0
# Date Utilities
1

2
Comprehensive date manipulation, formatting, and calculation functions built on date-fns for working with dates in JavaScript applications.
3

4
## Capabilities
5

6
### Date Creation and Parsing
7

8
Functions for creating and parsing Date objects with proper validation.
9

10
```typescript { .api }
11
/**
12
 * Create a new Date instance with fallback to current date
13
 * @param value - String, Date, number, or null/undefined
14
 * @returns Valid Date object
15
 */
16
function newDate(value?: string | Date | number | null): Date;
17

18
/**
19
 * Parse date string with format and locale support
20
 * @param value - Date string to parse
21
 * @param dateFormat - Format string or array of formats
22
 * @param locale - Locale for parsing
23
 * @param strictParsing - Whether to use strict parsing
24
 * @param refDate - Reference date for relative parsing
25
 * @returns Parsed Date or null if invalid
26
 */
27
function parseDate(
28
  value: string,
29
  dateFormat: string | string[],
30
  locale?: Locale,
31
  strictParsing?: boolean,
32
  refDate?: Date
33
): Date | null;
34
```
35

36
### Date Validation
37

38
Functions for validating Date objects and checking date properties.
39

40
```typescript { .api }
41
/**
42
 * Check if value is a Date object
43
 * @param value - Value to check
44
 * @returns True if value is Date
45
 */
46
function isDate(value: any): value is Date;
47

48
/**
49
 * Check if date is valid and within acceptable range
50
 * @param date - Date to validate
51
 * @param minDate - Optional minimum date (defaults to 1/1/1800)
52
 * @returns True if date is valid
53
 */
54
function isValid(date: Date, minDate?: Date): boolean;
55

56
/**
57
 * Set multiple date properties at once
58
 * @param date - Source date
59
 * @param values - Object with date properties to set
60
 * @returns New Date with set properties
61
 */
62
function set(date: Date, values: {
63
  year?: number;
64
  month?: number;
65
  date?: number;
66
  hours?: number;
67
  minutes?: number;
68
  seconds?: number;
69
  milliseconds?: number;
70
}): Date;
71
```
72

73
### Date Formatting
74

75
Functions for formatting dates with locale support.
76

77
```typescript { .api }
78
/**
79
 * Format date with locale support
80
 * @param date - Date to format
81
 * @param formatStr - Format string
82
 * @param locale - Locale for formatting
83
 * @returns Formatted date string
84
 */
85
function formatDate(date: Date, formatStr: string, locale?: Locale): string;
86

87
/**
88
 * Safely format date (handles null/undefined)
89
 * @param date - Date to format (can be null/undefined)
90
 * @param options - Formatting options
91
 * @returns Formatted string or empty string
92
 */
93
function safeDateFormat(
94
  date: Date | null | undefined,
95
  options: { dateFormat: string | string[]; locale?: Locale }
96
): string;
97

98
/**
99
 * Format date range with separator
100
 * @param startDate - Start date
101
 * @param endDate - End date  
102
 * @param props - Formatting options with separator
103
 * @returns Formatted date range string
104
 */
105
function safeDateRangeFormat(
106
  startDate: Date | null | undefined,
107
  endDate: Date | null | undefined,
108
  props: {
109
    dateFormat: string | string[];
110
    locale?: Locale;
111
    rangeSeparator?: string;
112
  }
113
): string;
114

115
/**
116
 * Format multiple selected dates
117
 * @param dates - Array of dates
118
 * @param props - Formatting options
119
 * @returns Formatted dates string
120
 */
121
function safeMultipleDatesFormat(
122
  dates: Date[],
123
  props: { dateFormat: string | string[]; locale?: Locale }
124
): string;
125
```
126

127
### Date Getters
128

129
Functions for extracting date components.
130

