holidayfyi

Pure TypeScript holiday date engine for developers. Calculate Easter dates (Western and Orthodox), find nth weekdays in a month (e.g., "3rd Monday of January"), count days until a target date, find next occurrences of fixed holidays, and check weekend/weekday status -- all with zero dependencies.

Try the interactive tools at holidayfyi.com -- holiday calendar, countdown timers, and date calculators.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Easter Calculation (Computus Algorithm)
  • Finding Nth Weekdays
  • Days Until & Next Occurrence
• API Reference
• TypeScript Types
• Features
• Learn More About Holidays
• Also Available for Python
• FYIPedia Developer Tools
• License

Install

npm install holidayfyi

Works in Node.js, Deno, Bun, and browsers (ESM).

Quick Start

import { easterWestern, easterOrthodox, nthWeekdayOfMonth, daysUntil, WEEKDAY } from "holidayfyi";

// Easter 2026
const easter = easterWestern(2026);
console.log(easter.toISOString().slice(0, 10));  // "2026-04-05"

const orthodox = easterOrthodox(2026);
console.log(orthodox.toISOString().slice(0, 10)); // "2026-04-12"

// MLK Day 2026: 3rd Monday of January
const mlk = nthWeekdayOfMonth(2026, 1, WEEKDAY.MONDAY, 3);
console.log(mlk.toISOString().slice(0, 10));  // "2026-01-19"

// Thanksgiving 2026: 4th Thursday of November
const thanksgiving = nthWeekdayOfMonth(2026, 11, WEEKDAY.THURSDAY, 4);
console.log(thanksgiving.toISOString().slice(0, 10));  // "2026-11-26"

// Days until Easter
const days = daysUntil(easter);
console.log(days);  // days remaining

What You Can Do

Easter Calculation (Computus Algorithm)

Computing Easter's date is one of the oldest algorithms still in use. The Anonymous Gregorian algorithm (used since 1582) uses modular arithmetic to find the first Sunday after the first ecclesiastical full moon after March 21.

The algorithm involves 10 intermediate variables computed entirely through integer division and modulo operations:

a = year % 19                    (Metonic cycle position)
b = year / 100, c = year % 100   (Century)
d = b / 4, e = b % 4             (Leap century correction)
f = (b + 8) / 25                 (Synchronization correction)
g = (b - f + 1) / 3              (Epact correction)
h = (19a + b - d - g + 15) % 30  (Paschal full moon)
i = c / 4, k = c % 4             (Leap year correction)
el = (32 + 2e + 2i - h - k) % 7  (Sunday correction)
m = (a + 11h + 22*el) / 451      (Lunar/solar correction)
month = (h + el - 7m + 114) / 31
day = (h + el - 7m + 114) % 31 + 1

For Orthodox Easter, the Meeus Julian algorithm is used instead, and 13 days are added to convert from the Julian to the Gregorian calendar. This offset accounts for the accumulated drift between the two calendars.

Easter determines the dates of many other moveable feasts in the Christian calendar:

| Holiday | Rule | 2026 Date | |---------|------|----------| | Shrove Tuesday | 47 days before Easter | Feb 17 | | Ash Wednesday | 46 days before Easter | Feb 18 | | Palm Sunday | 7 days before Easter | Mar 29 | | Good Friday | 2 days before Easter | Apr 3 | | Easter Sunday | First Sunday after Paschal full moon | Apr 5 | | Ascension Day | 39 days after Easter | May 14 | | Whit Sunday (Pentecost) | 49 days after Easter | May 24 |

import { easterWestern, easterOrthodox } from "holidayfyi";

// Western Easter dates for the next several years
for (const year of [2026, 2027, 2028, 2029, 2030]) {
  const date = easterWestern(year);
  console.log(`${year}: ${date.toISOString().slice(0, 10)}`);
}

// Orthodox Easter -- typically 1-5 weeks after Western Easter
const western = easterWestern(2026);
const orthodox = easterOrthodox(2026);
const diffDays = Math.round((orthodox.getTime() - western.getTime()) / 86400000);
console.log(`Difference: ${diffDays} days`);  // 7

Learn more: Easter Calculator · Computus Algorithm · Holiday Calendar

Finding Nth Weekdays

Many public holidays are defined as the "nth weekday of a month" rather than a fixed date. This pattern is especially common in the United States, Canada, and Australia.

import { nthWeekdayOfMonth, WEEKDAY } from "holidayfyi";

// US Federal holidays that use "nth weekday of month" rules:
const mlkDay = nthWeekdayOfMonth(2026, 1, WEEKDAY.MONDAY, 3);        // MLK Day
const presidentsDay = nthWeekdayOfMonth(2026, 2, WEEKDAY.MONDAY, 3);  // Presidents' Day
const memorialDay = nthWeekdayOfMonth(2026, 5, WEEKDAY.MONDAY, -1);   // Last Monday of May
const laborDay = nthWeekdayOfMonth(2026, 9, WEEKDAY.MONDAY, 1);       // Labor Day
const columbusDay = nthWeekdayOfMonth(2026, 10, WEEKDAY.MONDAY, 2);   // Columbus Day
const thanksgiving = nthWeekdayOfMonth(2026, 11, WEEKDAY.THURSDAY, 4); // Thanksgiving

