Bodu.Globalization.Calendar 1.3.0

Bodu.Globalization.Calendar

API stability - Stable. The public API surface is committed: breaking changes are reserved for a major-version bump per SemVer, except a deliberate break that is recorded in the release notes and in the package's CompatibilitySuppressions.xml. See versioning and support.

A resource-driven notable-date (holiday / observance) engine for .NET 8 and .NET 10. 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 and net10.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 - among them FixedDateStrategy, DayOfWeekInMonthStrategy, RelativeWeekdayInMonthStrategy, WeekdayNearDateStrategy, OffsetFromRuleStrategy, and AlgorithmDateStrategy. AlgorithmDateStrategy dispatches an <Algorithm key> to the bundled astronomical and calendrical calculators (Easter, the equinoxes and solar terms, lunar phases, the Hindu lunisolar festivals, Losar, and the gazetted Matariki table), which are internal and reached only through their keys. Custom algorithms implement INotableDateAlgorithm, register through NotableDateAlgorithmRegistry, and dispatch by key.

Range resolution

The Bodu.Globalization.Calendar.RangeResolution namespace defines how colliding occurrences collapse: ResolutionPolicy carries the duplicate policy the loader applies to a document's own declarations (DuplicatePolicy), the same-day and span collision and priority-direction rules (CollisionPolicy, PriorityDirection), the span that controls range inclusion (ObservedDateRangePolicy), the category precedence, and the working week, with INotableDateCollisionResolver as the custom extension point; each AdjustmentPolicy carries its own EmissionMode.

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

Building and testing

To build this package from source and run its tests, see CONTRIBUTING.md. The published vectors and corpora the tests hold it to are listed under conformance and test vectors.

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.