-
Notifications
You must be signed in to change notification settings - Fork 13
/
README.hbs
244 lines (174 loc) · 6.64 KB
/
README.hbs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
# Luxon Business Days
[](https://circleci.com/gh/amaidah/luxon-business-days/tree/master)
[](https://codecov.io/gh/amaidah/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
<script src="https://cdn.jsdelivr.net/npm/[email protected]/build/global/luxon.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/luxon-business-days/dist/index.js"></script>
```
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/[email protected]/dist/index.js
```
```html
<head>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/build/global/luxon.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/luxon-business-days/dist/index.js"></script>
</head>
<body>
<script>
let dt = luxon.DateTime.local();
const nextBizDay = dt.plusBusiness();
console.log(nextBizDay.toLocaleString());
</script>
</body>
```
## 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
{{>main}}