Holify

A powerful TypeScript library for calculating holidays from various countries. Inspired by Yasumi for PHP, Holify is calculation-driven, provider-based, and perfect for Next.js or JavaScript/TypeScript project.

Features

• Pure TypeScript with full type safety
• 42+ Countries Supported - Comprehensive coverage across all continents
• Calculation-driven - No database needed, holidays calculated on-the-fly
• Provider-based architecture - Easy to add new countries
• Multi-language support - Built-in translations in 30+ languages
• Powerful filtering - Filter by type, date range, and more
• Timezone aware - Proper handling of different timezones
• Framework agnostic - Works with Next.js, React, Node.js, etc.
• Tree-shakeable - Only bundle what you use
• Fully typed - Excellent IntelliSense support

Installation

npm install holify
# or
yarn add holify
# or
pnpm add holify

Quick Start

import { Holify } from 'holify';

// Get all holidays for USA in 2024
const usa2024 = Holify.create('US', 2024);
const holidays = usa2024.getHolidays();

console.log(holidays);
// Output: Array of Holiday objects with dates, names, and types

// Check if a specific date is a holiday
const date = new Date(2024, 6, 4); // July 4, 2024
console.log(usa2024.isHoliday(date)); // true (Independence Day)

// Get the name of a specific holiday
const independenceDay = usa2024.getHoliday('independenceDay');
console.log(independenceDay?.getName()); // "Independence Day"

Usage Examples

Basic Usage

import { Holify, HolidayType } from 'holify';

// Create a provider for a specific country and year
const uk2024 = Holify.create('GB', 2024);

// Get all holidays
const allHolidays = uk2024.getHolidays();

// Get a specific holiday
const christmas = uk2024.getHoliday('christmasDay');
console.log(christmas?.getName()); // "Christmas Day"
console.log(christmas?.date); // Date object
console.log(christmas?.type); // HolidayType.OFFICIAL or BANK

// Check if date is a holiday
const isHoliday = uk2024.isHoliday(new Date(2024, 11, 25)); // true

// Check if date is a working day
const isWorkingDay = uk2024.isWorkingDay(new Date(2024, 11, 25)); // false

Working with Locales

import { Holify } from 'holify';

// Create provider with German locale
const germany = Holify.create('DE', 2024, 'de');

const newYear = germany.getHoliday('newYearsDay');
console.log(newYear?.getName()); // "Neujahr"

// Get name in a different locale
console.log(newYear?.getNameInLocale('en')); // "New Year's Day"

Filtering Holidays

import { Holify, HolidayType, OfficialHolidaysFilter, BetweenDatesFilter } from 'holify';

const usa = Holify.create('US', 2024);

// Get only official holidays
const officialHolidays = usa.getHolidaysByType(HolidayType.OFFICIAL);

// Get holidays in a date range
const q1Holidays = usa.getHolidaysBetween(
  new Date(2024, 0, 1),
  new Date(2024, 2, 31)
);

// Using filter classes
const filter = new OfficialHolidaysFilter();
const filtered = filter.filter(usa.getHolidays());

// Combine filters
const betweenFilter = new BetweenDatesFilter(
  new Date(2024, 0, 1),
  new Date(2024, 5, 30)
);
const firstHalfYear = betweenFilter.filter(usa.getHolidays());

Next Working Day

import { Holify } from 'holify';

const provider = Holify.create('US', 2024);

// Get next working day after July 4th (Independence Day)
const startDate = new Date(2024, 6, 4);
const nextWorkingDay = provider.getNextWorkingDay(startDate);
console.log(nextWorkingDay); // July 5, 2024

// Get the 5th working day after a date
const fifthWorkingDay = provider.getNextWorkingDay(startDate, 5);

Static Methods

import { Holify } from 'holify';

// Check if a date is a holiday without creating a provider
const isHoliday = Holify.isHoliday('US', new Date(2024, 6, 4)); // true

// Check if a date is a working day
const isWorkingDay = Holify.isWorkingDay('US', new Date(2024, 6, 4)); // false

// Get next working day
const nextWorkingDay = Holify.getNextWorkingDay('US', new Date(2024, 6, 4));

// Get available providers
const providers = Holify.getAvailableProviders();
console.log(providers); // ['AR', 'AT', 'AU', 'BA', ...]

// Check if provider exists
const hasProvider = Holify.hasProvider('US'); // true

Using in Next.js

API Route (Next.js App Router)

// app/api/holidays/route.ts
import { Holify } from 'holify';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const country = searchParams.get('country') || 'US';
  const year = parseInt(searchParams.get('year') || new Date().getFullYear().toString());

  try {
    const provider = Holify.create(country, year);
    const holidays = provider.getHolidays().map(h => ({
      key: h.key,
      name: h.getName(),
      date: h.date.toISOString(),
      type: h.type,
    }));

    return NextResponse.json({ holidays });
  } catch (error) {
    return NextResponse.json({ error: 'Invalid country or year' }, { status: 400 });
  }
}

React Component

'use client';

import { Holify, Holiday } from 'holify';
import { useState, useEffect } from 'react';

export default function HolidayCalendar() {
  const [holidays, setHolidays] = useState<Holiday[]>([]);

  useEffect(() => {
    const provider = Holify.create('US', 2024);
    setHolidays(provider.getHolidays());
  }, []);

  return (
    <div>
      <h1>US Holidays 2024</h1>
      <ul>
        {holidays.map((holiday) => (
          <li key={holiday.key}>
            {holiday.getName()} - {holiday.date.toDateString()}
          </li>
        ))}
      </ul>
    </div>
  );
}

Server Component

// app/holidays/page.tsx
import { Holify } from 'holify';

