Our Calendar Methodology
Our calendar engine combines deterministic astronomical and religious algorithms with continuous verification against primary government legislation and statutory decrees.
1. Deterministic Multi-Calendar Engine
Public holidays worldwide follow diverse mathematical and cultural systems. Our pipeline models four primary calendar mechanisms:
Fixed Gregorian Dates: National days and historical anniversaries falling on fixed calendar dates (e.g. July 4, January 1).
Astronomical & Equinoctial Computations: Solstices, equinoxes, and solar terms calculated using precise celestial coordinates.
Lunar & Lunisolar Calendars: Islamic Hijri calendars, Chinese Lunar New Year, Diwali, and Buddhist observances calculated via standard moon-phase visibility models and verified against national religious authority proclamations.
Computus Algorithms: Western (Gregorian) and Eastern Orthodox (Julian) Easter cycles and their dependent moving feasts (Good Friday, Ascension, Whit Monday, Corpus Christi).
2. Statutory Legislation & Official Decrees
Mathematical models provide raw dates, but statutory laws dictate legal rest. We cross-reference every calculated occurrence against primary legal instruments: national labor codes, parliamentary acts, official state gazettes, and executive orders.
Where standard libraries omit statutory reforms or use outdated rules, our manual override registry (data/holiday-overrides.ts) enforces verified statutory corrections.
3. Substitute Days & Weekend Shift Modeling
One of the most critical aspects of holiday planning is determining what happens when a statutory holiday coincides with a weekend.
Our engine systematically encodes national compensatory rules: automatic shifts to the following Monday (e.g. UK, Australia, US), shifts to the preceding Friday, or next available working day rules (e.g. Albania, South Africa), ensuring accurate working day counts.
4. Continuous Legislative Audits & Regression Testing
Every country calendar is subject to automated snapshot validation (npm run holidays:validate:snapshots) to prevent regression, while our continuous monitoring pipeline tracks newly enacted laws, one-off bank holidays, and royal or presidential decrees worldwide.