# Luxon Business Days ![npm](https://img.shields.io/npm/v/luxon-business-days) [![CircleCI](https://circleci.com/gh/amaidah/luxon-business-days/tree/master.svg?style=svg)](https://circleci.com/gh/amaidah/luxon-business-days/tree/master) [![codecov](https://codecov.io/gh/amaidah/luxon-business-days/branch/master/graph/badge.svg)](https://codecov.io/gh/amaidah/luxon-business-days) ![luxon-business-days](https://badgen.net/bundlephobia/minzip/luxon-business-days) ![npm](https://img.shields.io/npm/dm/luxon-business-days) ![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/luxon-business-days) Luxon Business Days is a [Luxon](https://github.com/moment/luxon) plugin for calculating and manipulating business days. Inspired by [moment-business-days](https://github.com/kalmecak/moment-business-days). ## Features - Add business days to a standard luxon `DateTime` instance. For instance, to calculate the arrival date of a shipment. - Customizable and extendable. Configure the business working days and holidays of your business. - Uses holiday "matcher functions" avoiding the need to manually maintain and update holiday date configs every year. ## Install ### Versions Package versions 3+ supports luxon 3+. For luxon ^1.X, check out [2.8.3](https://github.com/amaidah/luxon-business-days/tree/v2.8.3) ### Via NPM Already using luxon: ```bash yarn add luxon-business-days ``` ```diff - import { DateTime } from 'luxon'; + import { DateTime } from 'luxon-business-days'; // Use DateTime as normal ``` Not already using luxon: ```bash yarn add luxon luxon-business-days ``` ```javascript import { DateTime } from 'luxon-business-days'; // Use DateTime as normal ``` ### Via Browser Script ```html ``` Make sure `luxon` script is loaded before `luxon-business-days`. For production use, it is recommended to tag a version in the script url like so: ``` https://cdn.jsdelivr.net/npm/luxon-business-days@2.7.0/dist/index.js ``` ```html ``` ## Config Default business days: - Monday - Tuesday - Wednesday - Thursday - Friday Default holidays (aka shipping holidays via UPS): - New Year's Day - Easter Day - Memorial Day - Independance Day - Labor Day - Thanksgiving Day - Christmas Day #### Configure business days ```javascript import { DateTime } from 'luxon-business-days'; const dt = DateTime.local(); // [Mon, Thur, Fri, Sun] const awesomeFourDayBusinessWeek = [1, 4, 5, 7]; dt.setupBusiness({ businessDays: awesomeFourDayBusinessWeek }); ``` #### Configure holidays Pick from available holiday matchers: ```javascript import { DateTime } from 'luxon-business-days'; const dt = DateTime.local(); const { availableHolidayMatchers } = dt; const myCompanyIsNoFun = [ availableHolidayMatchers.isNewYearsDay, availableHolidayMatchers.isChristmasDay, ]; dt.setupBusiness({ holidayMatchers: myCompanyIsNoFun }); ``` No holidays: ```javascript import { DateTime } from 'luxon-business-days'; const dt = DateTime.local(); dt.setupBusiness({ holidayMatchers: [] }); // Congrats, you will successfuly get everyone to quit ``` Custom holiday matchers: A holiday matcher is simply a function that takes in a `DateTime` instance and returns a boolean. This allows you to algorithmically determine what is considered a holiday without requiring a hardcoded list of dates that are updated and maintained annually. It is easy to write a basic matcher: ```javascript import { DateTime } from 'luxon-business-days'; /** * @param {DateTime} - An instance of DateTime. * @returns {boolean} */ const isCelebratingKobe = function(inst) { // Commemorate the day Kobe died const kobeRIP = DateTime.fromObject({ month: 1, day: 26 }); // Celebrate Kobe Day const kobeDay = DateTime.fromObject({ month: 8, day: 24 }); // Matches the following two days regardless of year return +inst === +kobeRIP || +inst === +kobeDay; }; const dt = DateTime.local(); const myHolidays = [ dt.availableHolidayMatchers.isNewYearsDay, dt.availableHolidayMatchers.isChristmasDay, isCelebratingKobe, ]; dt.setupBusiness({ holidayMatchers: myHolidays }); // Congrats, now your business will consider New Years, // Christmas, and the two Kobe days as holidays. ``` Tip: When writing custom holiday matchers, it is probably better to avoid harcoding years or dates and instead programatically generating holidays. Take a look at the provided [matchers](https://github.com/amaidah/luxon-business-days/blob/master/src/holidays.js) for ideas. ## Usage Basic: ```javascript import { DateTime } from 'luxon-business-days'; // Day before July 4 let dt = DateTime.local(2019, 7, 3); dt = dt.plusBusiness(); // 7/5/19 - Friday dt = dt.plusBusiness({ days: 2 }); // 7/9/19 - Tuesday (Skipped through Saturday/Sunday) dt = dt.minusBusiness({ days: 2 }); // back to 7/5/19 dt = dt.minusBusiness({ days: -2 }) // back to 7/9/19 dt = dt.plusBusiness({ days: -2 }); // back to 7/5/19 // Now do what you normally would with a DateTime instance. ``` Passing additional arguments to matchers: Perhaps you need to calculate regional holidays manually and want to pass extra information to your custom holiday matchers. ```javascript import { DateTime } from 'luxon-business-days'; /** * @param {DateTime} - An instance of DateTime. * @param {string} region - An example extra param. * @param {Object} someStuff - An example extra param. * @returns {boolean} */ const someCustomRegionalMatcher = (inst, region, someStuff) => { // does some matching based on region and data in someStuff } /** * @param {DateTime} - An instance of DateTime. * @returns {boolean} */ const anotherCustomMatcher = inst => { // does some matching, but doesn't need additional info } let dt = DateTime.local(); const myHolidays = [ someCustomRegionalMatcher, anotherCustomMatcher, ]; dt.setupBusiness({ holidayMatchers: myHolidays }); // Pass any additional argument to all your matchers dt.isHoliday('middle-america', {some: 'stuff'}); ``` ## Examples * [Display a range of delivery dates for a shipment](https://codesandbox.io/s/luxon-business-days-range-example-tmb1d). * [Add custom holiday matchers to extend a holiday](https://codesandbox.io/s/luxon-business-days-holiday-ovveride-example-b18v5i) ## API ## Members
DateTime ⇐ DateTime
## Functions
getEasterMonthAndDay(year) ⇒ Array.<number>

