0
# Date Module
1

2
The Sugar Date module provides comprehensive date manipulation, formatting, and internationalization capabilities. With over 150 methods, it offers complete date/time functionality including creation, manipulation, comparison, calculation, formatting, and locale support.
3

4
## Core Imports
5

6
```typescript
7
import Sugar from "sugar";
8

9
// Enable Date methods
10
Sugar.extend();
11

12
// Or import specific date functionality
13
import Sugar from "sugar/date";
14
```
15

16
For CommonJS:
17

18
```javascript
19
const Sugar = require("sugar");
20
Sugar.extend();
21

22
// Or specific module
23
const Sugar = require("sugar/date");
24
```
25

26
## Basic Usage
27

28
```typescript
29
import Sugar from "sugar";
30
Sugar.extend();
31

32
// Create dates from various inputs
33
const date1 = Sugar.Date.create("next Friday");
34
const date2 = Sugar.Date.create("2025-12-25");
35
const date3 = Sugar.Date.create("3 days ago");
36

37
// Date manipulation
38
const future = Sugar.Date.addDays(Sugar.Date.beginningOfWeek(Sugar.Date.addDays(date1, 5)));
39
const past = Sugar.Date.rewind(Sugar.Date.create(), "3 weeks 2 days");
40

41
// Formatting
42
const formatted = Sugar.Date.format(date1, "MMM dd, yyyy");
43
const relative = Sugar.Date.relative(date2); // "in 3 months"
44

45
// Comparisons and tests
46
const isWeekend = Sugar.Date.isWeekend(date1);
47
const isFuture = Sugar.Date.isFuture(date2);
48
const daysBetween = Sugar.Date.daysSince(date1, date2);
49
```
50

51
## Capabilities
52

53
### Date Creation and Configuration
54

55
Date creation from various input formats and locale management.
56

57
```typescript { .api }
58
/**
59
 * Creates a date from various input types with optional configuration
60
 * @param d - Date input (string, number, Date, or undefined for now)
61
 * @param options - Creation options
62
 * @returns New Date instance
63
 */
64
function create(d?: any, options?: DateCreateOptions): Date;
65

66
/**
67
 * Creates a date range between two dates
68
 * @param start - Start date (any valid date input)
69
 * @param end - End date (any valid date input)  
70
 * @returns Range object containing date range
71
 */
72
function range(start?: any, end?: any): Range;
73

74
/**
75
 * Adds a custom locale for date parsing and formatting
76
 * @param localeCode - Locale identifier (e.g. "en-US")
77
 * @param def - Locale definition object
78
 */
79
function addLocale(localeCode: string, def: any): void;
80

81
/**
82
 * Gets all available locale codes
83
 * @returns Array of locale code strings
84
 */
85
function getAllLocaleCodes(): string[];
86

87
/**
88
 * Gets all locale objects
89
 * @returns Array of locale objects
90
 */
91
function getAllLocales(): Locale[];
92

93
/**
94
 * Gets a specific locale object
95
 * @param localeCode - Locale code (defaults to current locale)
96
 * @returns Locale object or undefined
97
 */
98
function getLocale(localeCode?: string): Locale | undefined;
99

100
/**
101
 * Removes a custom locale
102
 * @param localeCode - Locale code to remove
103
 */
104
function removeLocale(localeCode: string): void;
105

106
/**
107
 * Sets the active locale for date operations
108
 * @param localeCode - Locale code to activate
109
 */
110
function setLocale(localeCode: string): void;
111
```
112

113
**Usage Examples:**
114

115
```typescript
116
// Create dates from strings
117
const christmas = Sugar.Date.create("December 25, 2025");
118
const meeting = Sugar.Date.create("next Tuesday at 3pm");
119
const deadline = Sugar.Date.create("in 2 weeks");
120

121
// Create with options
122
const utcDate = Sugar.Date.create("2025-06-15", { fromUTC: true });
123
const pastPreferred = Sugar.Date.create("May", { past: true });
124

125
// Create ranges
126
const quarter = Sugar.Date.range("January 1", "March 31");
127
const week = Sugar.Date.range("last Monday", "next Sunday");
128

129
// Locale management
130
Sugar.Date.setLocale("fr");
131
const frenchDate = Sugar.Date.create("15 janvier 2025");
132
```
133

134
### Date Manipulation
135

136
Methods for adding, subtracting, and setting date components.
137

