date-fns-holidays 1.1.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +494 -317
  2. package/dist/index.cjs +1 -1
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +228 -97
  5. package/dist/index.d.mts +228 -97
  6. package/dist/index.iife.js +1 -1
  7. package/dist/index.iife.js.map +1 -1
  8. package/dist/index.mjs +1 -1
  9. package/dist/index.mjs.map +1 -1
  10. package/package.json +7 -3
package/README.md CHANGED
@@ -2,9 +2,56 @@
2
2
 
3
3
  This project is fork of:
4
4
 
5
- - https://github.com/jonstuebe/date-fns-holiday-us
6
-
7
- The API will be the same as the original project, with the primary focus being bug fixes.
5
+ * https://github.com/jonstuebe/date-fns-holiday-us
6
+
7
+ The API will be the same as the original project, with the primary focus being bug fixes and performance improvements.
8
+
9
+ ## Table of Contents
10
+
11
+ * [Install](#install)
12
+ * [Type Aliases](#type-aliases)
13
+ * [Holiday](#holiday)
14
+ * [HolidayList](#holidaylist)
15
+ * [Holidays](#holidays)
16
+ * [Functions](#functions)
17
+ * [Holiday](#holiday-1)
18
+ * [getBlackFriday()](#getblackfriday)
19
+ * [getBoxingDay()](#getboxingday)
20
+ * [getChristmas()](#getchristmas)
21
+ * [getChristmasEve()](#getchristmaseve)
22
+ * [getColumbusDay()](#getcolumbusday)
23
+ * [getEaster()](#geteaster)
24
+ * [getFathersDay()](#getfathersday)
25
+ * [getGoodFriday()](#getgoodfriday)
26
+ * [getHalloween()](#gethalloween)
27
+ * [getIndependenceDay()](#getindependenceday)
28
+ * [getJuneteenth()](#getjuneteenth)
29
+ * [getLaborDay()](#getlaborday)
30
+ * [getMartinLutherKingJrDay()](#getmartinlutherkingjrday)
31
+ * [getMemorialDay()](#getmemorialday)
32
+ * [getMothersDay()](#getmothersday)
33
+ * [getNewYearsDay()](#getnewyearsday)
34
+ * [getNewYearsEve()](#getnewyearseve)
35
+ * [getPresidentsDay()](#getpresidentsday)
36
+ * [getStPatricksDay()](#getstpatricksday)
37
+ * [getThanksgiving()](#getthanksgiving)
38
+ * [getValentinesDay()](#getvalentinesday)
39
+ * [getVeteransDay()](#getveteransday)
40
+ * [Holidays](#holidays-1)
41
+ * [getBankHolidays()](#getbankholidays)
42
+ * [getFederalHolidays()](#getfederalholidays)
43
+ * [getHolidays()](#getholidays)
44
+ * [getObservedHolidays()](#getobservedholidays)
45
+ * [Utility](#utility)
46
+ * [filterHolidays()](#filterholidays)
47
+ * [getFirstOccurrence()](#getfirstoccurrence)
48
+ * [getLastOfMonth()](#getlastofmonth)
49
+ * [getNextOccurrence()](#getnextoccurrence)
50
+ * [getPrevOccurrence()](#getprevoccurrence)
51
+ * [isBankHoliday()](#isbankholiday)
52
+ * [isFederalHoliday()](#isfederalholiday)
53
+ * [isHoliday()](#isholiday)
54
+ * [isInHolidayList()](#isinholidaylist)
8
55
 
9
56
  ## Install
10
57
 
@@ -18,32 +65,34 @@ npm i date-fns-holidays date-fns
18
65
 
19
66
  ```ts
20
67
  type Holiday =
68
+ | "blackFriday"
69
+ | "boxingDay"
21
70
  | "christmas"
71
+ | "christmasEve"
72
+ | "columbusDay"
22
73
  | "easter"
74
+ | "fathersDay"
75
+ | "goodFriday"
23
76
  | "halloween"
24
- | "valentinesDay"
25
- | "mothersDay"
26
- | "columbusDay"
27
77
  | "independenceDay"
28
- | "presidentsDay"
78
+ | "juneteenth"
29
79
  | "laborDay"
30
- | "veteransDay"
31
- | "thanksgiving"
32
- | "newYearsEve"
33
80
  | "martinLutherKingJrDay"
34
- | "newYearsDay"
35
- | "fathersDay"
36
81
  | "memorialDay"
37
- | "goodFriday"
38
- | "juneteenth";
82
+ | "mothersDay"
83
+ | "newYearsDay"
84
+ | "newYearsEve"
85
+ | "presidentsDay"
86
+ | "stPatricksDay"
87
+ | "thanksgiving"
88
+ | "valentinesDay"
89
+ | "veteransDay";
39
90
  ```
40
91
 
41
- Defined in: [types/index.ts:7](https://github.com/nktnet1/date-fns-holidays/blob/main/src/types/index.ts#L7)
92
+ Defined in: [types/index.ts:6](https://github.com/nktnet1/date-fns-holidays/blob/main/src/types/index.ts#L6)
42
93
 
43
94
  Union of supported holiday identifiers used throughout the library.
44
95
 
45
- #### Remarks
46
-
47
96
  Each value corresponds to a key in [Holidays](#holidays).
48
97
 
49
98
  ***
@@ -56,12 +105,10 @@ type HolidayList = Record<string, {
56
105
  }>;
57
106
  ```
58
107
 
59
- Defined in: [types/index.ts:34](https://github.com/nktnet1/date-fns-holidays/blob/main/src/types/index.ts#L34)
108
+ Defined in: [types/index.ts:36](https://github.com/nktnet1/date-fns-holidays/blob/main/src/types/index.ts#L36)
60
109
 
61
110
  Mapping of holiday names to their computed date values.
62
111
 
63
- #### Remarks
64
-
65
112
  This structure is used for filtered or derived holiday collections where
66
113
  only the date is relevant.
67
114
 
@@ -73,104 +120,108 @@ only the date is relevant.
73
120
  type Holidays = { [K in Holiday]: { bankHoliday: boolean; date: Date; federal: boolean } };
74
121
  ```
75
122
 
76
- Defined in: [types/index.ts:45](https://github.com/nktnet1/date-fns-holidays/blob/main/src/types/index.ts#L45)
123
+ Defined in: [types/index.ts:46](https://github.com/nktnet1/date-fns-holidays/blob/main/src/types/index.ts#L46)
77
124
 
78
125
  Complete set of holidays returned by [getHolidays](#getholidays).
79
126
 
80
- #### Remarks
81
-
82
127
  Each entry includes:
83
- - `date`: computed holiday date
84
- - `bankHoliday`: whether the holiday is observed by banks
85
- - `federal`: whether the holiday is a U.S. federal holiday
128
+
129
+ * `date`: computed holiday date
130
+ * `bankHoliday`: whether the holiday is observed by banks
131
+ * `federal`: whether the holiday is a U.S. federal holiday
86
132
 
87
133
  ## Functions
88
134
 
89
- ### filterHolidays()
135
+ ### Holiday
136
+
137
+ #### getBlackFriday()
90
138
 
91
139
  ```ts
92
- function filterHolidays(year, predicate): HolidayList;
140
+ function getBlackFriday(year): Date;
93
141
  ```
94
142
 
95
- Defined in: [utils/filters.ts:19](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/filters.ts#L19)
143
+ Defined in: [holiday/getBlackFriday.ts:18](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getBlackFriday.ts#L18)
96
144
 
97
- Filters the full holiday set for a given year using a predicate.
145
+ Returns the date of Black Friday for the specified year.
98
146
 
99
- #### Parameters
147
+ ##### Parameters
100
148
 
101
149
  | Parameter | Type | Description |
102
150
  | ------ | ------ | ------ |
103
- | `year` | `number` | The year for which to retrieve and filter holidays. |
104
- | `predicate` | (`holiday`) => `boolean` | Function applied to each holiday entry to determine inclusion. |
151
+ | `year` | `number` | The year for which to obtain Black Friday. |
105
152
 
106
- #### Returns
153
+ ##### Returns
107
154
 
108
- [`HolidayList`](#holidaylist)
155
+ [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
109
156
 
110
- A [HolidayList](#holidaylist) containing only matching holidays.
157
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Black Friday of the specified year.
111
158
 
112
- #### Remarks
159
+ ##### Remarks
113
160
 
114
- This function evaluates the complete [Holidays](#holidays) object returned by
115
- [getHolidays](#getholidays) and constructs a [HolidayList](#holidaylist) containing only
116
- entries that satisfy the provided predicate.
161
+ Black Friday is observed annually on the day after Thanksgiving Day
162
+ in the United States (the fourth Friday of November).
117
163
 
118
- The resulting object preserves the original holiday keys but reduces each
119
- entry to its date value.
164
+ The returned [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) is created in the local time zone.
120
165
 
121
166
  ***
122
167
 
123
- ### getBankHolidays()
168
+ #### getBoxingDay()
124
169
 
125
170
  ```ts
126
- function getBankHolidays(year): HolidayList;
171
+ function getBoxingDay(year): Date;
127
172
  ```
128
173
 
129
- Defined in: [holidays/getBankHolidays.ts:13](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getBankHolidays.ts#L13)
174
+ Defined in: [holiday/getBoxingDay.ts:18](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getBoxingDay.ts#L18)
130
175
 
131
- Returns all bank holidays for the specified year.
176
+ Returns the date of Boxing Day for the specified year.
132
177
 
133
- #### Parameters
178
+ ##### Parameters
134
179
 
135
180
  | Parameter | Type | Description |
136
181
  | ------ | ------ | ------ |
137
- | `year` | `number` | The year for which to retrieve bank holidays. |
182
+ | `year` | `number` | The year for which to obtain Boxing Day. |
138
183
 
139
- #### Returns
184
+ ##### Returns
140
185
 
141
- [`HolidayList`](#holidaylist)
186
+ [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
142
187
 
143
- A [HolidayList](#holidaylist) of bank holidays occurring in the specified year.
188
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing December 26 of the specified year.
144
189
 
145
- #### Remarks
190
+ ##### Remarks
146
191
 
147
- Only holidays marked as bank holidays are included in the returned list.
192
+ Boxing Day is observed on December 26 in several Commonwealth countries,
193
+ including the UK, Canada, Australia, and New Zealand.
194
+
195
+ It is not a U.S. federal holiday, but it is a fixed calendar date
196
+ immediately following Christmas Day.
197
+
198
+ The returned [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) is created in the local time zone.
148
199
 
149
200
  ***
150
201
 
151
- ### getChristmas()
202
+ #### getChristmas()
152
203
 
153
204
  ```ts
154
205
  function getChristmas(year): Date;
155
206
  ```
156
207
 
157
- Defined in: [holidays/getChristmas.ts:12](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getChristmas.ts#L12)
208
+ Defined in: [holiday/getChristmas.ts:14](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getChristmas.ts#L14)
158
209
 
159
210
  Returns the date of Christmas Day for the specified year.
160
211
 
161
- #### Parameters
212
+ ##### Parameters
162
213
 
163
214
  | Parameter | Type | Description |
164
215
  | ------ | ------ | ------ |
165
216
  | `year` | `number` | The year for which to obtain Christmas Day. |
166
217
 
167
- #### Returns
218
+ ##### Returns
168
219
 
169
220
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
170
221
 
171
222
  A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing December 25 of the specified year.
172
223
 
173
- #### Remarks
224
+ ##### Remarks
174
225
 
175
226
  Christmas Day is observed annually on December 25.
176
227
 
@@ -178,59 +229,89 @@ The returned [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe
178
229
 
179
230
  ***
180
231
 
181
- ### getColumbusDay()
232
+ #### getChristmasEve()
233
+
234
+ ```ts
235
+ function getChristmasEve(year): Date;
236
+ ```
237
+
238
+ Defined in: [holiday/getChristmasEve.ts:14](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getChristmasEve.ts#L14)
239
+
240
+ Returns the date of Christmas Eve for the specified year.
241
+
242
+ ##### Parameters
243
+
244
+ | Parameter | Type | Description |
245
+ | ------ | ------ | ------ |
246
+ | `year` | `number` | The year for which to obtain Christmas Eve. |
247
+
248
+ ##### Returns
249
+
250
+ [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
251
+
252
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing December 24 of the specified year.
253
+
254
+ ##### Remarks
255
+
256
+ Christmas Eve is observed annually on December 24.
257
+
258
+ The returned [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) is created in the local time zone.
259
+
260
+ ***
261
+
262
+ #### getColumbusDay()
182
263
 
183
264
  ```ts
184
265
  function getColumbusDay(year): Date;
185
266
  ```
186
267
 
187
- Defined in: [holidays/getColumbusDay.ts:14](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getColumbusDay.ts#L14)
268
+ Defined in: [holiday/getColumbusDay.ts:16](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getColumbusDay.ts#L16)
188
269
 
189
270
  Calculates the date of Columbus Day for the specified year.
190
271
 
191
- #### Parameters
272
+ ##### Parameters
192
273
 
193
274
  | Parameter | Type | Description |
194
275
  | ------ | ------ | ------ |
195
276
  | `year` | `number` | The year for which to calculate Columbus Day. |
196
277
 
197
- #### Returns
278
+ ##### Returns
198
279
 
199
280
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
200
281
 
201
282
  A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing the second Monday in October.
202
283
 
203
- #### Remarks
284
+ ##### Remarks
204
285
 
205
286
  In the United States, Columbus Day is observed on the second Monday
206
287
  of October.
207
288
 
208
289
  ***
209
290
 
210
- ### getEaster()
291
+ #### getEaster()
211
292
 
212
293
  ```ts
213
294
  function getEaster(year): Date;
214
295
  ```
215
296
 
216
- Defined in: [holidays/getEaster.ts:16](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getEaster.ts#L16)
297
+ Defined in: [holiday/getEaster.ts:18](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getEaster.ts#L18)
217
298
 
218
299
  Calculates the date of Easter Sunday for a given year using the
219
300
  Gregorian computus algorithm.
220
301
 
221
- #### Parameters
302
+ ##### Parameters
222
303
 
223
304
  | Parameter | Type | Description |
224
305
  | ------ | ------ | ------ |
225
306
  | `year` | `number` | The year for which to calculate Easter Sunday. |
226
307
 
227
- #### Returns
308
+ ##### Returns
228
309
 
229
310
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
230
311
 
231
312
  A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Easter Sunday in the specified year.
232
313
 
233
- #### Remarks
314
+ ##### Remarks
234
315
 
235
316
  This implementation is valid for years from 325 AD onward, the year of the
236
317
  First Council of Nicaea, which established the basis for calculating Easter.
@@ -238,667 +319,763 @@ First Council of Nicaea, which established the basis for calculating Easter.
238
319
  The returned [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) is created in the local time zone and represents
239
320
  Easter Sunday for the specified year.
240
321
 
241
- #### Throws
322
+ ##### Throws
242
323
 
243
324
  Thrown if the year is earlier than 325 AD.
244
325
 
245
326
  ***
246
327
 
247
- ### getFathersDay()
328
+ #### getFathersDay()
248
329
 
249
330
  ```ts
250
331
  function getFathersDay(year): Date;
251
332
  ```
252
333
 
253
- Defined in: [holidays/getFathersDay.ts:14](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getFathersDay.ts#L14)
334
+ Defined in: [holiday/getFathersDay.ts:16](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getFathersDay.ts#L16)
254
335
 
255
336
  Calculates the date of Father's Day for the specified year.
256
337
 
257
- #### Parameters
338
+ ##### Parameters
258
339
 
259
340
  | Parameter | Type | Description |
260
341
  | ------ | ------ | ------ |
261
342
  | `year` | `number` | The year for which to calculate Father's Day. |
262
343
 
263
- #### Returns
344
+ ##### Returns
264
345
 
265
346
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
266
347
 
267
348
  A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing the third Sunday in June.
268
349
 
269
- #### Remarks
350
+ ##### Remarks
270
351
 
271
352
  In the United States and many other countries, Father's Day is observed on
272
353
  the third Sunday of June.
273
354
 
274
355
  ***
275
356
 
276
- ### getFederalHolidays()
357
+ #### getGoodFriday()
277
358
 
278
359
  ```ts
279
- function getFederalHolidays(year): HolidayList;
360
+ function getGoodFriday(year): Date;
280
361
  ```
281
362
 
282
- Defined in: [holidays/getFederalHolidays.ts:13](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getFederalHolidays.ts#L13)
363
+ Defined in: [holiday/getGoodFriday.ts:16](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getGoodFriday.ts#L16)
283
364
 
284
- Returns all federal holidays for the specified year.
365
+ Calculates the date of Good Friday for the specified year.
285
366
 
286
- #### Parameters
367
+ ##### Parameters
287
368
 
288
369
  | Parameter | Type | Description |
289
370
  | ------ | ------ | ------ |
290
- | `year` | `number` | The year for which to retrieve federal holidays. |
371
+ | `year` | `number` | The year for which to calculate Good Friday. |
291
372
 
292
- #### Returns
373
+ ##### Returns
293
374
 
294
- [`HolidayList`](#holidaylist)
375
+ [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
295
376
 
296
- A [HolidayList](#holidaylist) of federal holidays occurring in the specified year.
377
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Good Friday in the specified year.
297
378
 
298
- #### Remarks
379
+ ##### Remarks
299
380
 
300
- Only holidays marked as federal holidays are included in the returned list.
381
+ Good Friday is observed two days before Easter Sunday and commemorates the
382
+ crucifixion of Jesus Christ in Christian tradition.
301
383
 
302
384
  ***
303
385
 
304
- ### getFirstOccurrence()
386
+ #### getHalloween()
305
387
 
306
388
  ```ts
307
- function getFirstOccurrence(date, dayOfWeekIndex): Date;
389
+ function getHalloween(year): Date;
308
390
  ```
309
391
 
310
- Defined in: [utils/getters.ts:19](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/getters.ts#L19)
392
+ Defined in: [holiday/getHalloween.ts:12](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getHalloween.ts#L12)
311
393
 
312
- Returns the first occurrence of a given weekday within the month of the provided date.
394
+ Returns the date of Halloween for the specified year.
313
395
 
314
- #### Parameters
396
+ ##### Parameters
315
397
 
316
398
  | Parameter | Type | Description |
317
399
  | ------ | ------ | ------ |
318
- | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | Any date within the target month. |
319
- | `dayOfWeekIndex` | `number` | Weekday index (0 = Sunday, 6 = Saturday). |
400
+ | `year` | `number` | The year for which to obtain Halloween. |
320
401
 
321
- #### Returns
402
+ ##### Returns
322
403
 
323
404
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
324
405
 
325
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing the first occurrence of the weekday in that month.
406
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing October 31 of the specified year.
326
407
 
327
- #### Remarks
408
+ ##### Remarks
328
409
 
329
- This works by normalizing the date to the first day of its month, then finding the
330
- next occurrence of the specified weekday.
410
+ Halloween is observed annually on October 31.
331
411
 
332
412
  ***
333
413
 
334
- ### getGoodFriday()
414
+ #### getIndependenceDay()
335
415
 
336
416
  ```ts
337
- function getGoodFriday(year): Date;
417
+ function getIndependenceDay(year): Date;
338
418
  ```
339
419
 
340
- Defined in: [holidays/getGoodFriday.ts:14](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getGoodFriday.ts#L14)
420
+ Defined in: [holiday/getIndependenceDay.ts:12](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getIndependenceDay.ts#L12)
341
421
 
342
- Calculates the date of Good Friday for the specified year.
422
+ Returns the date of Independence Day for the specified year.
343
423
 
344
- #### Parameters
424
+ ##### Parameters
345
425
 
346
426
  | Parameter | Type | Description |
347
427
  | ------ | ------ | ------ |
348
- | `year` | `number` | The year for which to calculate Good Friday. |
428
+ | `year` | `number` | The year for which to obtain Independence Day. |
349
429
 
350
- #### Returns
430
+ ##### Returns
351
431
 
352
432
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
353
433
 
354
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Good Friday in the specified year.
434
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing July 4 of the specified year.
355
435
 
356
- #### Remarks
436
+ ##### Remarks
357
437
 
358
- Good Friday is observed two days before Easter Sunday and commemorates the
359
- crucifixion of Jesus Christ in Christian tradition.
438
+ Independence Day in the United States is observed annually on July 4.
360
439
 
361
440
  ***
362
441
 
363
- ### getHalloween()
442
+ #### getJuneteenth()
364
443
 
365
444
  ```ts
366
- function getHalloween(year): Date;
445
+ function getJuneteenth(year): Date;
367
446
  ```
368
447
 
369
- Defined in: [holidays/getHalloween.ts:10](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getHalloween.ts#L10)
448
+ Defined in: [holiday/getJuneteenth.ts:13](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getJuneteenth.ts#L13)
370
449
 
371
- Returns the date of Halloween for the specified year.
450
+ Returns the date of Juneteenth for the specified year.
372
451
 
373
- #### Parameters
452
+ ##### Parameters
374
453
 
375
454
  | Parameter | Type | Description |
376
455
  | ------ | ------ | ------ |
377
- | `year` | `number` | The year for which to obtain Halloween. |
456
+ | `year` | `number` | The year for which to obtain Juneteenth. |
378
457
 
379
- #### Returns
458
+ ##### Returns
380
459
 
381
460
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
382
461
 
383
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing October 31 of the specified year.
462
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing June 19 of the specified year.
384
463
 
385
- #### Remarks
464
+ ##### Remarks
386
465
 
387
- Halloween is observed annually on October 31.
466
+ Juneteenth National Independence Day is observed in the United States on June 19.
467
+ It became a federal holiday in 2021.
388
468
 
389
469
  ***
390
470
 
391
- ### getHolidays()
471
+ #### getLaborDay()
392
472
 
393
473
  ```ts
394
- function getHolidays(year): Holidays;
474
+ function getLaborDay(year): Date;
395
475
  ```
396
476
 
397
- Defined in: [holidays/getHolidays.ts:36](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getHolidays.ts#L36)
477
+ Defined in: [holiday/getLaborDay.ts:14](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getLaborDay.ts#L14)
398
478
 
399
- Returns the complete set of supported holidays for the specified year.
479
+ Returns the date of Labor Day for the specified year.
400
480
 
401
- #### Parameters
481
+ ##### Parameters
402
482
 
403
483
  | Parameter | Type | Description |
404
484
  | ------ | ------ | ------ |
405
- | `year` | `number` | The year for which to generate holiday information. |
406
-
407
- #### Returns
485
+ | `year` | `number` | The year for which to calculate Labor Day. |
408
486
 
409
- [`Holidays`](#holidays)
487
+ ##### Returns
410
488
 
411
- An object containing all supported holidays and their metadata.
489
+ [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
412
490
 
413
- #### Remarks
491
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Labor Day in the specified year.
414
492
 
415
- Each holiday entry contains its calculated date together with metadata
416
- indicating whether it is recognized as a federal holiday and/or a bank
417
- holiday.
493
+ ##### Remarks
418
494
 
419
- Holiday observance classifications may vary by jurisdiction and may change
420
- over time. The values returned by this function reflect the rules implemented
421
- by this library.
495
+ In the United States, Labor Day is observed on the first Monday of September.
422
496
 
423
497
  ***
424
498
 
425
- ### getIndependenceDay()
499
+ #### getMartinLutherKingJrDay()
426
500
 
427
501
  ```ts
428
- function getIndependenceDay(year): Date;
502
+ function getMartinLutherKingJrDay(year): Date;
429
503
  ```
430
504
 
431
- Defined in: [holidays/getIndependenceDay.ts:10](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getIndependenceDay.ts#L10)
505
+ Defined in: [holiday/getMartinLutherKingJrDay.ts:15](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getMartinLutherKingJrDay.ts#L15)
432
506
 
433
- Returns the date of Independence Day for the specified year.
507
+ Returns the date of Martin Luther King Jr. Day for the specified year.
434
508
 
435
- #### Parameters
509
+ ##### Parameters
436
510
 
437
511
  | Parameter | Type | Description |
438
512
  | ------ | ------ | ------ |
439
- | `year` | `number` | The year for which to obtain Independence Day. |
513
+ | `year` | `number` | The year for which to calculate the holiday. |
440
514
 
441
- #### Returns
515
+ ##### Returns
442
516
 
443
517
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
444
518
 
445
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing July 4 of the specified year.
519
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Martin Luther King Jr. Day in the specified year.
446
520
 
447
- #### Remarks
521
+ ##### Remarks
448
522
 
449
- Independence Day in the United States is observed annually on July 4.
523
+ In the United States, Martin Luther King Jr. Day is observed on the third Monday of January.
450
524
 
451
525
  ***
452
526
 
453
- ### getJuneteenth()
527
+ #### getMemorialDay()
454
528
 
455
529
  ```ts
456
- function getJuneteenth(year): Date;
530
+ function getMemorialDay(year): Date;
457
531
  ```
458
532
 
459
- Defined in: [holidays/getJuneteenth.ts:11](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getJuneteenth.ts#L11)
533
+ Defined in: [holiday/getMemorialDay.ts:14](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getMemorialDay.ts#L14)
460
534
 
461
- Returns the date of Juneteenth for the specified year.
535
+ Returns the date of Memorial Day for the specified year.
462
536
 
463
- #### Parameters
537
+ ##### Parameters
464
538
 
465
539
  | Parameter | Type | Description |
466
540
  | ------ | ------ | ------ |
467
- | `year` | `number` | The year for which to obtain Juneteenth. |
541
+ | `year` | `number` | The year for which to calculate Memorial Day. |
468
542
 
469
- #### Returns
543
+ ##### Returns
470
544
 
471
545
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
472
546
 
473
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing June 19 of the specified year.
547
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Memorial Day in the specified year.
474
548
 
475
- #### Remarks
549
+ ##### Remarks
476
550
 
477
- Juneteenth National Independence Day is observed in the United States on June 19.
478
- It became a federal holiday in 2021.
551
+ In the United States, Memorial Day is observed on the last Monday of May.
479
552
 
480
553
  ***
481
554
 
482
- ### getLaborDay()
555
+ #### getMothersDay()
483
556
 
484
557
  ```ts
485
- function getLaborDay(year): Date;
558
+ function getMothersDay(year): Date;
486
559
  ```
487
560
 
488
- Defined in: [holidays/getLaborDay.ts:12](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getLaborDay.ts#L12)
561
+ Defined in: [holiday/getMothersDay.ts:15](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getMothersDay.ts#L15)
489
562
 
490
- Returns the date of Labor Day for the specified year.
563
+ Returns the date of Mother's Day for the specified year.
491
564
 
492
- #### Parameters
565
+ ##### Parameters
493
566
 
494
567
  | Parameter | Type | Description |
495
568
  | ------ | ------ | ------ |
496
- | `year` | `number` | The year for which to calculate Labor Day. |
569
+ | `year` | `number` | The year for which to calculate Mother's Day. |
497
570
 
498
- #### Returns
571
+ ##### Returns
499
572
 
500
573
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
501
574
 
502
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Labor Day in the specified year.
575
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Mother's Day in the specified year.
503
576
 
504
- #### Remarks
577
+ ##### Remarks
505
578
 
506
- In the United States, Labor Day is observed on the first Monday of September.
579
+ In the United States, Mother's Day is observed on the second Sunday of May.
507
580
 
508
581
  ***
509
582
 
510
- ### getLastOfMonth()
583
+ #### getNewYearsDay()
511
584
 
512
585
  ```ts
513
- function getLastOfMonth(date, dayOfWeekIndex): Date;
586
+ function getNewYearsDay(year): Date;
514
587
  ```
515
588
 
516
- Defined in: [utils/getters.ts:82](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/getters.ts#L82)
589
+ Defined in: [holiday/getNewYearsDay.ts:12](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getNewYearsDay.ts#L12)
517
590
 
518
- Returns the last occurrence of a given weekday within the month of the provided date.
591
+ Returns the date of New Year's Day for the specified year.
519
592
 
520
- #### Parameters
593
+ ##### Parameters
521
594
 
522
595
  | Parameter | Type | Description |
523
596
  | ------ | ------ | ------ |
524
- | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | Any date within the target month. |
525
- | `dayOfWeekIndex` | `number` | Weekday index (0 = Sunday, 6 = Saturday). |
597
+ | `year` | `number` | The year for which to obtain New Year's Day. |
526
598
 
527
- #### Returns
599
+ ##### Returns
528
600
 
529
601
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
530
602
 
531
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing the last occurrence of the weekday in the month.
603
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing January 1 of the specified year.
532
604
 
533
- #### Remarks
605
+ ##### Remarks
534
606
 
535
- This is computed by starting at the last day of the month and walking backwards
536
- to the requested weekday.
607
+ New Year's Day is observed annually on January 1.
537
608
 
538
609
  ***
539
610
 
540
- ### getMartinLutherKingJrDay()
611
+ #### getNewYearsEve()
541
612
 
542
613
  ```ts
543
- function getMartinLutherKingJrDay(year): Date;
614
+ function getNewYearsEve(year): Date;
544
615
  ```
545
616
 
546
- Defined in: [holidays/getMartinLutherKingJrDay.ts:13](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getMartinLutherKingJrDay.ts#L13)
617
+ Defined in: [holiday/getNewYearsEve.ts:14](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getNewYearsEve.ts#L14)
547
618
 
548
- Returns the date of Martin Luther King Jr. Day for the specified year.
619
+ Returns the date of New Year's Eve for the specified year.
549
620
 
550
- #### Parameters
621
+ ##### Parameters
551
622
 
552
623
  | Parameter | Type | Description |
553
624
  | ------ | ------ | ------ |
554
- | `year` | `number` | The year for which to calculate the holiday. |
625
+ | `year` | `number` | The year for which to obtain New Year's Eve. |
555
626
 
556
- #### Returns
627
+ ##### Returns
557
628
 
558
629
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
559
630
 
560
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Martin Luther King Jr. Day in the specified year.
631
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing December 31 of the specified year.
561
632
 
562
- #### Remarks
633
+ ##### Remarks
563
634
 
564
- In the United States, Martin Luther King Jr. Day is observed on the third Monday of January.
635
+ New Year's Eve is the last day of the year, observed on December 31.
565
636
 
566
637
  ***
567
638
 
568
- ### getMemorialDay()
639
+ #### getPresidentsDay()
569
640
 
570
641
  ```ts
571
- function getMemorialDay(year): Date;
642
+ function getPresidentsDay(year): Date;
572
643
  ```
573
644
 
574
- Defined in: [holidays/getMemorialDay.ts:12](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getMemorialDay.ts#L12)
645
+ Defined in: [holiday/getPresidentsDay.ts:15](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getPresidentsDay.ts#L15)
575
646
 
576
- Returns the date of Memorial Day for the specified year.
647
+ Returns the date of Presidents Day for the specified year.
577
648
 
578
- #### Parameters
649
+ ##### Parameters
579
650
 
580
651
  | Parameter | Type | Description |
581
652
  | ------ | ------ | ------ |
582
- | `year` | `number` | The year for which to calculate Memorial Day. |
653
+ | `year` | `number` | The year for which to calculate Presidents Day. |
583
654
 
584
- #### Returns
655
+ ##### Returns
585
656
 
586
657
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
587
658
 
588
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Memorial Day in the specified year.
659
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Presidents Day in the specified year.
589
660
 
590
- #### Remarks
661
+ ##### Remarks
591
662
 
592
- In the United States, Memorial Day is observed on the last Monday of May.
663
+ In the United States, Presidents Day is observed on the third Monday of February.
593
664
 
594
665
  ***
595
666
 
596
- ### getMothersDay()
667
+ #### getStPatricksDay()
597
668
 
598
669
  ```ts
599
- function getMothersDay(year): Date;
670
+ function getStPatricksDay(year): Date;
600
671
  ```
601
672
 
602
- Defined in: [holidays/getMothersDay.ts:13](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getMothersDay.ts#L13)
673
+ Defined in: [holiday/getStPatricksDay.ts:17](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getStPatricksDay.ts#L17)
603
674
 
604
- Returns the date of Mother's Day for the specified year.
675
+ Returns the date of St. Patrick's Day for the specified year.
605
676
 
606
- #### Parameters
677
+ ##### Parameters
607
678
 
608
679
  | Parameter | Type | Description |
609
680
  | ------ | ------ | ------ |
610
- | `year` | `number` | The year for which to calculate Mother's Day. |
681
+ | `year` | `number` | The year for which to obtain St. Patrick's Day. |
611
682
 
612
- #### Returns
683
+ ##### Returns
613
684
 
614
685
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
615
686
 
616
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Mother's Day in the specified year.
687
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing March 17 of the specified year.
617
688
 
618
- #### Remarks
689
+ ##### Remarks
619
690
 
620
- In the United States, Mother's Day is observed on the second Sunday of May.
691
+ St. Patrick's Day is observed annually on March 17.
692
+
693
+ It is not a U.S. federal holiday, but is widely celebrated culturally,
694
+ particularly in the United States and Ireland.
695
+
696
+ The returned [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) is created in the local time zone.
621
697
 
622
698
  ***
623
699
 
624
- ### getNewYearsDay()
700
+ #### getThanksgiving()
625
701
 
626
702
  ```ts
627
- function getNewYearsDay(year): Date;
703
+ function getThanksgiving(year): Date;
628
704
  ```
629
705
 
630
- Defined in: [holidays/getNewYearsDay.ts:10](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getNewYearsDay.ts#L10)
706
+ Defined in: [holiday/getThanksgiving.ts:15](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getThanksgiving.ts#L15)
631
707
 
632
- Returns the date of New Year's Day for the specified year.
708
+ Returns the date of Thanksgiving for the specified year.
633
709
 
634
- #### Parameters
710
+ ##### Parameters
635
711
 
636
712
  | Parameter | Type | Description |
637
713
  | ------ | ------ | ------ |
638
- | `year` | `number` | The year for which to obtain New Year's Day. |
714
+ | `year` | `number` | The year for which to calculate Thanksgiving. |
639
715
 
640
- #### Returns
716
+ ##### Returns
641
717
 
642
718
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
643
719
 
644
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing January 1 of the specified year.
720
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Thanksgiving in the specified year.
645
721
 
646
- #### Remarks
722
+ ##### Remarks
647
723
 
648
- New Year's Day is observed annually on January 1.
724
+ In the United States, Thanksgiving is observed on the fourth Thursday of November.
649
725
 
650
726
  ***
651
727
 
652
- ### getNewYearsEve()
728
+ #### getValentinesDay()
653
729
 
654
730
  ```ts
655
- function getNewYearsEve(year): Date;
731
+ function getValentinesDay(year): Date;
656
732
  ```
657
733
 
658
- Defined in: [holidays/getNewYearsEve.ts:12](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getNewYearsEve.ts#L12)
734
+ Defined in: [holiday/getValentinesDay.ts:12](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getValentinesDay.ts#L12)
659
735
 
660
- Returns the date of New Year's Eve for the specified year.
736
+ Returns the date of Valentine's Day for the specified year.
661
737
 
662
- #### Parameters
738
+ ##### Parameters
663
739
 
664
740
  | Parameter | Type | Description |
665
741
  | ------ | ------ | ------ |
666
- | `year` | `number` | The year for which to obtain New Year's Eve. |
742
+ | `year` | `number` | The year for which to obtain Valentine's Day. |
667
743
 
668
- #### Returns
744
+ ##### Returns
669
745
 
670
746
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
671
747
 
672
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing December 31 of the specified year.
748
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing February 14 of the specified year.
673
749
 
674
- #### Remarks
750
+ ##### Remarks
675
751
 
676
- New Year's Eve is the last day of the year, observed on December 31.
752
+ Valentine's Day is observed annually on February 14.
677
753
 
678
754
  ***
679
755
 
680
- ### getNextOccurrence()
756
+ #### getVeteransDay()
681
757
 
682
758
  ```ts
683
- function getNextOccurrence(date, dayOfWeekIndex): Date;
759
+ function getVeteransDay(year): Date;
684
760
  ```
685
761
 
686
- Defined in: [utils/getters.ts:34](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/getters.ts#L34)
762
+ Defined in: [holiday/getVeteransDay.ts:12](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holiday/getVeteransDay.ts#L12)
687
763
 
688
- Returns the next occurrence of a given weekday relative to a date.
764
+ Returns the date of Veterans Day for the specified year.
689
765
 
690
- #### Parameters
766
+ ##### Parameters
691
767
 
692
768
  | Parameter | Type | Description |
693
769
  | ------ | ------ | ------ |
694
- | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | Starting date. |
695
- | `dayOfWeekIndex` | `number` | Weekday index (0 = Sunday, 6 = Saturday). |
770
+ | `year` | `number` | The year for which to obtain Veterans Day. |
696
771
 
697
- #### Returns
772
+ ##### Returns
698
773
 
699
774
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
700
775
 
701
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing the next occurrence of the weekday.
776
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing November 11 of the specified year.
702
777
 
703
- #### Remarks
778
+ ##### Remarks
704
779
 
705
- If the provided date already matches the target weekday, it is returned unchanged.
706
- Otherwise, the function advances forward to the next matching weekday.
780
+ Veterans Day is observed annually on November 11 in the United States.
781
+
782
+ ### Holidays
783
+
784
+ #### getBankHolidays()
785
+
786
+ ```ts
787
+ function getBankHolidays(year): HolidayList;
788
+ ```
789
+
790
+ Defined in: [holidays/getBankHolidays.ts:15](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getBankHolidays.ts#L15)
791
+
792
+ Returns all bank holidays for the specified year.
793
+
794
+ ##### Parameters
795
+
796
+ | Parameter | Type | Description |
797
+ | ------ | ------ | ------ |
798
+ | `year` | `number` | The year for which to retrieve bank holidays. |
799
+
800
+ ##### Returns
801
+
802
+ [`HolidayList`](#holidaylist)
803
+
804
+ A [HolidayList](#holidaylist) of bank holidays occurring in the specified year.
805
+
806
+ ##### Remarks
807
+
808
+ Only holidays marked as bank holidays are included in the returned list.
707
809
 
708
810
  ***
709
811
 
710
- ### getObservedHolidays()
812
+ #### getFederalHolidays()
813
+
814
+ ```ts
815
+ function getFederalHolidays(year): HolidayList;
816
+ ```
817
+
818
+ Defined in: [holidays/getFederalHolidays.ts:15](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getFederalHolidays.ts#L15)
819
+
820
+ Returns all federal holidays for the specified year.
821
+
822
+ ##### Parameters
823
+
824
+ | Parameter | Type | Description |
825
+ | ------ | ------ | ------ |
826
+ | `year` | `number` | The year for which to retrieve federal holidays. |
827
+
828
+ ##### Returns
829
+
830
+ [`HolidayList`](#holidaylist)
831
+
832
+ A [HolidayList](#holidaylist) of federal holidays occurring in the specified year.
833
+
834
+ ##### Remarks
835
+
836
+ Only holidays marked as federal holidays are included in the returned list.
837
+
838
+ ***
839
+
840
+ #### getHolidays()
841
+
842
+ ```ts
843
+ function getHolidays(year): Holidays;
844
+ ```
845
+
846
+ Defined in: [holidays/getHolidays.ts:42](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getHolidays.ts#L42)
847
+
848
+ Returns the complete set of supported holidays for the specified year.
849
+
850
+ ##### Parameters
851
+
852
+ | Parameter | Type | Description |
853
+ | ------ | ------ | ------ |
854
+ | `year` | `number` | The year for which to generate holiday information. |
855
+
856
+ ##### Returns
857
+
858
+ [`Holidays`](#holidays)
859
+
860
+ An object containing all supported holidays and their metadata.
861
+
862
+ ##### Remarks
863
+
864
+ Each holiday entry contains its calculated date together with metadata
865
+ indicating whether it is recognized as a federal holiday and/or a bank
866
+ holiday.
867
+
868
+ Holiday observance classifications may vary by jurisdiction and may change
869
+ over time. The values returned by this function reflect the rules implemented
870
+ by this library.
871
+
872
+ ***
873
+
874
+ #### getObservedHolidays()
711
875
 
712
876
  ```ts
713
877
  function getObservedHolidays(year): HolidayList;
714
878
  ```
715
879
 
716
- Defined in: [holidays/getObservedHolidays.ts:19](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getObservedHolidays.ts#L19)
880
+ Defined in: [holidays/getObservedHolidays.ts:21](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getObservedHolidays.ts#L21)
717
881
 
718
882
  Returns the observed federal holidays for the specified year.
719
883
 
720
- #### Parameters
884
+ ##### Parameters
721
885
 
722
886
  | Parameter | Type | Description |
723
887
  | ------ | ------ | ------ |
724
888
  | `year` | `number` | The year for which to calculate observed holidays. |
725
889
 
726
- #### Returns
890
+ ##### Returns
727
891
 
728
892
  [`HolidayList`](#holidaylist)
729
893
 
730
894
  A [HolidayList](#holidaylist) containing observed federal holiday dates.
731
895
 
732
- #### Remarks
896
+ ##### Remarks
733
897
 
734
898
  This function adjusts federal holidays that fall on weekends to their
735
899
  observed dates:
736
- - Saturday holidays are observed on the preceding Friday
737
- - Sunday holidays are observed on the following Monday
900
+
901
+ * Saturday holidays are observed on the preceding Friday
902
+ * Sunday holidays are observed on the following Monday
738
903
 
739
904
  Only holidays marked as `federal: true` are included in the result.
740
905
 
741
- ***
906
+ ### Utility
742
907
 
743
- ### getPresidentsDay()
908
+ #### filterHolidays()
744
909
 
745
910
  ```ts
746
- function getPresidentsDay(year): Date;
911
+ function filterHolidays(year, predicate): HolidayList;
747
912
  ```
748
913
 
749
- Defined in: [holidays/getPresidentsDay.ts:13](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getPresidentsDay.ts#L13)
914
+ Defined in: [utils/filters.ts:21](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/filters.ts#L21)
750
915
 
751
- Returns the date of Presidents Day for the specified year.
916
+ Filters the full holiday set for a given year using a predicate.
752
917
 
753
- #### Parameters
918
+ ##### Parameters
754
919
 
755
920
  | Parameter | Type | Description |
756
921
  | ------ | ------ | ------ |
757
- | `year` | `number` | The year for which to calculate Presidents Day. |
922
+ | `year` | `number` | The year for which to retrieve and filter holidays. |
923
+ | `predicate` | (`holiday`) => `boolean` | Function applied to each holiday entry to determine inclusion. |
758
924
 
759
- #### Returns
925
+ ##### Returns
760
926
 
761
- [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
927
+ [`HolidayList`](#holidaylist)
762
928
 
763
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Presidents Day in the specified year.
929
+ A [HolidayList](#holidaylist) containing only matching holidays.
764
930
 
765
- #### Remarks
931
+ ##### Remarks
766
932
 
767
- In the United States, Presidents Day is observed on the third Monday of February.
933
+ This function evaluates the complete [Holidays](#holidays) object returned by
934
+ [getHolidays](#getholidays) and constructs a [HolidayList](#holidaylist) containing only
935
+ entries that satisfy the provided predicate.
936
+
937
+ The resulting object preserves the original holiday keys but reduces each
938
+ entry to its date value.
768
939
 
769
940
  ***
770
941
 
771
- ### getPrevOccurrence()
942
+ #### getFirstOccurrence()
772
943
 
773
944
  ```ts
774
- function getPrevOccurrence(date, dayOfWeekIndex): Date;
945
+ function getFirstOccurrence(date, dayOfWeekIndex): Date;
775
946
  ```
776
947
 
777
- Defined in: [utils/getters.ts:58](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/getters.ts#L58)
948
+ Defined in: [utils/getters.ts:21](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/getters.ts#L21)
778
949
 
779
- Returns the previous occurrence of a given weekday relative to a date.
950
+ Returns the first occurrence of a given weekday within the month of the provided date.
780
951
 
781
- #### Parameters
952
+ ##### Parameters
782
953
 
783
954
  | Parameter | Type | Description |
784
955
  | ------ | ------ | ------ |
785
- | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | Starting date. |
956
+ | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | Any date within the target month. |
786
957
  | `dayOfWeekIndex` | `number` | Weekday index (0 = Sunday, 6 = Saturday). |
787
958
 
788
- #### Returns
959
+ ##### Returns
789
960
 
790
961
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
791
962
 
792
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing the previous occurrence of the weekday.
963
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing the first occurrence of the weekday in that month.
793
964
 
794
- #### Remarks
965
+ ##### Remarks
795
966
 
796
- If the provided date already matches the target weekday, it is returned unchanged.
797
- Otherwise, the function moves backward to the previous matching weekday.
967
+ This works by normalizing the date to the first day of its month, then finding the
968
+ next occurrence of the specified weekday.
798
969
 
799
970
  ***
800
971
 
801
- ### getThanksgiving()
972
+ #### getLastOfMonth()
802
973
 
803
974
  ```ts
804
- function getThanksgiving(year): Date;
975
+ function getLastOfMonth(date, dayOfWeekIndex): Date;
805
976
  ```
806
977
 
807
- Defined in: [holidays/getThanksgiving.ts:13](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getThanksgiving.ts#L13)
978
+ Defined in: [utils/getters.ts:90](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/getters.ts#L90)
808
979
 
809
- Returns the date of Thanksgiving for the specified year.
980
+ Returns the last occurrence of a given weekday within the month of the provided date.
810
981
 
811
- #### Parameters
982
+ ##### Parameters
812
983
 
813
984
  | Parameter | Type | Description |
814
985
  | ------ | ------ | ------ |
815
- | `year` | `number` | The year for which to calculate Thanksgiving. |
986
+ | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | Any date within the target month. |
987
+ | `dayOfWeekIndex` | `number` | Weekday index (0 = Sunday, 6 = Saturday). |
816
988
 
817
- #### Returns
989
+ ##### Returns
818
990
 
819
991
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
820
992
 
821
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing Thanksgiving in the specified year.
993
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing the last occurrence of the weekday in the month.
822
994
 
823
- #### Remarks
995
+ ##### Remarks
824
996
 
825
- In the United States, Thanksgiving is observed on the fourth Thursday of November.
997
+ This is computed by starting at the last day of the month and walking backwards
998
+ to the requested weekday.
826
999
 
827
1000
  ***
828
1001
 
829
- ### getValentinesDay()
1002
+ #### getNextOccurrence()
830
1003
 
831
1004
  ```ts
832
- function getValentinesDay(year): Date;
1005
+ function getNextOccurrence(date, dayOfWeekIndex): Date;
833
1006
  ```
834
1007
 
835
- Defined in: [holidays/getValentinesDay.ts:10](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getValentinesDay.ts#L10)
1008
+ Defined in: [utils/getters.ts:38](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/getters.ts#L38)
836
1009
 
837
- Returns the date of Valentine's Day for the specified year.
1010
+ Returns the next occurrence of a given weekday relative to a date.
838
1011
 
839
- #### Parameters
1012
+ ##### Parameters
840
1013
 
841
1014
  | Parameter | Type | Description |
842
1015
  | ------ | ------ | ------ |
843
- | `year` | `number` | The year for which to obtain Valentine's Day. |
1016
+ | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | Starting date. |
1017
+ | `dayOfWeekIndex` | `number` | Weekday index (0 = Sunday, 6 = Saturday). |
844
1018
 
845
- #### Returns
1019
+ ##### Returns
846
1020
 
847
1021
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
848
1022
 
849
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing February 14 of the specified year.
1023
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing the next occurrence of the weekday.
850
1024
 
851
- #### Remarks
1025
+ ##### Remarks
852
1026
 
853
- Valentine's Day is observed annually on February 14.
1027
+ If the provided date already matches the target weekday, it is returned unchanged.
1028
+ Otherwise, the function advances forward to the next matching weekday.
854
1029
 
855
1030
  ***
856
1031
 
857
- ### getVeteransDay()
1032
+ #### getPrevOccurrence()
858
1033
 
859
1034
  ```ts
860
- function getVeteransDay(year): Date;
1035
+ function getPrevOccurrence(date, dayOfWeekIndex): Date;
861
1036
  ```
862
1037
 
863
- Defined in: [holidays/getVeteransDay.ts:10](https://github.com/nktnet1/date-fns-holidays/blob/main/src/holidays/getVeteransDay.ts#L10)
1038
+ Defined in: [utils/getters.ts:64](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/getters.ts#L64)
864
1039
 
865
- Returns the date of Veterans Day for the specified year.
1040
+ Returns the previous occurrence of a given weekday relative to a date.
866
1041
 
867
- #### Parameters
1042
+ ##### Parameters
868
1043
 
869
1044
  | Parameter | Type | Description |
870
1045
  | ------ | ------ | ------ |
871
- | `year` | `number` | The year for which to obtain Veterans Day. |
1046
+ | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | Starting date. |
1047
+ | `dayOfWeekIndex` | `number` | Weekday index (0 = Sunday, 6 = Saturday). |
872
1048
 
873
- #### Returns
1049
+ ##### Returns
874
1050
 
875
1051
  [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
876
1052
 
877
- A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing November 11 of the specified year.
1053
+ A [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) representing the previous occurrence of the weekday.
878
1054
 
879
- #### Remarks
1055
+ ##### Remarks
880
1056
 
881
- Veterans Day is observed annually on November 11 in the United States.
1057
+ If the provided date already matches the target weekday, it is returned unchanged.
1058
+ Otherwise, the function moves backward to the previous matching weekday.
882
1059
 
883
1060
  ***
884
1061
 
885
- ### isBankHoliday()
1062
+ #### isBankHoliday()
886
1063
 
887
1064
  ```ts
888
1065
  function isBankHoliday(date): boolean;
889
1066
  ```
890
1067
 
891
- Defined in: [utils/isIn.ts:56](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/isIn.ts#L56)
1068
+ Defined in: [utils/isIn.ts:64](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/isIn.ts#L64)
892
1069
 
893
1070
  Checks whether a [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) is a bank holiday.
894
1071
 
895
- #### Parameters
1072
+ ##### Parameters
896
1073
 
897
1074
  | Parameter | Type | Description |
898
1075
  | ------ | ------ | ------ |
899
1076
  | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | The [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) to evaluate. |
900
1077
 
901
- #### Returns
1078
+ ##### Returns
902
1079
 
903
1080
  `boolean`
904
1081
 
@@ -906,23 +1083,23 @@ Checks whether a [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/
906
1083
 
907
1084
  ***
908
1085
 
909
- ### isFederalHoliday()
1086
+ #### isFederalHoliday()
910
1087
 
911
1088
  ```ts
912
1089
  function isFederalHoliday(date): boolean;
913
1090
  ```
914
1091
 
915
- Defined in: [utils/isIn.ts:46](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/isIn.ts#L46)
1092
+ Defined in: [utils/isIn.ts:52](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/isIn.ts#L52)
916
1093
 
917
1094
  Checks whether a [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) is a federal holiday.
918
1095
 
919
- #### Parameters
1096
+ ##### Parameters
920
1097
 
921
1098
  | Parameter | Type | Description |
922
1099
  | ------ | ------ | ------ |
923
1100
  | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | The [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) to evaluate. |
924
1101
 
925
- #### Returns
1102
+ ##### Returns
926
1103
 
927
1104
  `boolean`
928
1105
 
@@ -930,23 +1107,23 @@ Checks whether a [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/
930
1107
 
931
1108
  ***
932
1109
 
933
- ### isHoliday()
1110
+ #### isHoliday()
934
1111
 
935
1112
  ```ts
936
1113
  function isHoliday(date): boolean;
937
1114
  ```
938
1115
 
939
- Defined in: [utils/isIn.ts:36](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/isIn.ts#L36)
1116
+ Defined in: [utils/isIn.ts:40](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/isIn.ts#L40)
940
1117
 
941
1118
  Checks whether a [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) is any recognized holiday.
942
1119
 
943
- #### Parameters
1120
+ ##### Parameters
944
1121
 
945
1122
  | Parameter | Type | Description |
946
1123
  | ------ | ------ | ------ |
947
1124
  | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | The [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) to evaluate. |
948
1125
 
949
- #### Returns
1126
+ ##### Returns
950
1127
 
951
1128
  `boolean`
952
1129
 
@@ -954,30 +1131,30 @@ Checks whether a [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/
954
1131
 
955
1132
  ***
956
1133
 
957
- ### isInHolidayList()
1134
+ #### isInHolidayList()
958
1135
 
959
1136
  ```ts
960
1137
  function isInHolidayList(date, getHolidayList): boolean;
961
1138
  ```
962
1139
 
963
- Defined in: [utils/isIn.ts:19](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/isIn.ts#L19)
1140
+ Defined in: [utils/isIn.ts:21](https://github.com/nktnet1/date-fns-holidays/blob/main/src/utils/isIn.ts#L21)
964
1141
 
965
1142
  Determines whether a given [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) exists within a [HolidayList](#holidaylist) for its year.
966
1143
 
967
- #### Parameters
1144
+ ##### Parameters
968
1145
 
969
1146
  | Parameter | Type | Description |
970
1147
  | ------ | ------ | ------ |
971
1148
  | `date` | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) | The [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) to evaluate. |
972
1149
  | `getHolidayList` | (`year`) => [`HolidayList`](#holidaylist) | Function that returns a [HolidayList](#holidaylist) for a given year. |
973
1150
 
974
- #### Returns
1151
+ ##### Returns
975
1152
 
976
1153
  `boolean`
977
1154
 
978
1155
  `true` if the [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) matches any entry in the holiday list; otherwise `false`.
979
1156
 
980
- #### Remarks
1157
+ ##### Remarks
981
1158
 
982
1159
  The function resolves the appropriate holiday list for the year of the provided
983
1160
  [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), then checks whether any holiday in that list matches the given date