131
```typescript { .api }
132
/**
133
 * Get seconds from date (0-59)
134
 */
135
function getSeconds(date: Date): number;
136

137
/**
138
 * Get minutes from date (0-59)
139
 */
140
function getMinutes(date: Date): number;
141

142
/**
143
 * Get hours from date (0-23)
144
 */
145
function getHours(date: Date): number;
146

147
/**
148
 * Get day of month (1-31)
149
 */
150
function getDate(date: Date): number;
151

152
/**
153
 * Get day of week (0-6, Sunday = 0)
154
 */
155
function getDay(date: Date): number;
156

157
/**
158
 * Get ISO week number (1-53)
159
 */
160
function getWeek(date: Date): number;
161

162
/**
163
 * Get month (0-11, January = 0)
164
 */
165
function getMonth(date: Date): number;
166

167
/**
168
 * Get quarter (1-4)
169
 */
170
function getQuarter(date: Date): number;
171

172
/**
173
 * Get full year
174
 */
175
function getYear(date: Date): number;
176

177
/**
178
 * Get timestamp in milliseconds
179
 */
180
function getTime(date: Date): number;
181

182
/**
183
 * Get localized day of week abbreviation
184
 * @param day - Date object
185
 * @param locale - Locale for formatting
186
 * @returns Day abbreviation (e.g., "Mon", "Tue")
187
 */
188
function getDayOfWeekCode(day: Date, locale?: Locale): string;
189
```
190

191
### Date Setters
192

193
Functions for setting date components.
194

195
```typescript { .api }
196
/**
197
 * Set time components on date
198
 * @param date - Source date
199
 * @param time - Time components to set
200
 * @returns New Date with set time
201
 */
202
function setTime(
203
  date: Date,
204
  time: { hour?: number; minute?: number; second?: number }
205
): Date;
206

207
/**
208
 * Set hours (0-23)
209
 */
210
function setHours(date: Date, hours: number): Date;
211

212
/**
213
 * Set minutes (0-59)
214
 */
215
function setMinutes(date: Date, minutes: number): Date;
216

217
/**
218
 * Set seconds (0-59)
219
 */
220
function setSeconds(date: Date, seconds: number): Date;
221

222
/**
223
 * Set month (0-11)
224
 */
225
function setMonth(date: Date, month: number): Date;
226

227
/**
228
 * Set quarter (1-4)
229
 */
230
function setQuarter(date: Date, quarter: number): Date;
231

232
/**
233
 * Set year
234
 */
235
function setYear(date: Date, year: number): Date;
236
```
237

238
### Start/End Date Functions
239

240
Functions for getting start and end boundaries of time periods.
241

242
```typescript { .api }
243
/**
244
 * Get start of day (00:00:00.000)
245
 */
246
function getStartOfDay(date: Date): Date;
247

248
/**
249
 * Get start of week with locale support
250
 * @param date - Source date
251
 * @param locale - Locale for week start day
252
 * @param calendarStartDay - Override for week start day (0-6)
253
 */
254
function getStartOfWeek(
255
  date: Date,
256
  locale?: Locale,
257
  calendarStartDay?: number
258
): Date;
259

260
/**
261
 * Get first day of month
262
 */
263
function getStartOfMonth(date: Date): Date;
264

265
/**
266
 * Get first day of year
267
 */
268
function getStartOfYear(date: Date): Date;
269

270
/**
271
 * Get first day of quarter
272
 */
273
function getStartOfQuarter(date: Date): Date;
274

275
/**
276
 * Get start of today
277
 */
278
function getStartOfToday(): Date;
279

280
/**
281
 * Get end of day (23:59:59.999)
282
 */
283
function getEndOfDay(date: Date): Date;
284

285
/**
286
 * Get end of week
287
 */
288
function getEndOfWeek(date: Date): Date;
289

290
/**
291
 * Get last day of month
292
 */
293
function getEndOfMonth(date: Date): Date;
294
```
295

296
### Date Math Functions
297

298
Functions for adding and subtracting time periods.
299