138
```typescript { .api }
139
/**
140
 * Adds days to a date
141
 * @param instance - Date instance
142
 * @param n - Number of days to add
143
 * @param reset - Reset smaller units to beginning
144
 * @returns Modified date instance
145
 */
146
function addDays(instance: Date, n: number, reset?: boolean): Date;
147

148
/**
149
 * Adds hours to a date
150
 * @param instance - Date instance  
151
 * @param n - Number of hours to add
152
 * @param reset - Reset smaller units to beginning
153
 * @returns Modified date instance
154
 */
155
function addHours(instance: Date, n: number, reset?: boolean): Date;
156

157
/**
158
 * Adds minutes to a date
159
 * @param instance - Date instance
160
 * @param n - Number of minutes to add
161
 * @param reset - Reset smaller units to beginning
162
 * @returns Modified date instance
163
 */
164
function addMinutes(instance: Date, n: number, reset?: boolean): Date;
165

166
/**
167
 * Adds seconds to a date
168
 * @param instance - Date instance
169
 * @param n - Number of seconds to add
170
 * @param reset - Reset smaller units to beginning
171
 * @returns Modified date instance
172
 */
173
function addSeconds(instance: Date, n: number, reset?: boolean): Date;
174

175
/**
176
 * Adds weeks to a date
177
 * @param instance - Date instance
178
 * @param n - Number of weeks to add
179
 * @param reset - Reset smaller units to beginning
180
 * @returns Modified date instance
181
 */
182
function addWeeks(instance: Date, n: number, reset?: boolean): Date;
183

184
/**
185
 * Adds months to a date
186
 * @param instance - Date instance
187
 * @param n - Number of months to add
188
 * @param reset - Reset smaller units to beginning
189
 * @returns Modified date instance
190
 */
191
function addMonths(instance: Date, n: number, reset?: boolean): Date;
192

193
/**
194
 * Adds years to a date
195
 * @param instance - Date instance
196
 * @param n - Number of years to add
197
 * @param reset - Reset smaller units to beginning
198
 * @returns Modified date instance
199
 */
200
function addYears(instance: Date, n: number, reset?: boolean): Date;
201

202
/**
203
 * Advances a date by a time unit or compound string
204
 * @param instance - Date instance
205
 * @param set - Time unit object or string (e.g. "3 days 2 hours")
206
 * @param reset - Reset smaller units to beginning
207
 * @returns Modified date instance
208
 */
209
function advance(instance: Date, set: any, reset?: boolean): Date;
210

211
/**
212
 * Rewinds a date by a time unit or compound string
213
 * @param instance - Date instance
214
 * @param set - Time unit object or string (e.g. "1 week 3 days")
215
 * @param reset - Reset smaller units to beginning  
216
 * @returns Modified date instance
217
 */
218
function rewind(instance: Date, set: any, reset?: boolean): Date;
219

220
/**
221
 * Sets specific date components
222
 * @param instance - Date instance
223
 * @param set - Object or string specifying what to set
224
 * @param reset - Reset smaller units to beginning
225
 * @returns Modified date instance
226
 */
227
function set(instance: Date, set: any, reset?: boolean): Date;
228

229
/**
230
 * Resets a date to the beginning of a time unit
231
 * @param instance - Date instance
232
 * @param unit - Time unit ("day", "week", "month", "year")
233
 * @param locale - Locale for week calculations
234
 * @returns Modified date instance
235
 */
236
function reset(instance: Date, unit?: string, locale?: string): Date;
237
```
238

239
**Usage Examples:**
240

241
```typescript
242
const today = Sugar.Date.create();
243

244
// Add time units
245
const tomorrow = Sugar.Date.addDays(Sugar.Date.clone(today), 1);
246
const nextWeek = Sugar.Date.addWeeks(Sugar.Date.clone(today), 1);
247
const nextYear = Sugar.Date.addYears(Sugar.Date.clone(today), 1);
248

249
// Complex additions with reset
250
const startOfNextMonth = Sugar.Date.addMonths(Sugar.Date.clone(today), 1, true); // Resets to 1st day
251

252
// Advance/rewind with strings
253
const future = Sugar.Date.advance(Sugar.Date.clone(today), "2 weeks 3 days 4 hours");
254
const past = Sugar.Date.rewind(Sugar.Date.clone(today), "1 month 2 weeks");
255

256
// Set specific components
257
const newYear = Sugar.Date.set(Sugar.Date.clone(today), { month: 0, day: 1 }); // January 1st
258
const midnight = Sugar.Date.set(Sugar.Date.clone(today), { hour: 0, minute: 0, second: 0 });
259

260
// Reset to boundaries
261
const startOfWeek = Sugar.Date.reset(Sugar.Date.clone(today), "week");
262
const startOfMonth = Sugar.Date.reset(Sugar.Date.clone(today), "month");
263
```
264

265
### Date Comparison
266

267
Methods for comparing dates and testing relationships.
268

269
```typescript { .api }
270
/**
271
 * Tests if two dates are equal within an optional margin
272
 * @param instance - Date instance
273
 * @param date - Date to compare with
274
 * @param margin - Margin of error in milliseconds
275
 * @returns True if dates are equal
276
 */
277
function is(instance: Date, date: any, margin?: number): boolean;
278

279
/**
280
 * Tests if date is after another date
281
 * @param instance - Date instance
282
 * @param date - Date to compare with
283
 * @param margin - Margin of error in milliseconds
284
 * @returns True if date is after
285
 */
286
function isAfter(instance: Date, date: any, margin?: number): boolean;
287

288
/**
289
 * Tests if date is before another date
290
 * @param instance - Date instance
291
 * @param date - Date to compare with
292
 * @param margin - Margin of error in milliseconds
293
 * @returns True if date is before
294
 */
295
function isBefore(instance: Date, date: any, margin?: number): boolean;
296

297
/**
298
 * Tests if date is between two other dates
299
 * @param instance - Date instance
300
 * @param start - Start date for range
301
 * @param end - End date for range
302
 * @param margin - Margin of error in milliseconds
303
 * @returns True if date is between start and end
304
 */
305
function isBetween(instance: Date, start: any, end: any, margin?: number): boolean;
306
```
307

308
### Date Period Tests
309

310
Methods for testing if a date falls within specific time periods or has certain characteristics.
311