// Use -1 for "last occurrence"
const lastFriday = nthWeekdayOfMonth(2026, 3, WEEKDAY.FRIDAY, -1);

Learn more: Holiday Calendar · US Federal Holidays · Date Calculator

Days Until & Next Occurrence

import { daysUntil, nextOccurrence, isWeekend, getWeekdayName } from "holidayfyi";

// Count days until a specific date
const christmas = new Date(Date.UTC(2026, 11, 25));
console.log(daysUntil(christmas));  // days until Christmas 2026

// Find the next occurrence of a fixed-date holiday
const nextChristmas = nextOccurrence(12, 25);
console.log(nextChristmas.toISOString().slice(0, 10));  // "2026-12-25" or "2027-12-25"

const nextNewYear = nextOccurrence(1, 1);
console.log(nextNewYear.toISOString().slice(0, 10));

// Weekend and weekday checks
console.log(isWeekend(christmas));          // true or false
console.log(getWeekdayName(christmas));     // "Friday"

Learn more: Countdown Timers · Country Holiday Calendars · REST API Docs

API Reference

Easter Dates

| Function | Description | |----------|-------------| | easterWestern(year) -> Date | Western (Gregorian) Easter date using the Anonymous Gregorian algorithm | | easterOrthodox(year) -> Date | Orthodox Easter date (Julian algorithm + 13-day Gregorian offset) |

Nth Weekday

| Function | Description | |----------|-------------| | nthWeekdayOfMonth(year, month, wd, n) -> Date | Find the nth occurrence of a weekday in a month (n=-1 for last) |

Days Until & Next Occurrence

| Function | Description | |----------|-------------| | daysUntil(targetDate, fromDate?) -> number | Count days until a target date | | nextOccurrence(fixedMonth, fixedDay, fromDate?) -> Date | Next occurrence of a fixed-date holiday (this year or next) |

Weekend & Weekday

| Function | Description | |----------|-------------| | isWeekend(date) -> boolean | Check if a date falls on Saturday or Sunday | | getWeekdayName(date) -> string | English weekday name (e.g., "Monday", "Friday") |

Constants

| Export | Description | |--------|-------------| | WEEKDAY | Weekday constants: MONDAY (0), TUESDAY (1), ..., SUNDAY (6) |

TypeScript Types

import { WEEKDAY } from "holidayfyi";
import type { Weekday } from "holidayfyi";

Features

• Easter calculation: Western (Anonymous Gregorian) and Orthodox (Meeus Julian + 13-day offset)
• Nth weekday finder: "3rd Monday of January", "last Friday of March", etc.
• Days-until counting: Countdown to any target date
• Next occurrence: Find the next time a fixed-date holiday occurs
• Weekend/weekday checks: Simple boolean check and English weekday names
• Python weekday convention: 0=Monday, 6=Sunday (matches Python's datetime.weekday())
• UTC-based: All dates at midnight UTC to avoid timezone issues
• Zero dependencies: Pure TypeScript, no runtime deps
• Type-safe: Full TypeScript with strict mode
• Tree-shakeable: ESM with named exports
• Fast: All computations under 1ms

Learn More About Holidays

• Browse: Holiday Calendar · Countries · Today
• Tools: Date Calculator · Easter Calculator
• API: REST API Docs · OpenAPI Spec
• Python: PyPI Package

Also Available for Python

pip install holidayfyi

See the Python package on PyPI.

FYIPedia Developer Tools

Part of the FYIPedia open-source developer tools ecosystem.

| Package | PyPI | npm | Description | |---------|------|-----|-------------| | colorfyi | PyPI | npm | Color conversion, WCAG contrast, harmonies -- colorfyi.com | | emojifyi | PyPI | npm | Emoji encoding & metadata for 3,953 emojis -- emojifyi.com | | symbolfyi | PyPI | npm | Symbol encoding in 11 formats -- symbolfyi.com | | unicodefyi | PyPI | npm | Unicode lookup with 17 encodings -- unicodefyi.com | | fontfyi | PyPI | npm | Google Fonts metadata & CSS -- fontfyi.com | | distancefyi | PyPI | npm | Haversine distance & travel times -- distancefyi.com | | timefyi | PyPI | npm | Timezone ops & business hours -- timefyi.com | | namefyi | PyPI | npm | Korean romanization & Five Elements -- namefyi.com | | unitfyi | PyPI | npm | Unit conversion, 220 units -- unitfyi.com | | holidayfyi | PyPI | npm | Holiday dates & Easter calculation -- holidayfyi.com | | cocktailfyi | PyPI | -- | Cocktail ABV, calories, flavor -- cocktailfyi.com | | fyipedia | PyPI | -- | Unified CLI: fyi color info FF6B35 -- fyipedia.com | | fyipedia-mcp | PyPI | -- | Unified MCP hub for AI assistants -- fyipedia.com |

License

MIT