Returns the month and day of Easter for a given year.

## DateTime ⇐ [DateTime](#DateTime) **Kind**: global variable **Extends**: [DateTime](#DateTime) * [DateTime](#DateTime) ⇐ [DateTime](#DateTime) * [.availableHolidayMatchers](#DateTime+availableHolidayMatchers) : Object * [.availableHolidayHelpers](#DateTime+availableHolidayHelpers) : Object * [.setupBusiness([businessDays], [holidayMatchers])](#DateTime+setupBusiness) ⇐ [DateTime](#DateTime) * [.clearBusinessSetup()](#DateTime+clearBusinessSetup) ⇐ [DateTime](#DateTime) * [.isHoliday([...args])](#DateTime+isHoliday) ⇒ boolean * [.isBusinessDay()](#DateTime+isBusinessDay) ⇒ boolean * [.plusBusiness([days])](#DateTime+plusBusiness) ⇒ [DateTime](#DateTime) * [.minusBusiness([days])](#DateTime+minusBusiness) ⇒ [DateTime](#DateTime) ### dateTime.availableHolidayMatchers : Object All built-in holiday matchers. **Kind**: instance property of [DateTime](#DateTime) **Extends**: [DateTime](#DateTime) **Properties** | Name | Type | Description | | --- | --- | --- | | isNewYearsDay | function | A provided holiday matcher. | | isMLKDay | function | A provided holiday matcher. | | isEasterDay | function | A provided holiday matcher. | | isMemorialDay | function | A provided holiday matcher. | | isIndependanceDay | function | A provided holiday matcher. | | isLaborDay | function | A provided holiday matcher. | | isColumbusDay | function | A provided holiday matcher. | | isThanksgivingDay | function | A provided holiday matcher. | | isChristmasDay | function | A provided holiday matcher. | ### dateTime.availableHolidayHelpers : Object Exposes all available holiday helpers to a DateTime instance. **Kind**: instance property of [DateTime](#DateTime) **Extends**: [DateTime](#DateTime) **Properties** | Name | Type | Description | | --- | --- | --- | | getEasterMonthAndDay | function | A provided holiday helper function that can be helpful for custom holiday matchers. | ### dateTime.setupBusiness([businessDays], [holidayMatchers]) ⇐ [DateTime](#DateTime) Sets up business days and holiday matchers globally for all DateTime instances. **Kind**: instance method of [DateTime](#DateTime) **Extends**: [DateTime](#DateTime) | Param | Type | Default | Description | | --- | --- | --- | --- | | [businessDays] | Array.<number> | DEFAULT_BUSINESS_DAYS | The working business days for the business. | | [holidayMatchers] | Array.<function()> | DEFAULT_HOLIDAY_MATCHERS | The holiday matchers used to check if a particular day is a holiday for the business. | ### dateTime.clearBusinessSetup() ⇐ [DateTime](#DateTime) Clears business setup globally from all DateTime instances. **Kind**: instance method of [DateTime](#DateTime) **Extends**: [DateTime](#DateTime) ### dateTime.isHoliday([...args]) ⇒ boolean Checks if DateTime instance is a holiday by checking against all holiday matchers. **Kind**: instance method of [DateTime](#DateTime) **Extends**: [DateTime](#DateTime) | Param | Type | Description | | --- | --- | --- | | [...args] | \* | Any additional arguments to pass through to each holiday matcher. | ### dateTime.isBusinessDay() ⇒ boolean Checks if DateTime instance is a business day. **Kind**: instance method of [DateTime](#DateTime) **Extends**: [DateTime](#DateTime) ### dateTime.plusBusiness([days]) ⇒ [DateTime](#DateTime) Adds business days to an existing DateTime instance. **Kind**: instance method of [DateTime](#DateTime) **Extends**: [DateTime](#DateTime) | Param | Type | Default | Description | | --- | --- | --- | --- | | [days] | number | 1 | The number of business days to add. | ### dateTime.minusBusiness([days]) ⇒ [DateTime](#DateTime) Subtracts business days to an existing DateTime instance. **Kind**: instance method of [DateTime](#DateTime) **Extends**: [DateTime](#DateTime) | Param | Type | Default | Description | | --- | --- | --- | --- | | [days] | number | 1 | The number of business days to subtract. | ## getEasterMonthAndDay(year) ⇒ Array.<number> Returns the month and day of Easter for a given year. **Kind**: global function **Returns**: Array.<number> - Returns month and day via `[month, day]`. | Param | Type | | --- | --- | | year | number |