312
```typescript { .api }
313
/**
314
 * Tests if date falls on a Monday
315
 * @param instance - Date instance
316
 * @returns True if date is Monday
317
 */
318
function isMonday(instance: Date): boolean;
319

320
/**
321
 * Tests if date falls on a Tuesday
322
 * @param instance - Date instance
323
 * @returns True if date is Tuesday
324
 */
325
function isTuesday(instance: Date): boolean;
326

327
/**
328
 * Tests if date falls on a Wednesday
329
 * @param instance - Date instance
330
 * @returns True if date is Wednesday
331
 */
332
function isWednesday(instance: Date): boolean;
333

334
/**
335
 * Tests if date falls on a Thursday
336
 * @param instance - Date instance
337
 * @returns True if date is Thursday
338
 */
339
function isThursday(instance: Date): boolean;
340

341
/**
342
 * Tests if date falls on a Friday
343
 * @param instance - Date instance
344
 * @returns True if date is Friday
345
 */
346
function isFriday(instance: Date): boolean;
347

348
/**
349
 * Tests if date falls on a Saturday
350
 * @param instance - Date instance
351
 * @returns True if date is Saturday
352
 */
353
function isSaturday(instance: Date): boolean;
354

355
/**
356
 * Tests if date falls on a Sunday
357
 * @param instance - Date instance
358
 * @returns True if date is Sunday
359
 */
360
function isSunday(instance: Date): boolean;
361

362
/**
363
 * Tests if date is in the future
364
 * @param instance - Date instance
365
 * @returns True if date is in the future
366
 */
367
function isFuture(instance: Date): boolean;
368

369
/**
370
 * Tests if date is in the past
371
 * @param instance - Date instance
372
 * @returns True if date is in the past
373
 */
374
function isPast(instance: Date): boolean;
375

376
/**
377
 * Tests if date is today
378
 * @param instance - Date instance
379
 * @returns True if date is today
380
 */
381
function isToday(instance: Date): boolean;
382

383
/**
384
 * Tests if date is tomorrow
385
 * @param instance - Date instance
386
 * @returns True if date is tomorrow
387
 */
388
function isTomorrow(instance: Date): boolean;
389

390
/**
391
 * Tests if date is yesterday
392
 * @param instance - Date instance
393
 * @returns True if date is yesterday
394
 */
395
function isYesterday(instance: Date): boolean;
396

397
/**
398
 * Tests if date is in the current week
399
 * @param instance - Date instance
400
 * @param locale - Locale for week calculation
401
 * @returns True if date is this week
402
 */
403
function isThisWeek(instance: Date, locale?: string): boolean;
404

405
/**
406
 * Tests if date is in the current month
407
 * @param instance - Date instance
408
 * @param locale - Locale for month calculation
409
 * @returns True if date is this month
410
 */
411
function isThisMonth(instance: Date, locale?: string): boolean;
412

413
/**
414
 * Tests if date is in the current year
415
 * @param instance - Date instance
416
 * @param locale - Locale for year calculation
417
 * @returns True if date is this year
418
 */
419
function isThisYear(instance: Date, locale?: string): boolean;
420

421
/**
422
 * Tests if date is in the last week
423
 * @param instance - Date instance
424
 * @param locale - Locale for week calculation
425
 * @returns True if date is last week
426
 */
427
function isLastWeek(instance: Date, locale?: string): boolean;
428

429
/**
430
 * Tests if date is in the last month
431
 * @param instance - Date instance
432
 * @param locale - Locale for month calculation
433
 * @returns True if date is last month
434
 */
435
function isLastMonth(instance: Date, locale?: string): boolean;
436

437
/**
438
 * Tests if date is in the last year
439
 * @param instance - Date instance
440
 * @param locale - Locale for year calculation
441
 * @returns True if date is last year
442
 */
443
function isLastYear(instance: Date, locale?: string): boolean;
444

445
/**
446
 * Tests if date is in the next week
447
 * @param instance - Date instance
448
 * @param locale - Locale for week calculation
449
 * @returns True if date is next week
450
 */
451
function isNextWeek(instance: Date, locale?: string): boolean;
452

453
/**
454
 * Tests if date is in the next month
455
 * @param instance - Date instance
456
 * @param locale - Locale for month calculation
457
 * @returns True if date is next month
458
 */
459
function isNextMonth(instance: Date, locale?: string): boolean;
460

461
/**
462
 * Tests if date is in the next year
463
 * @param instance - Date instance
464
 * @param locale - Locale for year calculation
465
 * @returns True if date is next year
466
 */
467
function isNextYear(instance: Date, locale?: string): boolean;
468

469
/**
470
 * Tests if date falls on a weekday (Monday-Friday)
471
 * @param instance - Date instance
472
 * @returns True if date is a weekday
473
 */
474
function isWeekday(instance: Date): boolean;
475

476
/**
477
 * Tests if date falls on a weekend (Saturday-Sunday)
478
 * @param instance - Date instance
479
 * @returns True if date is a weekend
480
 */
481
function isWeekend(instance: Date): boolean;
482

483
/**
484
 * Tests if date is in a leap year
485
 * @param instance - Date instance
486
 * @returns True if date is in a leap year
487
 */
488
function isLeapYear(instance: Date): boolean;
489

490
/**
491
 * Tests if date is in UTC
492
 * @param instance - Date instance
493
 * @returns True if date is UTC
494
 */
495
function isUTC(instance: Date): boolean;
496

497
/**
498
 * Tests if date is valid
499
 * @param instance - Date instance
500
 * @returns True if date is valid
501
 */
502
function isValid(instance: Date): boolean;
503
```
504

505
### Date Calculations
506

507
Methods for calculating time differences between dates in various units.
508

