Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/commenthol/date-holidays-parser
parser for worldwide holidays
https://github.com/commenthol/date-holidays-parser
holidays parser worldwide
Last synced: 2 days ago
JSON representation
parser for worldwide holidays
- Host: GitHub
- URL: https://github.com/commenthol/date-holidays-parser
- Owner: commenthol
- License: isc
- Created: 2017-11-03T19:33:35.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-05-12T16:44:45.000Z (over 1 year ago)
- Last Synced: 2024-04-23T23:14:56.984Z (8 months ago)
- Topics: holidays, parser, worldwide
- Language: JavaScript
- Homepage:
- Size: 491 KB
- Stars: 45
- Watchers: 9
- Forks: 21
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# date-holidays-parser
> parser for world-wide holidays
[](https://www.npmjs.com/package/date-holidays-parser/)
[](https://github.com/commenthol/date-holidays-parser/actions/workflows/ci.yml?query=branch%3Amaster)
This module provides a parser for [date-holidays][] which does calculation of
holidays dates for various countries, states and regions by type while
considering the applicable timezone.
The features are:
- calculation of public, bank and observance holidays for different
countries, state, region, following ISO 3166-2
- consideration of timezones for holiday checks
- consideration of start and end time dependent on timezone
- substitute days
- multi-language support for all holiday names
- setting of custom holidays
- uses own grammar for calculation of days
- support for islamic calendar from 1970 to 2080 (*islamic dates might
not be correct as they are subject to the sighting of the moon)
- support for hebrew calendar from 1970 to 2100
- support for chinese calendar
Happy holidays!
## Table of Contents
* [Usage](#usage)
* [Holiday object](#holiday-object)
* [Dates](#dates)
* [Name](#name)
* [Types of holidays](#types-of-holidays)
* [API](#api)
* [Browser](#browser)
* [Data](#data)
* [Contribution and License Agreement](#contribution-and-license-agreement)
* [License](#license)
* [References](#references)
## Usage
```js
const data = require('date-holidays/data/holidays.json')
const Holidays = require('date-holidays-parser')
const hd = new Holidays(data)
// get supported countries
hd.getCountries()
/*>
{ AD: 'Andorra',
...
US: 'United States' }
*/
// get supported states e.g. for US
hd.getStates('US')
/*>
{ al: 'Alabama',
...
wy: 'Wyoming' }
*/
// get supported regions e.g. for US, Lousiana
hd.getRegions('US', 'la')
/*>
{ no: 'New Orleans' }
*/
// initialize holidays for US, Lousiana, New Orleans
hd.init('US', 'la', 'no')
// or using a new instance
hd = new Holidays('US', 'la', 'no')
// get all holidays for the year 2016
hd.getHolidays(2016)
/*>
[ { date: '2016-01-01 00:00:00',
start: Fri Jan 01 2016 00:00:00 GMT-0600 (CST),
end: Sat Jan 02 2016 00:00:00 GMT-0600 (CST),
name: 'New Year\'s Day',
type: 'public' },
...
{ date: '2016-11-24 00:00:00',
start: Thu Nov 24 2016 00:00:00 GMT-0600 (CST),
end: Fri Nov 25 2016 00:00:00 GMT-0600 (CST),
name: 'Thanksgiving Day',
type: 'public' },
...
{ date: '2016-12-26 00:00:00',
start: Mon Dec 26 2016 00:00:00 GMT-0600 (CST),
end: Tue Dec 27 2016 00:00:00 GMT-0600 (CST),
substitute: true,
name: 'Christmas Day (substitute day)',
type: 'public' } ]
*/
// check if date is a holiday while respecting timezones
hd.isHoliday(new Date('2016-02-09 00:00:00 GMT+0000'))
//> false
hd.isHoliday(new Date('2016-02-09 10:00:00 GMT-0600'))
/*>
{ date: '2016-02-09 00:00:00',
start: Tue Feb 09 2016 00:00:00 GMT-0600 (CST),
end: Wed Feb 10 2016 00:00:00 GMT-0600 (CST),
name: 'Mardi Gras',
type: 'public' }
*/
```
## Holiday object
`getHolidays()` as well as a matching `isHoliday()` call return either
a list or a single holiday object which consists of:
* {String} date - ISO Date String of (start)-date in local format
* {Date} start - start date of holiday
* {Date} end - end date of holiday
* {String} name - name of holiday using `language` (if available)
* {String} type - type of holiday `public|bank|school|optional|observance`
* {Boolean} substitute - (optional) if true holiday substitutes another holiday`
* {String} note - (optional) note`
### Dates
The `date` String represents the start date of the holiday in ISO
format without timezone. This string it intended for information only.
`start` and `end` are the start/end date of the holiday within the
selected timezone of the country, state, region.
### Name
The `name` names the holiday in the local language of the selected
country, state, region. The applied language(s) can be requested using
`getLanguages()`.
The language can be changed using the `setLanguages()` method. In case
that not translation is available a fall-back to the next given
language will be made. E.g. local language is "fr",
`setLanguages('nl')` was called. For all holidays where no dutch
translation is available the French version will be used instead.
All holiday names should support an English translation.
### Types of holidays
Currently the following type with their meaning are supported
type | meaning
----------- | ------------------------------------------
public | public holiday
bank | bank holiday, banks and offices are closed
school | school holiday, schools are closed
optional | majority of people take a day off
observance | optional festivity, no paid day off
Additionally a `note` field is sometimes available for further
clarification.
## API
See [Holidays API][] for further information.
## Browser
This project also runs in all modern browsers. See `./examples/browser`
Browser | Version | Notes
--- | --- | ---
Chrome | >=45 |
Firefox | >=45 |
Safari | >=10 |
Edge | >=13 |
IE | >=10 | needs polyfill `core-js/es6`
Please do not forget to set the correct charset!
```html
...
...
```
Testing was done with `zuul`. For local browser tests run `npm run zuul
-- --local 3000` and open .
requires manual install of
```
npm i zuul@3 browserify@10
```
## Data
All data for the holidays of the different countries is contained in
[`./data/holidays.json`](./data/holidays.json). For changing holiday
data edit the appropriate country in `./data/countries`. Any details on
structure and available grammar for holiday attribution is described in
[holidays.yaml specification][].
## Contribution and License Agreement
If you contribute code to this project, you are implicitly allowing your
code to be distributed under the ISC license. You are also implicitly
verifying that all code is your original work or correctly attributed
with the source of its origin and license.
## License
Copyright (c) 2015-present commenthol ([ISC License][])
See [LICENSE][] for more information.
## References
* [date-holidays][date-holidays]
* [date-holidays-ical][date-holidays-ical]
* [Holidays API][Holidays API]
* [holidays.yaml specification][holidays.yaml specification]
* [ISC License][ISC License]
* [LICENSE][LICENSE]
[LICENSE]: ./LICENSE
[holidays.yaml specification]: https://github.com/commenthol/date-holidays/docs/specification.md
[Holidays API]: https://github.com/commenthol/date-holidays-parser/blob/master/docs/Holidays.md
[date-holidays]: https://github.com/commenthol/date-holidays
[date-holidays-ical]: https://github.com/commenthol/date-holidays-ical
[ISC License]: http://opensource.org/licenses/ISC