300
```typescript { .api }
301
/**
302
 * Add days to date
303
 */
304
function addDays(date: Date, amount: number): Date;
305

306
/**
307
 * Add weeks to date
308
 */
309
function addWeeks(date: Date, amount: number): Date;
310

311
/**
312
 * Add months to date
313
 */
314
function addMonths(date: Date, amount: number): Date;
315

316
/**
317
 * Add quarters to date
318
 */
319
function addQuarters(date: Date, amount: number): Date;
320

321
/**
322
 * Add years to date
323
 */
324
function addYears(date: Date, amount: number): Date;
325

326
/**
327
 * Add hours to date
328
 */
329
function addHours(date: Date, amount: number): Date;
330

331
/**
332
 * Add minutes to date
333
 */
334
function addMinutes(date: Date, amount: number): Date;
335

336
/**
337
 * Add seconds to date
338
 */
339
function addSeconds(date: Date, amount: number): Date;
340

341
/**
342
 * Subtract days from date
343
 */
344
function subDays(date: Date, amount: number): Date;
345

346
/**
347
 * Subtract weeks from date
348
 */
349
function subWeeks(date: Date, amount: number): Date;
350

351
/**
352
 * Subtract months from date
353
 */
354
function subMonths(date: Date, amount: number): Date;
355

356
/**
357
 * Subtract quarters from date
358
 */
359
function subQuarters(date: Date, amount: number): Date;
360

361
/**
362
 * Subtract years from date
363
 */
364
function subYears(date: Date, amount: number): Date;
365
```
366

367
### Date Comparison Functions
368

369
Functions for comparing dates and checking relationships.
370

371
```typescript { .api }
372
/**
373
 * Check if date is after another date
374
 */
375
function isAfter(date: Date, dateToCompare: Date): boolean;
376

377
/**
378
 * Check if date is before another date
379
 */
380
function isBefore(date: Date, dateToCompare: Date): boolean;
381

382
/**
383
 * Check if dates are equal
384
 */
385
function isEqual(date: Date, dateToCompare: Date): boolean;
386

387
/**
388
 * Check if dates are the same day
389
 */
390
function isSameDay(date: Date, dateToCompare: Date): boolean;
391

392
/**
393
 * Check if dates are in the same month
394
 */
395
function isSameMonth(date: Date, dateToCompare: Date): boolean;
396

397
/**
398
 * Check if dates are in the same year
399
 */
400
function isSameYear(date: Date, dateToCompare: Date): boolean;
401

402
/**
403
 * Check if dates are in the same quarter
404
 */
405
function isSameQuarter(date: Date, dateToCompare: Date): boolean;
406

407
/**
408
 * Check if day is within date range (inclusive)
409
 */
410
function isDayInRange(
411
  day: Date,
412
  startDate: Date,
413
  endDate: Date
414
): boolean;
415

416
/**
417
 * Check if date is before another with midnight comparison
418
 */
419
function isDateBefore(date: Date, dateToCompare: Date): boolean;
420
```
421

422
### Date Validation and Filtering
423

424
Functions for validating dates against constraints and filters.
425

426
```typescript { .api }
427
/**
428
 * Check if day should be disabled based on DatePicker props
429
 * @param day - Date to check
430
 * @param props - DatePicker props with constraints
431
 * @returns True if day should be disabled
432
 */
433
function isDayDisabled(day: Date, props: {
434
  minDate?: Date;
435
  maxDate?: Date;
436
  excludeDates?: Date[];
437
  excludeDateIntervals?: Array<{start: Date, end: Date}>;
438
  includeDates?: Date[];
439
  includeDateIntervals?: Array<{start: Date, end: Date}>;
440
  filterDate?: (date: Date) => boolean;
441
}): boolean;
442

443
/**
444
 * Check if month should be disabled
445
 */
446
function isMonthDisabled(month: Date, props: any): boolean;
447

448
/**
449
 * Check if year should be disabled
450
 */
451
function isYearDisabled(year: number, props: any): boolean;
452

453
/**
454
 * Check if month is disabled before given date
455
 */
456
function monthDisabledBefore(day: Date, props: any): boolean;
457

458
/**
459
 * Check if month is disabled after given date
460
 */
461
function monthDisabledAfter(day: Date, props: any): boolean;
462

463
/**
464
 * Check if quarter is disabled before given date
465
 */
466
function quarterDisabledBefore(day: Date, props: any): boolean;
467

468
/**
469
 * Check if quarter is disabled after given date
470
 */
471
function quarterDisabledAfter(day: Date, props: any): boolean;
472

473
/**
474
 * Check if year is disabled before given date
475
 */
476
function yearDisabledBefore(day: Date, props: any): boolean;
477

478
/**
479
 * Check if year is disabled after given date
480
 */
481
function yearDisabledAfter(day: Date, props: any): boolean;
482

483
/**
484
 * Check if years are disabled before given date
485
 */
486
function yearsDisabledBefore(day: Date, props: any): boolean;
487

488
/**
489
 * Check if years are disabled after given date
490
 */
491
function yearsDisabledAfter(day: Date, props: any): boolean;
492
```
493

