moment-biz

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:

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

You can also do this with a oneliner:

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

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

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):

<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):

<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:

<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):

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.

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.

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()).

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.

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.

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.

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.

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:

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.