export default function HolidaysPage() {
  const provider = Holify.create('US', 2024);
  const holidays = provider.getHolidays();

  return (
    <div>
      <h1>US Holidays 2024</h1>
      <ul>
        {holidays.map((holiday) => (
          <li key={holiday.key}>
            {holiday.getName()} - {holiday.date.toDateString()}
          </li>
        ))}
      </ul>
    </div>
  );
}

Available Providers

Holify supports 42 countries across all continents with comprehensive holiday calculations:

Americas (5)

• AR - Argentina
• BR - Brazil
• CA - Canada
• MX - Mexico
• US - United States

Europe (27)

• AT - Austria
• BE - Belgium
• BA - Bosnia and Herzegovina
• BG - Bulgaria
• HR - Croatia
• CZ - Czech Republic
• EE - Estonia
• FI - Finland
• FR - France
• DE - Germany
• GR - Greece
• HU - Hungary
• IE - Ireland
• IT - Italy
• LV - Latvia
• LT - Lithuania
• LU - Luxembourg
• NL - Netherlands
• NO - Norway
• PL - Poland
• PT - Portugal
• RO - Romania
• SK - Slovakia
• ES - Spain
• SE - Sweden
• CH - Switzerland
• GB or UK - United Kingdom

Middle East & Central Asia (5)

• GE - Georgia
• IR - Iran
• RU - Russia
• TR - Turkey
• UA - Ukraine

Asia-Pacific (4)

• AU - Australia
• JP - Japan
• NZ - New Zealand
• KR - South Korea

Africa (1)

• ZA - South Africa

Special Features by Country

• Japan: Complex equinox calculations, substitute holidays, bridge holidays
• South Korea: Lunar calendar holidays (Seollal, Chuseok) with pre-calculated dates
• Orthodox Countries (Bulgaria, Greece, Romania, Ukraine): Orthodox Easter calculations
• Australia/New Zealand: Mondayisation rules for weekend holidays
• Netherlands: Historical King's Day / Queen's Day logic
• Many countries: Year-based holiday additions/removals reflecting historical changes

Holiday Types

enum HolidayType {
  OFFICIAL = 'official',    // National/Federal holidays
  OBSERVANCE = 'observance', // Observance holidays
  SEASON = 'season',        // Seasonal holidays
  BANK = 'bank',           // Bank holidays
  OTHER = 'other',         // Other holidays
}

Creating Custom Providers

You can easily create your own holiday providers for countries not yet supported:

import { AbstractProvider, Holiday, HolidayType } from 'holify';

class Iceland extends AbstractProvider {
  public readonly id = 'IS';

  protected initialize(): void {
    // Add New Year's Day
    this.addHoliday(
      this.newYearsDay({
        en: "New Year's Day",
        is: 'Nýársdagur',
      })
    );

    // Add National Day (June 17)
    if (this.year >= 1944) {
      this.addHoliday(
        new Holiday(
          {
            key: 'nationalDay',
            date: new Date(this.year, 5, 17),
            names: {
              en: 'Icelandic National Day',
              is: 'Þjóðhátíðardagur Íslendinga',
            },
            type: HolidayType.OFFICIAL,
          },
          this.locale
        )
      );
    }

    // Add more holidays...
  }
}

// Register your custom provider
Holify.registerProvider('IS', Iceland);

// Use it
const iceland = Holify.create('IS', 2024);

Utility Functions

Holify provides useful calculation utilities:

import {
  calculateEaster,
  calculateGoodFriday,
  calculateEasterMonday,
  getNthWeekdayOfMonth,
  isLeapYear,
} from 'holify';

// Calculate Easter Sunday
const easter2024 = calculateEaster(2024);

// Get the 3rd Monday in January (MLK Day)
const mlkDay = getNthWeekdayOfMonth(2024, 0, 1, 3);

// Check if year is leap year
const isLeap = isLeapYear(2024); // true

API Reference

Holify Class

Holify.create(countryCode: string, year: number, locale?: string, timezone?: string): IProvider

Create a holiday provider for a specific country and year.

Holify.isHoliday(countryCode: string, date: Date, locale?: string, timezone?: string): boolean

Check if a date is a holiday.

Holify.isWorkingDay(countryCode: string, date: Date, locale?: string, timezone?: string): boolean

Check if a date is a working day.

Holify.getNextWorkingDay(countryCode: string, startDate: Date, workingDays?: number, locale?: string, timezone?: string): Date

Get the next working day.

Provider Interface

• getHolidays(): Map<string, Holiday> - Get all holidays as a Map
• getHolidays(): Holiday[] - Get all holidays as an array
• getHoliday(key: string): Holiday | undefined - Get a specific holiday
• isHoliday(date: Date): boolean - Check if a date is a holiday
• isWorkingDay(date: Date): boolean - Check if a date is a working day
• getNextWorkingDay(startDate: Date, workingDays?: number): Date - Get next working day
• getHolidaysByType(type: HolidayType): Holiday[] - Get holidays by type
• getHolidaysBetween(start: Date, end: Date): Holiday[] - Get holidays in date range

Holiday Class

• getName(): string - Get the holiday name in the display locale
• getNameInLocale(locale: string): string - Get the name in a specific locale
• isOn(date: Date): boolean - Check if the holiday falls on a specific date
• isBetween(start: Date, end: Date): boolean - Check if the holiday is between two dates
• isWeekend(): boolean - Check if the holiday falls on a weekend

Contributing

Contributions are welcome! To add a new country provider:

1. Create a new file in src/providers/
2. Extend AbstractProvider
3. Implement the initialize() method
4. Register it in src/Holify.ts
5. Add exports to src/index.ts

License

MIT

Acknowledgments

Inspired by Yasumi - the excellent PHP holiday library.

Author

Author

• E-Mail: [email protected]
• URL: https://www.patriceckhart.com