509
```typescript { .api }
510
/**
511
 * Gets the number of days from the date to now or another date
512
 * @param instance - Date instance
513
 * @param date - Date to compare with (defaults to now)
514
 * @param options - Calculation options
515
 * @returns Number of days
516
 */
517
function daysAgo(instance: Date, date?: any, options?: any): number;
518

519
/**
520
 * Gets the number of days from now to the date
521
 * @param instance - Date instance
522
 * @param date - Date to compare with (defaults to now)
523
 * @param options - Calculation options
524
 * @returns Number of days
525
 */
526
function daysFromNow(instance: Date, date?: any, options?: any): number;
527

528
/**
529
 * Gets the number of days since another date
530
 * @param instance - Date instance
531
 * @param date - Date to compare with
532
 * @param options - Calculation options
533
 * @returns Number of days since date
534
 */
535
function daysSince(instance: Date, date?: any, options?: any): number;
536

537
/**
538
 * Gets the number of days until another date
539
 * @param instance - Date instance
540
 * @param date - Date to compare with
541
 * @param options - Calculation options
542
 * @returns Number of days until date
543
 */
544
function daysUntil(instance: Date, date?: any, options?: any): number;
545

546
/**
547
 * Gets the number of hours from the date to now or another date
548
 * @param instance - Date instance
549
 * @param date - Date to compare with (defaults to now)
550
 * @param options - Calculation options
551
 * @returns Number of hours
552
 */
553
function hoursAgo(instance: Date, date?: any, options?: any): number;
554

555
/**
556
 * Gets the number of hours from now to the date
557
 * @param instance - Date instance
558
 * @param date - Date to compare with (defaults to now)
559
 * @param options - Calculation options
560
 * @returns Number of hours
561
 */
562
function hoursFromNow(instance: Date, date?: any, options?: any): number;
563

564
/**
565
 * Gets the number of hours since another date
566
 * @param instance - Date instance
567
 * @param date - Date to compare with
568
 * @param options - Calculation options
569
 * @returns Number of hours since date
570
 */
571
function hoursSince(instance: Date, date?: any, options?: any): number;
572

573
/**
574
 * Gets the number of hours until another date
575
 * @param instance - Date instance
576
 * @param date - Date to compare with
577
 * @param options - Calculation options
578
 * @returns Number of hours until date
579
 */
580
function hoursUntil(instance: Date, date?: any, options?: any): number;
581

582
/**
583
 * Gets the number of minutes from the date to now or another date
584
 * @param instance - Date instance
585
 * @param date - Date to compare with (defaults to now)
586
 * @param options - Calculation options
587
 * @returns Number of minutes
588
 */
589
function minutesAgo(instance: Date, date?: any, options?: any): number;
590

591
/**
592
 * Gets the number of minutes from now to the date
593
 * @param instance - Date instance
594
 * @param date - Date to compare with (defaults to now)
595
 * @param options - Calculation options
596
 * @returns Number of minutes
597
 */
598
function minutesFromNow(instance: Date, date?: any, options?: any): number;
599

600
/**
601
 * Gets the number of minutes since another date
602
 * @param instance - Date instance
603
 * @param date - Date to compare with
604
 * @param options - Calculation options
605
 * @returns Number of minutes since date
606
 */
607
function minutesSince(instance: Date, date?: any, options?: any): number;
608

609
/**
610
 * Gets the number of minutes until another date
611
 * @param instance - Date instance
612
 * @param date - Date to compare with
613
 * @param options - Calculation options
614
 * @returns Number of minutes until date
615
 */
616
function minutesUntil(instance: Date, date?: any, options?: any): number;
617

618
/**
619
 * Gets the number of seconds from the date to now or another date
620
 * @param instance - Date instance
621
 * @param date - Date to compare with (defaults to now)
622
 * @param options - Calculation options
623
 * @returns Number of seconds
624
 */
625
function secondsAgo(instance: Date, date?: any, options?: any): number;
626

627
/**
628
 * Gets the number of seconds from now to the date
629
 * @param instance - Date instance
630
 * @param date - Date to compare with (defaults to now)
631
 * @param options - Calculation options
632
 * @returns Number of seconds
633
 */
634
function secondsFromNow(instance: Date, date?: any, options?: any): number;
635

636
/**
637
 * Gets the number of seconds since another date
638
 * @param instance - Date instance
639
 * @param date - Date to compare with
640
 * @param options - Calculation options
641
 * @returns Number of seconds since date
642
 */
643
function secondsSince(instance: Date, date?: any, options?: any): number;
644

645
/**
646
 * Gets the number of seconds until another date
647
 * @param instance - Date instance
648
 * @param date - Date to compare with
649
 * @param options - Calculation options
650
 * @returns Number of seconds until date
651
 */
652
function secondsUntil(instance: Date, date?: any, options?: any): number;
653

654
/**
655
 * Gets the number of milliseconds from the date to now or another date
656
 * @param instance - Date instance
657
 * @param date - Date to compare with (defaults to now)
658
 * @param options - Calculation options
659
 * @returns Number of milliseconds
660
 */
661
function millisecondsAgo(instance: Date, date?: any, options?: any): number;
662

663
/**
664
 * Gets the number of milliseconds from now to the date
665
 * @param instance - Date instance
666
 * @param date - Date to compare with (defaults to now)
667
 * @param options - Calculation options
668
 * @returns Number of milliseconds
669
 */
670
function millisecondsFromNow(instance: Date, date?: any, options?: any): number;
671

672
/**
673
 * Gets the number of milliseconds since another date
674
 * @param instance - Date instance
675
 * @param date - Date to compare with
676
 * @param options - Calculation options
677
 * @returns Number of milliseconds since date
678
 */
679
function millisecondsSince(instance: Date, date?: any, options?: any): number;
680

681
/**
682
 * Gets the number of milliseconds until another date
683
 * @param instance - Date instance
684
 * @param date - Date to compare with
685
 * @param options - Calculation options
686
 * @returns Number of milliseconds until date
687
 */
688
function millisecondsUntil(instance: Date, date?: any, options?: any): number;
689

690
/**
691
 * Gets the number of weeks from the date to now or another date
692
 * @param instance - Date instance
693
 * @param date - Date to compare with (defaults to now)
694
 * @param options - Calculation options
695
 * @returns Number of weeks
696
 */
697
function weeksAgo(instance: Date, date?: any, options?: any): number;
698

699
/**
700
 * Gets the number of weeks from now to the date
701
 * @param instance - Date instance
702
 * @param date - Date to compare with (defaults to now)
703
 * @param options - Calculation options
704
 * @returns Number of weeks
705
 */
706
function weeksFromNow(instance: Date, date?: any, options?: any): number;
707

708
/**
709
 * Gets the number of weeks since another date
710
 * @param instance - Date instance
711
 * @param date - Date to compare with
712
 * @param options - Calculation options
713
 * @returns Number of weeks since date
714
 */
715
function weeksSince(instance: Date, date?: any, options?: any): number;
716

717
/**
718
 * Gets the number of weeks until another date
719
 * @param instance - Date instance
720
 * @param date - Date to compare with
721
 * @param options - Calculation options
722
 * @returns Number of weeks until date
723
 */
724
function weeksUntil(instance: Date, date?: any, options?: any): number;
725

726
/**
727
 * Gets the number of months from the date to now or another date
728
 * @param instance - Date instance
729
 * @param date - Date to compare with (defaults to now)
730
 * @param options - Calculation options
731
 * @returns Number of months
732
 */
733
function monthsAgo(instance: Date, date?: any, options?: any): number;
734

735
/**
736
 * Gets the number of months from now to the date
737
 * @param instance - Date instance
738
 * @param date - Date to compare with (defaults to now)
739
 * @param options - Calculation options
740
 * @returns Number of months
741
 */
742
function monthsFromNow(instance: Date, date?: any, options?: any): number;
743

744
/**
745
 * Gets the number of months since another date
746
 * @param instance - Date instance
747
 * @param date - Date to compare with
748
 * @param options - Calculation options
749
 * @returns Number of months since date
750
 */
751
function monthsSince(instance: Date, date?: any, options?: any): number;
752

753
/**
754
 * Gets the number of months until another date
755
 * @param instance - Date instance
756
 * @param date - Date to compare with
757
 * @param options - Calculation options
758
 * @returns Number of months until date
759
 */
760
function monthsUntil(instance: Date, date?: any, options?: any): number;
761

762
/**
763
 * Gets the number of years from the date to now or another date
764
 * @param instance - Date instance
765
 * @param date - Date to compare with (defaults to now)
766
 * @param options - Calculation options
767
 * @returns Number of years
768
 */
769
function yearsAgo(instance: Date, date?: any, options?: any): number;
770

771
/**
772
 * Gets the number of years from now to the date
773
 * @param instance - Date instance
774
 * @param date - Date to compare with (defaults to now)
775
 * @param options - Calculation options
776
 * @returns Number of years
777
 */
778
function yearsFromNow(instance: Date, date?: any, options?: any): number;
779

780
/**
781
 * Gets the number of years since another date
782
 * @param instance - Date instance
783
 * @param date - Date to compare with
784
 * @param options - Calculation options
785
 * @returns Number of years since date
786
 */
787
function yearsSince(instance: Date, date?: any, options?: any): number;
788

789
/**
790
 * Gets the number of years until another date
791
 * @param instance - Date instance
792
 * @param date - Date to compare with
793
 * @param options - Calculation options
794
 * @returns Number of years until date
795
 */
796
function yearsUntil(instance: Date, date?: any, options?: any): number;
797
```
798