494
### Effective Date Functions
495

496
Functions for getting effective min/max dates considering all constraints.
497

498
```typescript { .api }
499
/**
500
 * Get effective minimum date considering all constraints
501
 * @param props - DatePicker props
502
 * @returns Effective minimum date
503
 */
504
function getEffectiveMinDate(props: {
505
  minDate?: Date;
506
  includeDates?: Date[];
507
  includeDateIntervals?: Array<{start: Date, end: Date}>;
508
}): Date | undefined;
509

510
/**
511
 * Get effective maximum date considering all constraints
512
 * @param props - DatePicker props
513
 * @returns Effective maximum date
514
 */
515
function getEffectiveMaxDate(props: {
516
  maxDate?: Date;
517
  includeDates?: Date[];
518
  includeDateIntervals?: Array<{start: Date, end: Date}>;
519
}): Date | undefined;
520
```
521

522
### Utility Functions
523

524
Helper functions for common date operations.
525

526
```typescript { .api }
527
/**
528
 * Convert highlight dates array to Map for faster lookup
529
 * @param highlightDates - Array of dates or HighlightDate objects
530
 * @returns Map with date keys and HighlightDate values
531
 */
532
function getHighLightDaysMap(
533
  highlightDates?: Array<Date | HighlightDate>
534
): Map<string, HighlightDate>;
535

536
/**
537
 * Convert holidays array to Map for faster lookup
538
 * @param holidays - Array of holiday objects
539
 * @returns Map with date keys and holiday values
540
 */
541
function getHolidaysMap(holidays?: Array<{date: Date, holidayName: string}>): Map<string, string>;
542

543
/**
544
 * Add leading zero to single digit numbers
545
 * @param i - Number to pad
546
 * @returns Padded string
547
 */
548
function addZero(i: number): string;
549

550
/**
551
 * Get range of years for year picker
552
 * @param date - Current date
553
 * @param yearItemNumber - Number of years to show
554
 * @returns Object with start and end years
555
 */
556
function getYearsPeriod(
557
  date: Date,
558
  yearItemNumber?: number
559
): { startPeriod: number; endPeriod: number };
560

561
/**
562
 * Get times to inject after specific time
563
 * @param currentTime - Current time
564
 * @param currentMultiplier - Time multiplier
565
 * @param intervals - Time intervals
566
 * @param injectedTimes - Times to inject
567
 * @returns Array of times to inject
568
 */
569
function timesToInjectAfter(
570
  currentTime: Date,
571
  currentMultiplier: number,
572
  intervals: number,
573
  injectedTimes: Date[]
574
): Date[];
575
```
576

577
**Usage Examples:**
578

579
```typescript
580
import {
581
  newDate,
582
  parseDate,
583
  formatDate,
584
  addDays,
585
  isSameDay,
586
  isAfter,
587
  getStartOfWeek,
588
  safeDateFormat
589
} from "react-datepicker";
590

591
// Date creation and parsing
592
const today = newDate();
593
const parsedDate = parseDate("2023-12-25", "yyyy-MM-dd", "en");
594

595
// Date formatting
596
const formatted = formatDate(today, "MM/dd/yyyy");
597
const safeFormatted = safeDateFormat(today, { dateFormat: "PP" });
598

599
// Date math
600
const nextWeek = addDays(today, 7);
601
const weekStart = getStartOfWeek(today);
602

603
// Date comparisons
604
const isToday = isSameDay(someDate, today);
605
const isFuture = isAfter(someDate, today);
606

607
// Working with date ranges
608
const isInRange = isDayInRange(checkDate, startDate, endDate);
609

610
// Validation
611
const isValid = isDayDisabled(checkDate, {
612
  minDate: new Date(),
613
  excludeDates: [blackoutDate],
614
  filterDate: (date) => date.getDay() !== 0 // No Sundays
615
});
616
```