Skip to content

docs.md

Latest commit

 

History

History
211 lines (137 loc) · 8.99 KB

docs.md

File metadata and controls

211 lines (137 loc) · 8.99 KB
Raw

Table of Contents

Types

API

Timezone Handling

All dates are interpreted in German timezone (Europe/Berlin).

The library automatically converts any Date object to German timezone before checking holidays. This ensures correct behavior regardless of your server's timezone setting.

Examples

// All of these correctly identify May 29, 2025 as Christi Himmelfahrt:

// UTC timestamp that is May 29 in German timezone
isHoliday(new Date('2025-05-28T23:00:00Z'), 'ALL'); // true (01:00 May 29 in Germany)

// Explicit German timezone
isHoliday(new Date('2025-05-29T00:00:00+02:00'), 'ALL'); // true

// UTC date at noon (timezone-safe)
isHoliday(new Date(Date.UTC(2025, 4, 29, 12, 0, 0)), 'ALL'); // true

Best Practices

  1. For current date checks: new Date() works perfectly
  2. For specific dates: Use ISO strings with timezone or Date.UTC() at noon
  3. For server-side code: Use Date.UTC(year, month, day, 12, 0, 0) for guaranteed timezone independence

Types

HolidayType

Type: ("NEUJAHRSTAG" | "HEILIGEDREIKOENIGE" | "KARFREITAG" | "OSTERSONNTAG" | "OSTERMONTAG" | "TAG_DER_ARBEIT" | "CHRISTIHIMMELFAHRT" | "MARIAHIMMELFAHRT" | "PFINGSTSONNTAG" | "PFINGSTMONTAG" | "FRONLEICHNAM" | "DEUTSCHEEINHEIT" | "REFORMATIONSTAG" | "ALLERHEILIGEN" | "BUBETAG" | "ERSTERWEIHNACHTSFEIERTAG" | "ZWEITERWEIHNACHTSFEIERTAG" | "WELTKINDERTAG" | "WELTFRAUENTAG" | "AUGSBURGER_FRIEDENSFEST")

Region

Type: ("BW" | "BY" | "BE" | "BB" | "HB" | "HE" | "HH" | "MV" | "NI" | "NW" | "RP" | "SL" | "SN" | "ST" | "SH" | "TH" | "BUND" | "AUGSBURG" | "ALL")

As defined here: https://de.wikipedia.org/wiki/Land_(Deutschland)#Amtliche_bzw._Eigenbezeichnungen

The difference between BUND and ALL is defined as follows:

  • "ALL" refers to every holiday which is valid in at least one region. So a holiday that only applies to one state will be included.
  • "BUND" refers to holidays that are valid in every region ("bundesweit"). So a holiday that only applies to one state will not be included.

Holiday

Type: {name: HolidayType, date: Date, dateString: string, regions: Array<Region>, translate: function (lang: string?): string | undefined, equals: function (date: Date): boolean, getNormalizedDate: function (): number}

Properties

  • name HolidayType - The holiday identifier
  • date Date - The date (at noon UTC)
  • dateString string - The date as string in German timezone (YYYY-MM-DD format)
  • regions Array<Region> - Regions where this holiday is valid
  • translate function (lang: string?): string | undefined - Get translated name
  • equals function (date: Date): boolean - Compare with another date (in German timezone)
  • getNormalizedDate function (): number - Get UTC timestamp normalized to midnight

allHolidays

Type: Array<HolidayType>

allRegions

Type: Array<Region>

TranslationTable

Map of HolidayType to translation string.

Type: {}

API

addTranslation()

Adds a translation for the holidays (e.g. English). This also allows overriding the German names. Hint: Interpolates German for missing translations

Parameters

  • isoCode string of the new language
  • newTranslation TranslationTable map of {HolidayType} to translation stringg

setLanguage()

Set a language to default language

Parameters

getLanguage()

Get currently set language

Returns string

isSunOrHoliday()

Checks if a specific date is sunday or holiday in German timezone.

Parameters

  • date Date - Any Date object (will be converted to German timezone)
  • region Region

Returns boolean

Example

// Check if today is Sunday or a holiday in Bavaria
isSunOrHoliday(new Date(), 'BY');

isHoliday()

Check if a specific date is a holiday in German timezone.

Parameters

  • date Date - Any Date object (will be converted to German timezone)
  • region Region two character Region code

Returns boolean

Example

// Check if Christmas is a holiday
isHoliday(new Date(Date.UTC(2025, 11, 25, 12)), 'BY'); // true

// Check with ISO string
isHoliday(new Date('2025-12-25T12:00:00+01:00'), 'BY'); // true

getHolidayByDate()

Get the holiday object for a specific date (in German timezone).

Parameters

  • date Date - Any Date object (will be converted to German timezone)
  • region Region (optional, default 'ALL')

Returns (Holiday | void)

Example

const holiday = getHolidayByDate(new Date(Date.UTC(2025, 11, 25, 12)), 'BY');
console.log(holiday?.name); // 'ERSTERWEIHNACHTSFEIERTAG'
console.log(holiday?.translate('de')); // 'Erster Weihnachtsfeiertag'

isSpecificHoliday()

Check if a date is a specific holiday.

Parameters

  • date Date - Any Date object (will be converted to German timezone)
  • holidayName HolidayType
  • region Region (optional, default 'ALL')

Returns boolean

Example

// Check if May 29, 2025 is Christi Himmelfahrt
isSpecificHoliday(new Date(Date.UTC(2025, 4, 29, 12)), 'CHRISTIHIMMELFAHRT'); // true

getHolidays()

Returns all holidays of a year in a Region.

Parameters

Returns Array<Holiday>

Example

const holidays = getHolidays(2025, 'BY');
holidays.forEach(h => {
  console.log(`${h.dateString}: ${h.translate('de')}`);
});