799
**Usage Examples:**
800

801
```typescript
802
const now = Sugar.Date.create();
803
const birthday = Sugar.Date.create("1990-05-15");
804
const meeting = Sugar.Date.create("next Friday at 2pm");
805

806
// Calculate differences
807
const age = Sugar.Date.yearsAgo(birthday); // 34 (years old)
808
const daysToMeeting = Sugar.Date.daysFromNow(meeting); // 3 (days until meeting)
809
const hoursSince = Sugar.Date.hoursSince(birthday); // ~298,440 (hours since birth)
810

811
// Compare specific dates
812
const project1 = Sugar.Date.create("2025-01-15");
813
const project2 = Sugar.Date.create("2025-03-01");
814
const monthsBetween = Sugar.Date.monthsUntil(project1, project2); // ~1.5 months
815
```
816

817
### Date Formatting
818

819
Methods for converting dates to formatted strings for display.
820

821
```typescript { .api }
822
/**
823
 * Formats a date using a format string with locale support
824
 * @param instance - Date instance
825
 * @param format - Format string (e.g. "MMM dd, yyyy")
826
 * @param locale - Locale code
827
 * @returns Formatted date string
828
 */
829
function format(instance: Date, format?: string, locale?: string): string;
830

831
/**
832
 * Formats date in full locale format
833
 * @param instance - Date instance
834
 * @param locale - Locale code
835
 * @returns Full formatted date string
836
 */
837
function full(instance: Date, locale?: string): string;
838

839
/**
840
 * Formats date in long locale format
841
 * @param instance - Date instance
842
 * @param locale - Locale code
843
 * @returns Long formatted date string
844
 */
845
function long(instance: Date, locale?: string): string;
846

847
/**
848
 * Formats date in medium locale format
849
 * @param instance - Date instance
850
 * @param locale - Locale code
851
 * @returns Medium formatted date string
852
 */
853
function medium(instance: Date, locale?: string): string;
854

855
/**
856
 * Formats date in short locale format
857
 * @param instance - Date instance
858
 * @param locale - Locale code
859
 * @returns Short formatted date string
860
 */
861
function short(instance: Date, locale?: string): string;
862

863
/**
864
 * Formats date in ISO 8601 format
865
 * @param instance - Date instance
866
 * @returns ISO formatted date string (YYYY-MM-DDTHH:mm:ss.sssZ)
867
 */
868
function iso(instance: Date): string;
869

870
/**
871
 * Formats date as a relative time string
872
 * @param instance - Date instance
873
 * @param locale - Locale code
874
 * @param relativeFn - Custom relative function
875
 * @returns Relative time string (e.g. "3 days ago", "in 2 hours")
876
 */
877
function relative(instance: Date, locale?: string, relativeFn?: Function): string;
878

879
/**
880
 * Formats date relative to another specific date
881
 * @param instance - Date instance
882
 * @param date - Date to compare with
883
 * @param locale - Locale code
884
 * @returns Relative time string
885
 */
886
function relativeTo(instance: Date, date: any, locale?: string): string;
887
```
888

889
**Usage Examples:**
890

