business-days-js

    2.1.2 • Public • Published

    business-days-js

    npm npm bundle size

    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.

    Install

    npm i business-days-js

    DownloadsWeekly Downloads

    25

    Version

    2.1.2

    License

    MIT

    Unpacked Size

    96.3 kB

    Total Files

    20

    Last publish

    Collaborators

    • avatar