business-days-js

Determines whether a given date and time is on a weekend or a public holiday in the U.S. Can also add business days to a specified date to calculate a new date.

This package uses dayjs and date-holidays.

Install

npm i business-days-js

Usage

First initialize a businessDays object:

import businessDays from "business-days-js";

const bDays = businessDays();

By default, businessDays treats 10 U.S. public holidays as non-business days. To use state-specific public holidays, instead initialize businessDays with an appropriate two-letter state abbreviation:

import businessDays from "business-days-js";

const bDays = businessDays({state: "pa"}); // use public holidays for Pennsylvania

Consult 'advanced usage' for more information about customizing holidays.

Check business day

To check whether a native Date object is a business day:

import businessDays from "business-days-js";

const bDays = businessDays({state: "pa"});
const presidentsDay = new Date("2016-02-15 00:00:00 GMT-0500"); // 12 a.m. on Feb. 15, 2016 (EST)
bDays.check(presidentsDay); // returns false

Dates can also be provided as a string formatted as "YYYY-MM-DD":

import businessDays from "business-days-js";

const bDays = businessDays({state: "pa"});
const bizDay = "2021-11-17"; // Wednesday, Nov 17, 2021
bDays.check(bizDay); // returns true

Or dates can be provided as a Day.js object:

import businessDays from "business-days-js";
import dayjs from "dayjs";

const bDays = businessDays({state: "pa"});
const xmasDay = dayjs("2020-12-25 00:00:00 GMT-0500"); // 12 a.m. on Dec 25, 2020 (EST)
bDays.check(xmasDay); // returns false

Add business days

Add a specified number of business days to a date to calculate a new date. The returned date is a Day.js object.

import businessDays from "business-days-js";

const bDays = businessDays({state: "pa"});
const startDate = new Date("2020-12-20 00:00:00 GMT-0500");
bDays.addDays(startDate, 5) // returns a Day.js object representing Dec 28, 2020.

As with other methods, dates can be provided as a Day.js object or a string formatted as "YYYY-MM-DD":

import businessDays from "business-days-js";

const bDays = businessDays({state: "pa"});
const newDate = bDays.addDays("2020-12-20", 5) // returns a Day.js object representing Dec 28, 2020.

Count days

To return an object with a tally of total days, business days, weekends, weekdays, and holidays between two dates:

import businessDays from "business-days-js";

const bDays = businessDays({state: "pa"});
bDays.countDays("2020-12-20", "2020-12-28") // returns an object

Note that countDays excludes the start date from its calculations by default. For instance, by default countDays would count a total of eight days between "2020-12-20" to "2020-12-28" rather than nine days.

To include the start date in the tallies:

import businessDays from "business-days-js";

const bDays = businessDays({state: "pa"});
bDays.countDays("2020-12-20", "2020-12-28", {excludeInitialDate: false})

Get list of public holidays

To get a list of public holidays for a specific year with the dates they end and start:

import businessDays from "business-days-js";

const bDays = businessDays({state: "pa"});
// returns an array of objects with data on Pennsylvania public holidays in 2020
bDays.getHolidays("2020")

Advanced Usage

Customize holidays

You can exclude specific public holidays from businessDays default list of public holidays. Simply initialize a businessDays object with a list of holidays to exclude.

import businessDays from "business-days-js";

const bDays = businessDays({state: "pa", excludeHolidays: ["Flag Day", "Presidents' Day"]});

// Flag Day and Presidents' Day will now be considered business days if they fall during the work week.
const flagDay = new Date("2019-06-14 00:00:00 GMT-0500")
const presDay = new Date("2020-02-17 00:00:00 GMT-0500")
bDays.check(flagDay) // returns true
bDays.check(presDay) // returns true

You can also add custom holidays to to the default list. Each custom holiday is an object with a 'name' property and a 'rule' property. The rule defines the occurrence of the holiday based on the grammar of date-holidays.

import businessDays from "business-days-js";

const CUSTOM_HOLIDAYS = [
  {
    rule: "02-02",
    name: "Groundhog Day",
  },
  {
    rule: "06-19",
    name: "Juneteenth",
  },
]
const bDays = businessDays({
  state: "pa",
  excludeHolidays: ["christmas day", "presidents' day"],
  addHolidays: CUSTOM_HOLIDAYS,
});

About holidays

By default, when initialized without a state abbreviation, businessDays handles 10 U.S. public holidays as non-business days:

New Year's Day
Martin Luther King Jr. Day
Washington's Birthday
Memorial Day
Independence Day
Labor Day
Columbus Day
Veterans Day
Thanksgiving Day
Christmas Day

If those days fall on a weekend, substitution days are used based on rules defined by date-holidays. For instance, if Christmas Day (Dec 25) falls on a Sunday, then Monday will be assumed to be a public holiday. If Christmas Day falls on a Saturday than Friday will be assumed to be a public holiday.

For more information about holiday rules, consult the documentation for date-holidays.

gawry/business-days-js