891
```typescript
892
const date = Sugar.Date.create("2025-06-15 14:30:00");
893

894
// Custom formatting
895
const custom = Sugar.Date.format(date, "MMM dd, yyyy 'at' h:mm a"); // "Jun 15, 2025 at 2:30 PM"
896
const european = Sugar.Date.format(date, "dd/MM/yyyy"); // "15/06/2025"
897
const time = Sugar.Date.format(date, "HH:mm:ss"); // "14:30:00"
898

899
// Predefined formats
900
const fullFormat = Sugar.Date.full(date); // "Sunday, June 15, 2025"
901
const longFormat = Sugar.Date.long(date); // "June 15, 2025"
902
const mediumFormat = Sugar.Date.medium(date); // "Jun 15, 2025"
903
const shortFormat = Sugar.Date.short(date); // "6/15/25"
904

905
// ISO format
906
const isoString = Sugar.Date.iso(date); // "2025-06-15T14:30:00.000Z"
907

908
// Relative formatting
909
const past = Sugar.Date.create("2 days ago");
910
const future = Sugar.Date.create("in 3 hours");
911
const relativeStr1 = Sugar.Date.relative(past); // "2 days ago"
912
const relativeStr2 = Sugar.Date.relative(future); // "in 3 hours"
913

914
// Relative to specific date
915
const birthday = Sugar.Date.create("1990-05-15");
916
const relativeAge = Sugar.Date.relativeTo(birthday, date); // "35 years ago"
917
```
918

919
### Date Boundaries
920

921
Methods for finding the beginning and end of time periods.
922

923
```typescript { .api }
924
/**
925
 * Gets the beginning of the day (midnight)
926
 * @param instance - Date instance
927
 * @param locale - Locale code
928
 * @returns Date at start of day
929
 */
930
function beginningOfDay(instance: Date, locale?: string): Date;
931

932
/**
933
 * Gets the beginning of the week
934
 * @param instance - Date instance
935
 * @param locale - Locale code (affects first day of week)
936
 * @returns Date at start of week
937
 */
938
function beginningOfWeek(instance: Date, locale?: string): Date;
939

940
/**
941
 * Gets the beginning of the month
942
 * @param instance - Date instance
943
 * @param locale - Locale code
944
 * @returns Date at start of month (1st day)
945
 */
946
function beginningOfMonth(instance: Date, locale?: string): Date;
947

948
/**
949
 * Gets the beginning of the year
950
 * @param instance - Date instance
951
 * @param locale - Locale code
952
 * @returns Date at start of year (January 1st)
953
 */
954
function beginningOfYear(instance: Date, locale?: string): Date;
955

956
/**
957
 * Gets the beginning of the ISO week (Monday)
958
 * @param instance - Date instance
959
 * @returns Date at start of ISO week
960
 */
961
function beginningOfISOWeek(instance: Date): Date;
962

963
/**
964
 * Gets the end of the day (23:59:59.999)
965
 * @param instance - Date instance
966
 * @param locale - Locale code
967
 * @returns Date at end of day
968
 */
969
function endOfDay(instance: Date, locale?: string): Date;
970

971
/**
972
 * Gets the end of the week
973
 * @param instance - Date instance
974
 * @param locale - Locale code (affects last day of week)
975
 * @returns Date at end of week
976
 */
977
function endOfWeek(instance: Date, locale?: string): Date;
978

979
/**
980
 * Gets the end of the month (last day)
981
 * @param instance - Date instance
982
 * @param locale - Locale code
983
 * @returns Date at end of month
984
 */
985
function endOfMonth(instance: Date, locale?: string): Date;
986

987
/**
988
 * Gets the end of the year (December 31st)
989
 * @param instance - Date instance
990
 * @param locale - Locale code
991
 * @returns Date at end of year
992
 */
993
function endOfYear(instance: Date, locale?: string): Date;
994

995
/**
996
 * Gets the end of the ISO week (Sunday)
997
 * @param instance - Date instance
998
 * @returns Date at end of ISO week
999
 */
1000
function endOfISOWeek(instance: Date): Date;
1001
```
1002

1003
**Usage Examples:**
1004

1005
```typescript
1006
const someDate = Sugar.Date.create("2025-06-15 14:30:00"); // A Sunday
1007

1008
// Beginning of periods
1009
const dayStart = Sugar.Date.beginningOfDay(someDate); // "2025-06-15 00:00:00"
1010
const weekStart = Sugar.Date.beginningOfWeek(someDate); // Previous Sunday 00:00:00
1011
const monthStart = Sugar.Date.beginningOfMonth(someDate); // "2025-06-01 00:00:00"
1012
const yearStart = Sugar.Date.beginningOfYear(someDate); // "2025-01-01 00:00:00"
1013
const isoWeekStart = Sugar.Date.beginningOfISOWeek(someDate); // Previous Monday 00:00:00
1014

1015
// End of periods
1016
const dayEnd = Sugar.Date.endOfDay(someDate); // "2025-06-15 23:59:59.999"
1017
const weekEnd = Sugar.Date.endOfWeek(someDate); // Same Sunday 23:59:59.999
1018
const monthEnd = Sugar.Date.endOfMonth(someDate); // "2025-06-30 23:59:59.999"
1019
const yearEnd = Sugar.Date.endOfYear(someDate); // "2025-12-31 23:59:59.999"
1020
const isoWeekEnd = Sugar.Date.endOfISOWeek(someDate); // Next Sunday 23:59:59.999
1021

1022
// Common patterns
1023
const thisMonthRange = [Sugar.Date.beginningOfMonth(Sugar.Date.create()), Sugar.Date.endOfMonth(Sugar.Date.create())];
1024
const thisWeekSchedule = Sugar.Date.daysUntil(Sugar.Date.addDays(Sugar.Date.beginningOfWeek(Sugar.Date.create()), 1), Sugar.Date.endOfWeek(Sugar.Date.create())); // Days in work week
1025
```
1026

1027
### Date Utilities
1028

1029
Utility methods for date manipulation, cloning, and information retrieval.
1030

