moment-biz
v1.0.3
Published
Handle business days & weekends over multiple years
Downloads
5
Maintainers
Readme
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.