@smartput/holiday

Which holiday a phrase names, and when it falls.

A tokenising scorer over the date-holidays rule table, and nothing else — no kinds, no values, no Decimal, no engine. That isolation is what lets @smartput/datetime reach it from a subpath instead of its root.

It is a package rather than a file because of its weight: ~1.5 MB bundled, six times the T0 gazetteer. As a plain dependency of datetime it would charge every consumer of today + 3 d a megabyte for a feature they did not ask for.

Setup

npm add @smartput/holiday

Example

import { findHoliday, holidaysFor } from "@smartput/holiday";

findHoliday("christmas")?.[0]?.name  // "New Year's Day"
holidaysFor(2026, "US").length       // 23
holidaysFor(2026, "US")[0]?.name     // "New Year's Day"

No @smartput dependency at all — it knows nothing about kinds, values or the engine, which is what lets @smartput/datetime reach it from a subpath instead of from its root.

Entry points

| Import | Contents | | --- | --- | | @smartput/holiday | The package root. | | @smartput/holiday/types | Type declarations only — erased at runtime. |

Runtime exports

Type-only exports are erased and do not appear here.

DEFAULT_COUNTRY · findHoliday · holidayCountries · holidaysFor

Dependencies

• date-holidays

What it costs

Ceilings, not measurements. bun run check-size bundles each entry with bun build --minify and fails if a row crosses its ceiling or drops more than 30 % below it — a budget that is only an upper bound reports a vanished graph as a triumph.

| Import | Minified | Gzipped | | --- | --- | --- | | holiday root (the rule table, alone) | ≤ 1430 kB | ≤ 236 kB |

Generated by scripts/gen-readmes.ts — run bun run docs:readmes. Every output above was produced by running the line beside it. The full page, with live demos, is docs/packages/holiday.md.