1031
```typescript { .api }
1032
/**
1033
 * Creates a copy of the date
1034
 * @param instance - Date instance
1035
 * @returns Cloned date instance
1036
 */
1037
function clone(instance: Date): Date;
1038

1039
/**
1040
 * Gets the number of days in the current month
1041
 * @param instance - Date instance
1042
 * @returns Number of days in month (28-31)
1043
 */
1044
function daysInMonth(instance: Date): number;
1045

1046
/**
1047
 * Parses and gets a date from various input formats
1048
 * @param instance - Date instance
1049
 * @param date - Date input to parse
1050
 * @param options - Parse options
1051
 * @returns Parsed date or original instance
1052
 */
1053
function get(instance: Date, date: any, options?: any): Date;
1054

1055
/**
1056
 * Gets the ISO week number (1-53)
1057
 * @param instance - Date instance
1058
 * @returns ISO week number
1059
 */
1060
function getISOWeek(instance: Date): number;
1061

1062
/**
1063
 * Gets the weekday number (0=Sunday, 1=Monday, etc.)
1064
 * @param instance - Date instance
1065
 * @returns Weekday number (0-6)
1066
 */
1067
function getWeekday(instance: Date): number;
1068

1069
/**
1070
 * Gets the UTC weekday number
1071
 * @param instance - Date instance
1072
 * @returns UTC weekday number (0-6)
1073
 */
1074
function getUTCWeekday(instance: Date): number;
1075

1076
/**
1077
 * Gets the UTC offset in minutes or ISO format
1078
 * @param instance - Date instance
1079
 * @param iso - Return in ISO format (+/-HH:MM)
1080
 * @returns UTC offset in minutes or ISO string
1081
 */
1082
function getUTCOffset(instance: Date, iso?: boolean): number | string;
1083

1084
/**
1085
 * Sets the ISO week number
1086
 * @param instance - Date instance
1087
 * @param value - ISO week number to set
1088
 * @returns Modified date instance
1089
 */
1090
function setISOWeek(instance: Date, value: any): Date;
1091

1092
/**
1093
 * Sets the weekday
1094
 * @param instance - Date instance
1095
 * @param value - Weekday to set (0-6 or name)
1096
 * @returns Modified date instance
1097
 */
1098
function setWeekday(instance: Date, value: any): Date;
1099

1100
/**
1101
 * Sets the date to UTC
1102
 * @param instance - Date instance
1103
 * @param value - Value to set for UTC conversion
1104
 * @returns Modified date instance
1105
 */
1106
function setUTC(instance: Date, value: any): Date;
1107
```
1108

1109
**Usage Examples:**
1110

1111
```typescript
1112
const original = Sugar.Date.create("2025-06-15");
1113

1114
// Clone for safe manipulation
1115
const copy = Sugar.Date.clone(original);
1116
Sugar.Date.addDays(copy, 5); // original is unchanged
1117

1118
// Date information
1119
const daysInJune = Sugar.Date.daysInMonth(original); // 30
1120
const weekNumber = Sugar.Date.getISOWeek(original); // 24 (24th week of year)
1121
const dayOfWeek = Sugar.Date.getWeekday(original); // 0 (Sunday)
1122

1123
// UTC operations
1124
const utcOffset = Sugar.Date.getUTCOffset(original); // -480 (minutes, varies by timezone)
1125
const utcOffsetISO = Sugar.Date.getUTCOffset(original, true); // "-08:00" (ISO format)
1126

1127
// Set weekday
1128
const nextMonday = Sugar.Date.setWeekday(Sugar.Date.clone(original), 1); // Set to Monday
1129
const previousFriday = Sugar.Date.setWeekday(Sugar.Date.clone(original), -2); // Set to Friday (negative = previous)
1130

1131
// Set ISO week
1132
const week20 = Sugar.Date.setISOWeek(Sugar.Date.clone(original), 20); // Move to 20th week of year
1133

1134
// Parse complex dates
1135
const parsed1 = Sugar.Date.get(Sugar.Date.create(), "next Friday at 3pm");
1136
const parsed2 = Sugar.Date.get(Sugar.Date.create(), "last day of March");
1137
```
1138

1139
## Types
1140

1141
```typescript { .api }
1142
/**
1143
 * Options for date creation with parsing and timezone control
1144
 */
1145
interface DateCreateOptions {
1146
  /** Locale code for parsing (e.g. "en-US", "fr") */
1147
  locale?: string;
1148
  /** Prefer past dates when parsing ambiguous inputs */
1149
  past?: boolean;
1150
  /** Prefer future dates when parsing ambiguous inputs */
1151
  future?: boolean;
1152
  /** Parse input as UTC time */
1153
  fromUTC?: boolean;
1154
  /** Set result as UTC time */
1155
  setUTC?: boolean;
1156
  /** Clone the input if it's already a Date */
1157
  clone?: boolean;
1158
}
1159

1160
/**
1161
 * Locale interface for internationalization support
1162
 */
1163
interface Locale {
1164
  /** Add a date format pattern */
1165
  addFormat(src: string, to?: Array<string>): void;
1166
  /** Get duration string for milliseconds */
1167
  getDuration(ms: number): string;
1168
  /** Get first day of week (0=Sunday, 1=Monday) */
1169
  getFirstDayOfWeek(): number;
1170
  /** Get first day of week year */
1171
  getFirstDayOfWeekYear(): number;
1172
  /** Get localized month name */
1173
  getMonthName(n: number): string;
1174
  /** Get localized weekday name */
1175
  getWeekdayName(n: number): string;
1176
}
1177

1178
/**
1179
 * Range class for date ranges with iteration and manipulation
1180
 */
1181
interface Range {
1182
  /** Clamp a date to this range */
1183
  clamp<T>(el: T): T;
1184
  /** Clone this range */
1185
  clone(): Range;
1186
  /** Test if date is contained in range */
1187
  contains<T>(el: T): boolean;
1188
  /** Iterate over range with specified interval */
1189
  every<T>(amount: string | number, everyFn?: Function): T[];
1190
  /** Get intersection with another range */
1191
  intersect(range: Range): Range;
1192
  /** Test if range is valid */
1193
  isValid(): boolean;
1194
  /** Get span of range */
1195
  span(): number;
1196
  /** Convert range to array */
1197
  toArray<T>(): T[];
1198
  /** Convert range to string */
1199
  toString(): string;
1200
  /** Get union with another range */
1201
  union(range: Range): Range;
1202
  
1203
  // Date range specific methods
1204
  /** Get range span in days */
1205
  days(): number;
1206
  /** Get range span in hours */
1207
  hours(): number;
1208
  /** Get range span in milliseconds */
1209
  milliseconds(): number;
1210
  /** Get range span in minutes */
1211
  minutes(): number;
1212
  /** Get range span in months */
1213
  months(): number;
1214
  /** Get range span in seconds */
1215
  seconds(): number;
1216
  /** Get range span in weeks */
1217
  weeks(): number;
1218
  /** Get range span in years */
1219
  years(): number;
1220
}
1221
```
1222

