Registry / serialization / date-holidays-parser

date-holidays-parser

JSON →
library3.4.7jsnpmunverified

date-holidays-parser is a JavaScript and TypeScript library designed to parse and calculate worldwide holidays, acting as the rule-engine backbone for the `date-holidays` library. It provides functionalities to determine public, bank, and observance holidays for various countries, states, and regions, adhering to ISO 3166-2 standards. The library is currently at version 3.4.7 and appears to be actively maintained, though no explicit release cadence is stated. Key features include timezone consideration for holiday checks, support for substitute days, multi-language holiday names, and the ability to define custom holidays. It also uniquely integrates support for Islamic, Hebrew, and Chinese calendars, though it cautions about potential inaccuracies with Islamic dates due to moon sighting dependencies. This parser is distinct in its use of a custom grammar for day calculations, enabling precise and flexible holiday determination across diverse cultural and legal frameworks.

npm install date-holidays-parser
INSTALL
IMPORT
SIG · DATE-HOLIDAYS-PARS
D
date-holidays-parser
serializationjavascriptv3.4.7
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Holidays
✓ import Holidays from 'date-holidays-parser';
✗ const Holidays = require('date-holidays-parser');
While CommonJS `require` syntax is supported for older Node.js environments, modern TypeScript/ESM projects should use the default ESM import. The library ships with TypeScript types.
holidayData
✓ import holidayData from 'date-holidays/data/holidays.json';
✗ const holidayData = require('date-holidays/data/holidays.json');
Starting with `date-holidays-parser` v3 (which aligns with `date-holidays` v3), holiday data must be explicitly imported from the `date-holidays` package. Ensure `date-holidays` is installed as a dependency to access this path.
Holiday (type)
✓ import type { Holiday } from 'date-holidays-parser';
✗ import { Holiday } from 'date-holidays-parser';
For type-only imports in TypeScript, use the `import type` syntax. This helps ensure that no accidental runtime code is generated, especially when `isolatedModules` is enabled.

Initializes the Holidays parser with global data, sets a specific locale (US, LA, NO), retrieves holidays for a year, and checks specific dates for holiday status, demonstrating timezone awareness and language setting.

import Holidays from 'date-holidays-parser'; import holidayData from 'date-holidays/data/holidays.json'; // Requires 'date-holidays' to be installed // Initialize the parser with the holiday data rules const hd = new Holidays(holidayData); // Set locale to US, Louisiana, New Orleans for specific holiday rules hd.init('US', 'la', 'no'); console.log('Supported countries (e.g., US):', hd.getCountries().US); console.log('Supported states for US (e.g., LA):', hd.getStates('US').la); // Get all holidays for a specific year const holidays2016 = hd.getHolidays(2016); console.log(`\nHolidays for 2016 (first 3 entries):`); holidays2016.slice(0, 3).forEach(h => { console.log(`- ${h.name} on ${h.date} (type: ${h.type})`); }); // Check if a specific date is a holiday, respecting timezones const newYearsDay2016CST = new Date('2016-01-01T12:00:00-06:00'); // Jan 1st, 2016, 12 PM CST const notAHolidayDate = new Date('2016-02-01T12:00:00-06:00'); // Feb 1st, 2016, 12 PM CST console.log('\nChecking New Year\'s Day 2016 (CST):', hd.isHoliday(newYearsDay2016CST) ? 'Is a holiday' : 'Not a holiday'); console.log('Checking Feb 1st 2016 (CST):', hd.isHoliday(notAHolidayDate) ? 'Is a holiday' : 'Not a holiday'); // Example of a specific holiday check (Mardi Gras for New Orleans in 2016 was Feb 9th) const mardiGras2016CST = new Date('2016-02-09T10:00:00-06:00'); console.log('Checking Mardi Gras 2016 (CST):', hd.isHoliday(mardiGras2016CST) ? 'Is a holiday' : 'Not a holiday'); // Demonstrate setting language hd.setLanguage('de'); // Set language to German const newYearsDayGerman = hd.getHolidays(2016).find(h => h.name.includes('Neujahrstag')); console.log('\nNew Year\'s Day in German:', newYearsDayGerman?.name || 'Not found');
Debug
Known issues
breakingStarting with `date-holidays-parser` v3 (which aligns with `date-holidays` v3), the holiday data (`holidays.json`) is no longer bundled directly with the parser library. You must explicitly install and import `date-holidays` to provide the data.
fix
Install `date-holidays` (`npm install date-holidays`) and import the data using `import holidayData from 'date-holidays/data/holidays.json';` before initializing `Holidays`.
affects: >=3.0.0
breaking`date-holidays-parser` v3 and above, following `date-holidays` v3 requirements, mandates Node.js version 12 or higher. Older Node.js environments are not supported.
fix
Upgrade your Node.js environment to version 12.0.0 or greater.
affects: >=3.0.0
gotchaIslamic calendar dates are explicitly noted as potentially inaccurate, as they are subject to the actual sighting of the moon, which cannot be perfectly predicted algorithmically. This limitation is inherent to the nature of Islamic calendar determination.
fix
For critical applications requiring precise Islamic dates, manual verification or consultation with authoritative sources is recommended as algorithmic calculations provide an approximation.
affects: >=1.0.0
gotchaWhen using `isHoliday()`, ensure the `Date` object passed is timezone-aware, especially if working with different timezones. The library considers timezones for holiday checks, and an incorrectly constructed `Date` object (e.g., a local time string interpreted as UTC) can lead to inaccurate results.
fix
Construct `Date` objects using ISO 8601 strings with explicit timezone offsets (e.g., `new Date('YYYY-MM-DDTHH:mm:ss-05:00')`) or use UTC constructors, and be mindful of your environment's default `Date` object behavior.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use CommonJS `require()` syntax in an ES module environment where `require` is not globally available.
fix
Convert `require('date-holidays-parser')` to `import Holidays from 'date-holidays-parser';` and `require('date-holidays/data/holidays.json')` to `import holidayData from 'date-holidays/data/holidays.json';`.
TypeError: Cannot read properties of undefined (reading 'holidays')
The `Holidays` constructor was called without valid holiday data. This typically happens if `holidayData` from `date-holidays/data/holidays.json` was not correctly imported, or the `date-holidays` package is missing.
fix
Ensure `date-holidays` is installed (`npm install date-holidays`) and that `import holidayData from 'date-holidays/data/holidays.json';` is correctly loading the data before passing it to `new Holidays(holidayData)`.
No holidays returned for a specified country/state/region.
The `init()` method might not have been called, or incorrect country, state, or region codes were provided, or there are genuinely no defined holidays for that specific locale in the provided data.
fix
Verify that `hd.init('COUNTRY', 'STATE', 'REGION')` is called with correct ISO 3166-2 codes. Use methods like `hd.getCountries()`, `hd.getStates(country)`, or `hd.getRegions(country, state)` to confirm supported locales and their exact codes.
Upgrade
Version history
3.4.7latest on npm
Audit
Dependencies
date-holidaysrequiredProvides the necessary holiday data (`holidays.json`) that the parser consumes to perform calculations. It is an essential runtime peer dependency.
Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources