{"id":13059,"library":"date-holidays-parser","title":"Worldwide Holiday Parser","description":"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.","status":"active","version":"3.4.7","language":"javascript","source_language":"en","source_url":"https://github.com/commenthol/date-holidays-parser","tags":["javascript","holidays","parser","world","typescript"],"install":[{"cmd":"npm install date-holidays-parser","lang":"bash","label":"npm"},{"cmd":"yarn add date-holidays-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add date-holidays-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the necessary holiday data (`holidays.json`) that the parser consumes to perform calculations. It is an essential runtime peer dependency.","package":"date-holidays","optional":false}],"imports":[{"note":"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.","wrong":"const Holidays = require('date-holidays-parser');","symbol":"Holidays","correct":"import Holidays from 'date-holidays-parser';"},{"note":"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.","wrong":"const holidayData = require('date-holidays/data/holidays.json');","symbol":"holidayData","correct":"import holidayData from 'date-holidays/data/holidays.json';"},{"note":"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.","wrong":"import { Holiday } from 'date-holidays-parser';","symbol":"Holiday (type)","correct":"import type { Holiday } from 'date-holidays-parser';"}],"quickstart":{"code":"import Holidays from 'date-holidays-parser';\nimport holidayData from 'date-holidays/data/holidays.json'; // Requires 'date-holidays' to be installed\n\n// Initialize the parser with the holiday data rules\nconst hd = new Holidays(holidayData);\n\n// Set locale to US, Louisiana, New Orleans for specific holiday rules\nhd.init('US', 'la', 'no');\n\nconsole.log('Supported countries (e.g., US):', hd.getCountries().US);\nconsole.log('Supported states for US (e.g., LA):', hd.getStates('US').la);\n\n// Get all holidays for a specific year\nconst holidays2016 = hd.getHolidays(2016);\nconsole.log(`\\nHolidays for 2016 (first 3 entries):`);\nholidays2016.slice(0, 3).forEach(h => {\n  console.log(`- ${h.name} on ${h.date} (type: ${h.type})`);\n});\n\n// Check if a specific date is a holiday, respecting timezones\nconst newYearsDay2016CST = new Date('2016-01-01T12:00:00-06:00'); // Jan 1st, 2016, 12 PM CST\nconst notAHolidayDate = new Date('2016-02-01T12:00:00-06:00');   // Feb 1st, 2016, 12 PM CST\n\nconsole.log('\\nChecking New Year\\'s Day 2016 (CST):', hd.isHoliday(newYearsDay2016CST) ? 'Is a holiday' : 'Not a holiday');\nconsole.log('Checking Feb 1st 2016 (CST):', hd.isHoliday(notAHolidayDate) ? 'Is a holiday' : 'Not a holiday');\n\n// Example of a specific holiday check (Mardi Gras for New Orleans in 2016 was Feb 9th)\nconst mardiGras2016CST = new Date('2016-02-09T10:00:00-06:00');\nconsole.log('Checking Mardi Gras 2016 (CST):', hd.isHoliday(mardiGras2016CST) ? 'Is a holiday' : 'Not a holiday');\n\n// Demonstrate setting language\nhd.setLanguage('de'); // Set language to German\nconst newYearsDayGerman = hd.getHolidays(2016).find(h => h.name.includes('Neujahrstag'));\nconsole.log('\\nNew Year\\'s Day in German:', newYearsDayGerman?.name || 'Not found');","lang":"typescript","description":"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."},"warnings":[{"fix":"Install `date-holidays` (`npm install date-holidays`) and import the data using `import holidayData from 'date-holidays/data/holidays.json';` before initializing `Holidays`.","message":"Starting 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js environment to version 12.0.0 or greater.","message":"`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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For critical applications requiring precise Islamic dates, manual verification or consultation with authoritative sources is recommended as algorithmic calculations provide an approximation.","message":"Islamic 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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';`.","cause":"Attempting to use CommonJS `require()` syntax in an ES module environment where `require` is not globally available.","error":"ReferenceError: require is not defined"},{"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)`.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'holidays')"},{"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.","cause":"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.","error":"No holidays returned for a specified country/state/region."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}