Almanac

Plain-English dates that know every market holiday.

Upcoming closures

Dates that respect the trading calendar

Almanac is a small TypeScript library that turns a person's date phrase into an actual date. It treats "business day" as a day the market is open, not just any weekday. Type "3 business days after Thanksgiving" and it counts forward through the NYSE calendar, skipping the weekend and any holiday it lands on, then hands back the real date.

Most natural-language date libraries parse the words but treat a business day as "not Saturday or Sunday." That breaks the moment a market holiday appears: the NYSE is closed on Good Friday, on Juneteenth, and on the day it observes a holiday that fell on a weekend. Almanac resolves every phrase through a calendar, so holiday awareness is the default, not an add-on you wire up later.

Phrases it understands

next trading day: the next day the market is open

the trading day before Christmas: holiday-relative, either direction

3 business days after Thanksgiving: business-day math off a holiday

in 2 weeks or in 10 days: plain calendar offsets

next Friday or last Monday: weekday references

How to use it

Import parse and the built-in nyseCalendar, then call parse(phrase, calendar). It returns { ok: true, date } when it understands the phrase, or { ok: false, reason } when it does not. It never throws, so a form or a batch job can treat "didn't understand that" as data. Need a different market or a company holiday list? Build a ListCalendar from your own dates and pass it in; every phrase resolves against it with no NYSE-specific code path.

FAQ

Which holidays does it know about?

NYSE full-closure days for 2024 through 2027, already adjusted for weekend observance (a holiday on a Saturday is observed the preceding Friday). Weekends are always recognized; extend the list to cover more years.

Can I use a calendar other than the NYSE?

Yes. The calendar is a plain interface you inject. Build a ListCalendar from any exchange or internal holiday list and the parser uses it directly.

Is this a full natural-language parser?

No, and it does not pretend to be. It recognizes a fixed, documented set of phrase shapes, the ones listed above. Anything it does not recognize comes back as ok: false with a reason, never a wrong guess.

What happens with garbage input?

You get a structured failure result. Empty strings, unknown holidays, and out-of-range date math all return ok: false. An oversized business-day count is rejected before any calendar walk, so the page never hangs.

Does it have runtime dependencies?

None. The library is standard-library TypeScript, so there is no separate parser or date package to fall out of sync with the calendar.