moment-biz/README.md

Handle business days & weekends over multiple years

# moment-biz

## Installation

Run `npm install moment moment-biz` to install this package and its moment dependency.

## Setup

### Node.js

Just require the package using:

```js
const moment = require('moment');
require('moment-biz');
```

You can also do this with a oneliner:

```js
const moment = require('moment-biz').moment;
```

Node loads the bundled country locales automatically when calling the related methods:

```js
const moment = require('moment-biz').moment;

// will load en-US locale automatically if it is not loaded yet
moment.locale('en-US');
// will load fr-FR locale automatically if it is not loaded yet
moment().locale('fr-FR');
```

### Browsers

You need to add the moment-biz file located in dist in your webpage. It needs to have moment loaded before if you are not using AMD or other module system. (all files in `dist/` have an UMD wrapper):

```html
<script type="application/javascript" src="node_modules/moment/min/moment.min.js"></script>
<script type="application/javascript" src="node_modules/moment-biz/dist/moment-biz.min.js"></script>
```

You can also load country locales (specific extension to moment locales that are already configured to support the proper holidays):

```html
<script type="application/javascript" src="node_modules/moment/min/moment.min.js"></script>
<script type="application/javascript" src="node_modules/moment-biz/dist/moment-biz.min.js"></script>
<script type="application/javascript" src="node_modules/moment-biz/dist/locale/en-US.min.js"></script>
```

You also have a file containing all country locales for ease of use:

```html
<script type="application/javascript" src="node_modules/moment/min/moment.min.js"></script>
<script type="application/javascript" src="node_modules/moment-biz/dist/moment-biz-with-locales.min.js"></script>
```

## Usage

### .add() and .subtract() changes

Now both methods supports a `businessdays` argument (also works in singular):

```js
const prevBusinessDay = moment().subtract(1, 'businessday');
const nextBusinessDay = moment().add(1, 'businessday');
const in10BusinessDays = moment().add(10, 'businessdays');
const bef10BusinessDays = moment().subtract(10, 'businessdays');
```

### moment.easter

You also have access to the `moment.easter(year)` function that returns you the easter sunday of the provided year.

```js
moment.easter(2017) // returns a moment object on April, 16th, 2017
```

### moment.getHolidays

`moment.getHolidays(year = moment().year(), locale = moment.locale())` returns the holidays for the current year & locale or the specified ones if set.

```js
moment.locale('fr-FR');
// will return a moment object on January, 1st, 2017
moment.getHolidays(2017)[0];
```

### .getHolidaysOfCurrentYear

On any moment instance, you can always call `getHolidaysOfCurrentYear()`. It will return the same thing as `moment.getHolidays(date.year(), date.locale())`.

```js
const date = moment().locale('fr-FR').year(2017);
// will return a moment object on January, 1st, 2017
date.getHolidaysOfCurrentYear()[0];
```

### .isHoliday

You can call `date.isHoliday()` to know if the current date is a holiday or not (be careful, country locales tend to contain only holidays that can happen on non weekend days) according to your locale configuration.

```js
moment('2017-01-02', 'YYYY-MM-DD').locale('en-US').isHoliday(); // return true
moment('2017-01-03', 'YYYY-MM-DD').locale('en-US').isHoliday(); // return false
```

### .isWeekend

You can call `date.isWeekend()` to test if your date is on a weekend according to your locale configuration.

```js
moment().locale('en-US').day(6).isWeekend(); // return true
moment().locale('en-US').day(2).isWeekend(); // return false
```

### .isFreeDay

You can call `date.isFreeDay()` to know if you date is not a business day according to your locale configuration.

```js
moment('2017-01-01', 'YYYY-MM-DD').locale('en-US').isFreeDay(); // return true
moment('2017-01-02', 'YYYY-MM-DD').locale('en-US').isFreeDay(); // return true
moment('2017-01-03', 'YYYY-MM-DD').locale('en-US').isFreeDay(); // return false
```

### .isBusinessDay

You can call `date.isBusinessDay()` to know if you date is a business day according to your locale configuration.

```js
moment.locale('en-US');
moment('2017-01-01', 'YYYY-MM-DD').isBusinessDay(); // return false
moment('2017-01-02', 'YYYY-MM-DD').isBusinessDay(); // return false
moment('2017-01-03', 'YYYY-MM-DD').isBusinessDay(); // return true
```

## Country locales

### Defining your own country locales

You can easily create country locales. First load the correct main locale, then call `moment.defineLocale()` to create it just like this:

```js
moment.locale('fr');
moment.defineLocale('fr-FR', {
  parentLocale: 'fr',
  weekends: [0, 6],
  holidays: [
    // --- civil holidays ---
    '01-01', // new year's day
    // ...
    // --- religious holidays ---
    year => moment.easter(year).add(1, 'day'), // easter monday
    // ...
  ],
});
```

There is 3 main parts to the `defineLocale()` call.

First, `parentLocale`, defines the basic locale you want to use. Always refer to the main locale you want to fallback to.

Then `weekends` defines the week days that are considered weekends in your country. Use `0 = sunday, 6 = saturday` values. It defaults to `[0, 6]` on all locales if not provided.

And last, `holidays`, that define the proper holidays of your country. It accepts either a `DD-MM` date (you can customize this format using the `holidaysFormat` configuration variable) that will become a holiday every year or a function that takes a year and return a holiday (or an invalid date if the holiday does not exists the provided year).

### Adding country locales to the package itself

I'll gladly accept PRs adding support for new countries. Just add your file & copy paste a test loading a locale to ensure yours keeps loading properly before submitting your PR.