Bodu.Globalization.Calendar 1.0.0

Bodu.Globalization.Calendar

API stability — Stable. The public API surface is committed; breaking changes are reserved for a major-version bump per SemVer.

A resource-driven notable-date (holiday / observance) engine for .NET 8. Calendars are described as declarative, importable documents — concepts, rules, calculation strategies, adjustment policies, and resolution policies — that the engine resolves into concrete occurrences for a territory and date range. The package ships the calculation strategies, astronomical algorithms, range-resolution machinery, and working-day extensions; the regional holiday data ships in the companion Bodu.Globalization.Calendar.<Region> data packages.

Installation

dotnet add package Bodu.Globalization.Calendar

Targets net8.0.

Core model

Shared faith and civil catalogues (global-core, christian-western, christian-orthodox, catholic, global-islamic, global-jewish, global-buddhist, global-hindu, global-persian, …) are embedded in this core library and resolved through CommonNotableDateResources; the regional data packs import them via their region hubs.

Calculation strategies and algorithms

The Bodu.Globalization.Calendar.Algorithms namespace provides the IDateCalculationStrategy implementations — FixedDateStrategy, DayOfWeekInMonthStrategy, RelativeWeekdayInMonthStrategy, WeekdayNearDateStrategy, OffsetFromRuleStrategy, and AlgorithmDateStrategy — together with the astronomical / calendrical INotableDateAlgorithm engines: EasterCalculator, HinduLunarCalculator, LunarPhaseCalculator, SolarTermCalculator, TibetanLosarCalculator, and MatarikiCalendar. Custom algorithms register through NotableDateAlgorithmRegistry and dispatch by key.

Range resolution

The Bodu.Globalization.Calendar.RangeResolution namespace defines how overlapping and duplicate occurrences collapse: ResolutionPolicy carries the duplicate, collision, priority-direction, observed-range, and emission rules (CollisionPolicy, DuplicatePolicy, PriorityDirection, ObservedDateRangePolicy, EmissionMode), with INotableDateCollisionResolver as the custom extension point.

Working-day extensions

The Bodu.Extensions namespace adds working-day and notable-date helpers over DateOnly, DateTime, and DateTimeOffset:

using Bodu.Extensions;

bool isHoliday = date.IsNotableDate(service, territory);
DateOnly settle = date.AddWorkingDays(2, service, territory);
DateOnly next   = date.NextWorkingDay(service, territory);

Members include IsWorkingDay, IsWeekend, AddWorkingDays, NextWorkingDay / PreviousWorkingDay, SnapToWorkingDay, WorkingDaysBetween, the IsNotableDate / GetNotableDates / EnumerateNotableDates family, and fiscal-period helpers.

Related packages

Testing

Tests live in test/ as MSTest classes. Run tiers via the runsettings files at the solution root:

dotnet test Bodu.Globalization.Calendar/test/Bodu.Globalization.Calendar.Test.csproj --settings bvt.runsettings
dotnet test Bodu.Globalization.Calendar/test/Bodu.Globalization.Calendar.Test.csproj --settings regression.runsettings

The suite uses self-contained *KnownAnswerTests classes that pin Easter offsets, lunar/solar-term, and strategy-resolution results against published dates, with shared XML fixtures under test/Globalization.Calendar/Fixtures/.

Runnable samples

The repository ships offline, dotnet run-able sample projects for the calendar packages — holiday queries with subdivision shadowing, working-day arithmetic, authored company calendars, DI with live data reload, and custom algorithms with contract tests — under samples/Globalization.Calendar/.

License

MIT. © Bodu Pty. Ltd.