1223
## Locale System
1224

1225
Sugar Date includes comprehensive internationalization support with 18 built-in locales and the ability to add custom locales.
1226

1227
### Built-in Locales
1228

1229
Available locale codes: `ca` (Catalan), `da` (Danish), `de` (German), `es` (Spanish), `fi` (Finnish), `fr` (French), `it` (Italian), `ja` (Japanese), `ko` (Korean), `nl` (Dutch), `no` (Norwegian), `pl` (Polish), `pt` (Portuguese), `ru` (Russian), `sv` (Swedish), `zh-CN` (Chinese Simplified), `zh-TW` (Chinese Traditional).
1230

1231
**Usage Examples:**
1232

1233
```typescript
1234
// Set global locale
1235
Sugar.Date.setLocale("fr");
1236
const frenchDate = Sugar.Date.create("15 janvier 2025"); // French input
1237
const frenchFormat = Sugar.Date.format(frenchDate, "d MMMM yyyy"); // "15 janvier 2025"
1238

1239
// Per-operation locale
1240
const germanFormat = Sugar.Date.format(Sugar.Date.create(), "d. MMMM yyyy", "de"); // "15. Januar 2025"
1241
const spanishRelative = Sugar.Date.relative(Sugar.Date.create("yesterday"), "es"); // "ayer"
1242

1243
// Week calculations with locale
1244
Sugar.Date.setLocale("en-US"); // Week starts Sunday
1245
const usWeekStart = Sugar.Date.beginningOfWeek(Sugar.Date.create()); // Previous/current Sunday
1246

1247
Sugar.Date.setLocale("de"); // Week starts Monday  
1248
const germanWeekStart = Sugar.Date.beginningOfWeek(Sugar.Date.create()); // Previous/current Monday
1249

1250
// Custom locale
1251
Sugar.Date.addLocale("en-custom", {
1252
  months: ["Jan", "Feb", "Mar", /*...*/],
1253
  weekdays: ["Sun", "Mon", "Tue", /*...*/],
1254
  formats: {
1255
    "short": "M/d/yy",
1256
    "medium": "MMM d, yyyy"
1257
  }
1258
});
1259

1260
Sugar.Date.setLocale("en-custom");
1261
const customFormat = Sugar.Date.medium(Sugar.Date.create()); // Uses custom medium format
1262
```
1263

1264
## Common Patterns
1265

1266
### Date Validation and Error Handling
1267

1268
```typescript
1269
// Safe date creation
1270
function createSafeDate(input: any): Date | null {
1271
  try {
1272
    const date = Sugar.Date.create(input);
1273
    return Sugar.Date.isValid(date) ? date : null;
1274
  } catch (e) {
1275
    return null;
1276
  }
1277
}
1278

1279
// Validate date ranges
1280
function isValidRange(start: any, end: any): boolean {
1281
  const startDate = Sugar.Date.create(start);
1282
  const endDate = Sugar.Date.create(end);
1283
  return Sugar.Date.isValid(startDate) && Sugar.Date.isValid(endDate) && !Sugar.Date.isAfter(startDate, endDate);
1284
}
1285
```
1286

1287
### Business Date Calculations
1288

1289
```typescript
1290
// Add business days (skip weekends)
1291
function addBusinessDays(date: Date, days: number): Date {
1292
  const result = Sugar.Date.clone(date);
1293
  let remaining = days;
1294
  
1295
  while (remaining > 0) {
1296
    Sugar.Date.addDays(result, 1);
1297
    if (Sugar.Date.isWeekday(result)) {
1298
      remaining--;
1299
    }
1300
  }
1301
  
1302
  return result;
1303
}
1304

1305
// Get next business day
1306
function nextBusinessDay(date: Date): Date {
1307
  const next = Sugar.Date.addDays(Sugar.Date.clone(date), 1);
1308
  return Sugar.Date.isWeekend(next) ? nextBusinessDay(next) : next;
1309
}
1310

1311
// Calculate age in years
1312
function calculateAge(birthDate: Date): number {
1313
  return Math.floor(Sugar.Date.yearsAgo(birthDate));
1314
}
1315
```
1316

1317
### Date Formatting Utilities
1318

1319
```typescript
1320
// Smart relative formatting
1321
function smartRelative(date: Date): string {
1322
  const now = Sugar.Date.create();
1323
  const daysDiff = Math.abs(Sugar.Date.daysUntil(date, now));
1324
  
1325
  if (daysDiff === 0) return "Today";
1326
  if (daysDiff === 1) return Sugar.Date.isBefore(date, now) ? "Yesterday" : "Tomorrow";
1327
  if (daysDiff < 7) return Sugar.Date.relative(date);
1328
  if (daysDiff < 365) return Sugar.Date.format(date, "MMM d");
1329
  return Sugar.Date.format(date, "MMM d, yyyy");
1330
}
1331

1332
// Consistent date display
1333
function displayDate(date: Date, context: "list" | "detail" | "relative"): string {
1334
  switch (context) {
1335
    case "list": return Sugar.Date.format(date, "M/d/yyyy");
1336
    case "detail": return Sugar.Date.format(date, "EEEE, MMMM d, yyyy 'at' h:mm a");
1337
    case "relative": return smartRelative(date);
1338
    default: return date.toString();
1339
  }
1340
}
1341
```