Compute the Holiday, Ship the Calendar: When Data Beats Code in a Date Engine
US federal holidays come from 11 rule lines, UK Easter from an algorithm, China from a 2020–2030 table. Why one date engine uses three strategies.
A date calculator that knows about holidays has a build-or-buy decision waiting on every single locale. The "buy" path is one npm install date-holidays away — about 60KB of bundled JavaScript that knows roughly every country on earth. The "build" path is to write the rules yourself, file by file, and pretend you do not need the other 180 countries. We picked build, finished in under 400 lines, and shipped zero dependencies. The interesting part is not that we built it. The interesting part is that the right implementation strategy is different for every region — and the rule for choosing between them is more general than holidays.
The rule, in one line: ship whichever is smaller — the algorithm plus its required runtime, or a precomputed table over the years your users actually care about.
The Easy Case: U.S. Federal Holidays Are Eleven Lines of Spec
The U.S. federal calendar has eleven holidays. Five are fixed dates (Jan 1, Jun 19, Jul 4, Nov 11, Dec 25). The other six are weekday-anchored: "third Monday of January" for MLK Day, "last Monday of May" for Memorial Day, and so on. The whole specification fits in a literal:
export const US_HOLIDAYS: readonly UsHolidaySpec[] = [
{ type: "fixed", month: 1, day: 1, nameKey: "newYear" },
{ type: "nth", month: 1, weekday: 1, n: 3, nameKey: "mlkDay" },
{ type: "nth", month: 2, weekday: 1, n: 3, nameKey: "presidentsDay" },
{ type: "last", month: 5, weekday: 1, nameKey: "memorialDay" },
{ type: "fixed", month: 6, day: 19, nameKey: "juneteenth" },
// …six more
];
The supporting algorithm is two small functions — nthWeekdayOfMonth and lastWeekdayOfMonth — totalling about 25 lines. Plug in any year between 1583 and 9999, get back the right dates. A precomputed table covering even just 1980-2050 would be 11 × 71 = 781 entries, every one of which would need to be hand-verified and updated whenever a holiday gets added (as Juneteenth was in 2021). The algorithm has none of that maintenance surface. Rules win, by a wide margin.
The Middle Case: Easter Needs a Real Algorithm
The U.K. calendar adds three holidays that pivot on Easter Sunday: Good Friday (Easter − 2), Easter Monday (Easter + 1), and indirectly the early-May bank holiday in years where the timing shifts. Easter is the famously tricky one — its date is defined as the first Sunday after the first ecclesiastical full moon on or after the spring equinox, which is a recipe for a lookup table unless you happen to know the Anonymous Gregorian Algorithm:
export function easterSunday(year: number): Date {
const a = year % 19;
const b = Math.floor(year / 100);
const c = year % 100;
const d = Math.floor(b / 4);
const e = b % 4;
const f = Math.floor((b + 8) / 25);
const g = Math.floor((b - f + 1) / 3);
const h = (19 * a + b - d - g + 15) % 30;
const i = Math.floor(c / 4);
const k = c % 4;
const l = (32 + 2 * e + 2 * i - h - k) % 7;
const m = Math.floor((a + 11 * h + 22 * l) / 451);
const month = Math.floor((h + l - 7 * m + 114) / 31);
const day = ((h + l - 7 * m + 114) % 31) + 1;
return new Date(year, month - 1, day);
}
It is sixteen lines of integer arithmetic, valid from 1583 onward (the year the Gregorian calendar was adopted), and it has been independently reverse-engineered enough times that you can find it on Wikipedia in a dozen languages. A table of Easter dates covering 1583-9999 would be 8417 rows. The function is, by any measure, the better artifact.
Japan's spring and autumn equinox holidays are the same story at smaller scale — a single floor expression accurate from 1900 to 2099:
function springEquinoxDay(year: number): number {
return Math.floor(
20.8431 + 0.242194 * (year - 1980) - Math.floor((year - 1980) / 4)
);
}
These cases are interesting because they look like they should be tables and are not. The cost of carrying the algorithm is one closed-form expression; the cost of carrying the table is hundreds of rows that have to come from somewhere.
The Hard Case: China Gets a Table, Bounded to 2020-2030
China's statutory calendar has seven holidays. Three are fixed by Gregorian date (New Year, Labour Day, National Day) and slot straight into the rules-based approach. The other four — Spring Festival, Qingming, Dragon Boat, and Mid-Autumn — are anchored to the Chinese lunar calendar, which means computing them at runtime requires a full lunisolar conversion: 24 solar terms, leap-month rules, jiazi cycles. The smallest serious lunar-calendar library on npm is ~30KB minified, and that is just to compute four dates per year.
The data we actually need, on the other hand, is microscopic. For 2020-2030, that is eleven years × four lunar holidays = 44 ISO date strings, plus a few bytes of envelope:
export const CN_LUNAR_BY_YEAR: Readonly<Record<number, CnLunarEntry>> = {
2020: { year: 2020, springFestival: "2020-01-25", qingming: "2020-04-04",
dragonBoat: "2020-06-25", midAutumn: "2020-10-01" },
// …ten more rows
2030: { year: 2030, springFestival: "2030-02-03", qingming: "2030-04-05",
dragonBoat: "2030-06-05", midAutumn: "2030-09-12" },
};
Total weight on the wire: under 1KB. The lunar library would have been 30× larger and still required us to keep the holiday spec table separately. Table wins, but it wins by being honest about its boundaries. The constants CN_PRESET_MIN = 2020 and CN_PRESET_MAX = 2030 are exported, the engine checks them, and the UI surfaces an isCnPresetOutOfRange warning when the user picks a year outside that window — instead of silently extrapolating, wrapping around, or returning blank.
Lunar Age: 201 Rows Cheaper Than a Runtime
The Age mode of the calculator has a separate small problem: 虚岁 (Chinese "nominal age"), which counts a person as 1 sui at birth and adds 1 on every Spring Festival. To compute it you need to know whether a given Gregorian date falls before or after that year's Spring Festival. Same situation as before — you can either ship a lunar runtime or ship the Spring Festival dates as a table:
export const SPRING_FESTIVAL: Readonly<Record<number, string>> = {
1900: "01-31", 1901: "02-19", 1902: "02-08", 1903: "01-29", 1904: "02-16",
// …201 rows total, through 2100
};
201 entries, two-byte values, sourced from the Hong Kong Observatory's published lunisolar tables. About 2KB shipped. The age computation itself is one subtraction:
export function lunarAge(birth: Date, asOf: Date): number | null {
// …range check elided
const a = lunarYearOf(birth);
const b = lunarYearOf(asOf);
if (a === null || b === null) return null;
return b - a + 1;
}
Notice the | null in the return type. When the input year is outside 1900-2100, we return null and the UI shows errors.lunarOutOfRange. We do not silently extrapolate the table, because extrapolating a lunar calendar from a Gregorian sequence is exactly the kind of "almost works" behaviour that produces a one-year-off answer two decades from now and an angry support email.
The Decision Rule, Generalised
Three holidays engines, one design rule:
- U.S. / fixed + nth-weekday holidays. Pure arithmetic, no calendar runtime, infinite year range. Algorithm easily smaller than any table that competes.
- U.K. Easter / Japan equinoxes. Closed-form mathematical algorithm, no runtime dependencies, bounded only by the formula's accuracy window (1583+ for Easter, 1900-2099 for equinox). Still smaller than a table.
- China lunar holidays / 虚岁. Algorithm requires a multi-kilobyte lunisolar runtime, table for the useful year range fits in ~3KB total. Table wins, but only with explicit min/max bounds and a surfaced error outside them.
It is the same rule that decides whether to ship a font subset or the whole file, or whether to compile a regex at startup or precompute its matches at build time. The variable that changes is "size of the runtime needed to compute the answer." When that runtime is comparable to a sensible precomputed table, run it. When it is much larger than a table covering the years your users will actually pick, ship the table — and admit, in the code, where it stops.
Try It Yourself
Open the Date Calculator, pick the Workdays mode, set the holiday preset to China, and try a date range that crosses February 2026. The Spring Festival on 2026-02-17 shows up from the table; the algorithm-driven holidays around it come from the rules engine; neither needed a single npm install. Switch to Age mode, type your birthday, and toggle 虚岁 — the answer comes out of 201 lines of pre-resolved Spring Festival dates and one subtraction.
The whole engine is around 400 lines and has zero dependencies.