swedish-holidays/README.md

Library for calculating the date of all swedish holidays for any given year.

# swedish-holidays

Library for calculating the date of all swedish holidays for any given year.

## How to install:

```shell
$ npm install swedish-holidays
```

## How to use:

```ts
import { getHolidays, getUpcomingHolidays, isHoliday, isPublicHoliday } from 'swedish-holidays';

// Get an array of all holidays for the current
const holidays = getHolidays();

// Get an array of all holidays for a specific year
const holidays2019 = getHolidays(2019);

// Get an array of all upcoming holidays
const upcoming = getUpcomingHolidays();

// Check if today is a holiday
const isItAHolidayToday = isHoliday();

// Or if you want to check a specific date
const isThisAHoliday = isHoliday(new Date('2019-12-24'));

// Check if today is a public holiday in Sweden (see https://www.riksdagen.se/sv/dokument-lagar/dokument/svensk-forfattningssamling/lag-1989253-om-allmanna-helgdagar_sfs-1989-253)
const isItAPublicHolidayToday = isPublicHoliday();

// Or if you want to check a specific date
const isThisAPublicHoliday = isPublicHoliday(new Date('2021-11-01'));
```

The result will always be an `Array` filled with JSON formatted holiday information including name and date.

```js
[
    {
        name: 'Julafton',
        date: '2019-12-24T00:00:00.000Z',
        day: 24,
        month: 12,
        year: 2019,
        isPublicHoliday: false,
    },
    {
        name: 'Juldagen',
        date: '2019-12-25T00:00:00.000Z',
        day: 25,
        month: 12,
        year: 2019,
        isPublicHoliday: true,
    },
    ...
]
```

When using `isHoliday` the result is `false` if the provided date is not a holiday, otherwise it is the holiday JSON object.

When using `isPublicHoliday` the result is `false` if the provided date is not a public holiday.

## Using holidays directly

Each holiday is exported and can be used individually.
`IHolidayOptions` is used to pass parameters to the constructor.
Both year and localization is supported.

For convenience holidays may also be imported using their swedish names.

```ts
import { MidsummerEve, Midsommarafton } from 'swedish-holidays';

// Both will be equal instances of the same class
const midsummerA = new MidsummerEve({ year: 2022 });
const midsummerB = new Midsommarafton({ year: 2022 });
```

## Localization

If you want the holiday names to be returned using a different language than the default (Swedish), use the `language` JSON object and modify it before passing it to the `getHolidays` function.

```js
const { language } = require('swedish-holidays');
const translation = { ...language };
// This value is 'Julafton' by default.
translation.christmasEve = 'Christmas Eve';

const holidays2019 = getHolidays(2019, translation);
// or if you want the current year
// supply a year that is 'falsy' e.g. undefined / null / 0 / false
const holidays = getHolidays(0, translation);
```

Or use the interface `IHolidayNames`

```ts
import { getHolidays, IHolidayNames } from 'swedish-holidays';

const language: IHolidayNames = {
    ...
    christmasEve: 'Christmas Eve',
    ...
}

const holidays2019 = getHolidays(2019, language);
```

## Limitations

This library can only return valid holidays for years between 1582 and 8702.

If an invalid year is requested, an error will be thrown.

## Supported Holidays

-   New Year's Day / Nyårsdagen
-   Twelfth Night / Trettondagsafton
-   Epiphany / Trettondedag jul
-   Maundy Thursday / Skärtorsdagen
-   Good Friday / Långfredagen
-   Holy Saturday / Påskafton
-   Easter Sunday / Påskdagen
-   Easter Monday / Annandag påsk
-   Walpurgis Night / Valborgsmässoafton
-   May First / Första maj
-   Ascension Day / Kristi himmelsfärdsdag
-   Swedish National Day / Sveriges nationaldag
-   Pentecost Eve / Pingstafton
-   Whit Sunday / Pingstdagen
-   Midsummer Eve / Midsommarafton
-   Midsummer Day / Midsommardagen
-   All Saints Eve / Allhelgonaafton
-   All Saints Day / Alla helgons dag
-   Christmas Eve / Julafton
-   Christmas Day / Juldagen
-   Boxing Day / Annandag jul
-   New Years Eve / Nyårsafton