ts-time-utils 1.1.0 → 3.0.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 (92) hide show
  1. package/README.md +567 -12
  2. package/dist/calculate.d.ts +7 -2
  3. package/dist/calculate.d.ts.map +1 -1
  4. package/dist/calculate.js +13 -3
  5. package/dist/calendar.d.ts +103 -0
  6. package/dist/calendar.d.ts.map +1 -1
  7. package/dist/calendar.js +224 -0
  8. package/dist/chain.d.ts +269 -0
  9. package/dist/chain.d.ts.map +1 -0
  10. package/dist/chain.js +422 -0
  11. package/dist/compare.d.ts +217 -0
  12. package/dist/compare.d.ts.map +1 -0
  13. package/dist/compare.js +417 -0
  14. package/dist/cron.d.ts +82 -0
  15. package/dist/cron.d.ts.map +1 -0
  16. package/dist/cron.js +294 -0
  17. package/dist/esm/calculate.d.ts +7 -2
  18. package/dist/esm/calculate.d.ts.map +1 -1
  19. package/dist/esm/calculate.js +13 -3
  20. package/dist/esm/calendar.d.ts +103 -0
  21. package/dist/esm/calendar.d.ts.map +1 -1
  22. package/dist/esm/calendar.js +224 -0
  23. package/dist/esm/chain.d.ts +269 -0
  24. package/dist/esm/chain.d.ts.map +1 -0
  25. package/dist/esm/chain.js +422 -0
  26. package/dist/esm/compare.d.ts +217 -0
  27. package/dist/esm/compare.d.ts.map +1 -0
  28. package/dist/esm/compare.js +417 -0
  29. package/dist/esm/cron.d.ts +82 -0
  30. package/dist/esm/cron.d.ts.map +1 -0
  31. package/dist/esm/cron.js +294 -0
  32. package/dist/esm/fiscal.d.ts +195 -0
  33. package/dist/esm/fiscal.d.ts.map +1 -0
  34. package/dist/esm/fiscal.js +295 -0
  35. package/dist/esm/format.d.ts +65 -0
  36. package/dist/esm/format.d.ts.map +1 -1
  37. package/dist/esm/format.js +202 -0
  38. package/dist/esm/holidays.d.ts +62 -0
  39. package/dist/esm/holidays.d.ts.map +1 -0
  40. package/dist/esm/holidays.js +793 -0
  41. package/dist/esm/index.d.ts +18 -6
  42. package/dist/esm/index.d.ts.map +1 -1
  43. package/dist/esm/index.js +20 -6
  44. package/dist/esm/iterate.d.ts +212 -0
  45. package/dist/esm/iterate.d.ts.map +1 -0
  46. package/dist/esm/iterate.js +409 -0
  47. package/dist/esm/parse.d.ts +45 -0
  48. package/dist/esm/parse.d.ts.map +1 -1
  49. package/dist/esm/parse.js +207 -0
  50. package/dist/esm/plugins.d.ts +129 -0
  51. package/dist/esm/plugins.d.ts.map +1 -0
  52. package/dist/esm/plugins.js +173 -0
  53. package/dist/esm/timezone.d.ts +52 -0
  54. package/dist/esm/timezone.d.ts.map +1 -1
  55. package/dist/esm/timezone.js +171 -0
  56. package/dist/esm/validate.d.ts +51 -0
  57. package/dist/esm/validate.d.ts.map +1 -1
  58. package/dist/esm/validate.js +92 -0
  59. package/dist/esm/workingHours.d.ts +70 -0
  60. package/dist/esm/workingHours.d.ts.map +1 -1
  61. package/dist/esm/workingHours.js +161 -0
  62. package/dist/fiscal.d.ts +195 -0
  63. package/dist/fiscal.d.ts.map +1 -0
  64. package/dist/fiscal.js +295 -0
  65. package/dist/format.d.ts +65 -0
  66. package/dist/format.d.ts.map +1 -1
  67. package/dist/format.js +202 -0
  68. package/dist/holidays.d.ts +62 -0
  69. package/dist/holidays.d.ts.map +1 -0
  70. package/dist/holidays.js +793 -0
  71. package/dist/index.d.ts +18 -6
  72. package/dist/index.d.ts.map +1 -1
  73. package/dist/index.js +20 -6
  74. package/dist/iterate.d.ts +212 -0
  75. package/dist/iterate.d.ts.map +1 -0
  76. package/dist/iterate.js +409 -0
  77. package/dist/parse.d.ts +45 -0
  78. package/dist/parse.d.ts.map +1 -1
  79. package/dist/parse.js +207 -0
  80. package/dist/plugins.d.ts +129 -0
  81. package/dist/plugins.d.ts.map +1 -0
  82. package/dist/plugins.js +173 -0
  83. package/dist/timezone.d.ts +52 -0
  84. package/dist/timezone.d.ts.map +1 -1
  85. package/dist/timezone.js +171 -0
  86. package/dist/validate.d.ts +51 -0
  87. package/dist/validate.d.ts.map +1 -1
  88. package/dist/validate.js +92 -0
  89. package/dist/workingHours.d.ts +70 -0
  90. package/dist/workingHours.d.ts.map +1 -1
  91. package/dist/workingHours.js +161 -0
  92. package/package.json +40 -1
package/dist/chain.js ADDED
@@ -0,0 +1,422 @@
1
+ /**
2
+ * Fluent chain API for ts-time-utils
3
+ *
4
+ * Provides a chainable interface for date operations:
5
+ * ```ts
6
+ * chain(new Date())
7
+ * .add(1, 'day')
8
+ * .startOf('month')
9
+ * .format('YYYY-MM-DD')
10
+ * ```
11
+ */
12
+ import { addTime, subtractTime, startOf, endOf, differenceInUnits, isBetween } from './calculate.js';
13
+ import { formatDate, formatDuration, timeAgo, formatTime, formatCalendarDate, formatOrdinal } from './format.js';
14
+ import { isValidDate, isToday, isYesterday, isTomorrow, isPast, isFuture, isWeekend, isWeekday, isSameDay, isSameWeek, isSameMonth, isSameYear, isThisWeek, isThisMonth, isThisYear, isBusinessDay, isLeapYear } from './validate.js';
15
+ /**
16
+ * Immutable chainable date wrapper
17
+ * All transformation methods return a new ChainedDate instance
18
+ */
19
+ export class ChainedDate {
20
+ constructor(date = new Date()) {
21
+ if (date instanceof Date) {
22
+ this._date = new Date(date.getTime());
23
+ }
24
+ else if (typeof date === 'number') {
25
+ this._date = new Date(date);
26
+ }
27
+ else {
28
+ this._date = new Date(date);
29
+ }
30
+ }
31
+ // ============ Transformations (return new ChainedDate) ============
32
+ /**
33
+ * Add time to the date
34
+ * @example chain(date).add(1, 'day').add(2, 'hours')
35
+ */
36
+ add(amount, unit) {
37
+ return new ChainedDate(addTime(this._date, amount, unit));
38
+ }
39
+ /**
40
+ * Subtract time from the date
41
+ * @example chain(date).subtract(1, 'week')
42
+ */
43
+ subtract(amount, unit) {
44
+ return new ChainedDate(subtractTime(this._date, amount, unit));
45
+ }
46
+ /**
47
+ * Get the start of a time period
48
+ * @example chain(date).startOf('month')
49
+ */
50
+ startOf(unit) {
51
+ return new ChainedDate(startOf(this._date, unit));
52
+ }
53
+ /**
54
+ * Get the end of a time period
55
+ * @example chain(date).endOf('day')
56
+ */
57
+ endOf(unit) {
58
+ return new ChainedDate(endOf(this._date, unit));
59
+ }
60
+ /**
61
+ * Set specific date/time components
62
+ * @example chain(date).set({ year: 2025, month: 1 })
63
+ */
64
+ set(values) {
65
+ const d = new Date(this._date.getTime());
66
+ if (values.year !== undefined)
67
+ d.setFullYear(values.year);
68
+ if (values.month !== undefined)
69
+ d.setMonth(values.month - 1); // 1-indexed input
70
+ if (values.day !== undefined)
71
+ d.setDate(values.day);
72
+ if (values.hours !== undefined)
73
+ d.setHours(values.hours);
74
+ if (values.minutes !== undefined)
75
+ d.setMinutes(values.minutes);
76
+ if (values.seconds !== undefined)
77
+ d.setSeconds(values.seconds);
78
+ if (values.milliseconds !== undefined)
79
+ d.setMilliseconds(values.milliseconds);
80
+ return new ChainedDate(d);
81
+ }
82
+ /**
83
+ * Clone the ChainedDate
84
+ */
85
+ clone() {
86
+ return new ChainedDate(this._date);
87
+ }
88
+ // ============ Formatters (return string) ============
89
+ /**
90
+ * Format date using pattern string
91
+ * @example chain(date).format('YYYY-MM-DD') // "2025-01-15"
92
+ */
93
+ format(pattern) {
94
+ return formatDate(this._date, pattern);
95
+ }
96
+ /**
97
+ * Format time in 12h, 24h, or ISO format
98
+ * @example chain(date).formatTime('12h') // "2:30 PM"
99
+ */
100
+ formatTime(fmt = '24h') {
101
+ return formatTime(this._date, fmt);
102
+ }
103
+ /**
104
+ * Format as calendar date (Today, Yesterday, Monday, etc.)
105
+ * @example chain(date).calendar() // "Tomorrow"
106
+ */
107
+ calendar() {
108
+ return formatCalendarDate(this._date);
109
+ }
110
+ /**
111
+ * Get relative time string
112
+ * @example chain(pastDate).ago() // "3 hours ago"
113
+ */
114
+ ago(options) {
115
+ return timeAgo(this._date, options);
116
+ }
117
+ /**
118
+ * Get ISO string
119
+ */
120
+ toISOString() {
121
+ return this._date.toISOString();
122
+ }
123
+ /**
124
+ * Get locale string
125
+ */
126
+ toLocaleString(locale, options) {
127
+ return this._date.toLocaleString(locale, options);
128
+ }
129
+ /**
130
+ * Format day as ordinal
131
+ * @example chain(date).dayOrdinal() // "15th"
132
+ */
133
+ dayOrdinal() {
134
+ return formatOrdinal(this._date.getDate());
135
+ }
136
+ // ============ Comparisons (return boolean) ============
137
+ /**
138
+ * Check if date is valid
139
+ */
140
+ isValid() {
141
+ return isValidDate(this._date);
142
+ }
143
+ /**
144
+ * Check if date is today
145
+ */
146
+ isToday() {
147
+ return isToday(this._date);
148
+ }
149
+ /**
150
+ * Check if date is yesterday
151
+ */
152
+ isYesterday() {
153
+ return isYesterday(this._date);
154
+ }
155
+ /**
156
+ * Check if date is tomorrow
157
+ */
158
+ isTomorrow() {
159
+ return isTomorrow(this._date);
160
+ }
161
+ /**
162
+ * Check if date is in the past
163
+ */
164
+ isPast() {
165
+ return isPast(this._date);
166
+ }
167
+ /**
168
+ * Check if date is in the future
169
+ */
170
+ isFuture() {
171
+ return isFuture(this._date);
172
+ }
173
+ /**
174
+ * Check if date is a weekend
175
+ */
176
+ isWeekend() {
177
+ return isWeekend(this._date);
178
+ }
179
+ /**
180
+ * Check if date is a weekday
181
+ */
182
+ isWeekday() {
183
+ return isWeekday(this._date);
184
+ }
185
+ /**
186
+ * Check if date is in this week
187
+ */
188
+ isThisWeek() {
189
+ return isThisWeek(this._date);
190
+ }
191
+ /**
192
+ * Check if date is in this month
193
+ */
194
+ isThisMonth() {
195
+ return isThisMonth(this._date);
196
+ }
197
+ /**
198
+ * Check if date is in this year
199
+ */
200
+ isThisYear() {
201
+ return isThisYear(this._date);
202
+ }
203
+ /**
204
+ * Check if year is a leap year
205
+ */
206
+ isLeapYear() {
207
+ return isLeapYear(this._date.getFullYear());
208
+ }
209
+ /**
210
+ * Check if date is a business day
211
+ */
212
+ isBusinessDay(holidays) {
213
+ return isBusinessDay(this._date, holidays);
214
+ }
215
+ /**
216
+ * Check if date is same day as another
217
+ */
218
+ isSameDay(other) {
219
+ return isSameDay(this._date, toDate(other));
220
+ }
221
+ /**
222
+ * Check if date is same week as another
223
+ */
224
+ isSameWeek(other) {
225
+ return isSameWeek(this._date, toDate(other));
226
+ }
227
+ /**
228
+ * Check if date is same month as another
229
+ */
230
+ isSameMonth(other) {
231
+ return isSameMonth(this._date, toDate(other));
232
+ }
233
+ /**
234
+ * Check if date is same year as another
235
+ */
236
+ isSameYear(other) {
237
+ return isSameYear(this._date, toDate(other));
238
+ }
239
+ /**
240
+ * Check if date is before another
241
+ */
242
+ isBefore(other) {
243
+ return this._date.getTime() < toDate(other).getTime();
244
+ }
245
+ /**
246
+ * Check if date is after another
247
+ */
248
+ isAfter(other) {
249
+ return this._date.getTime() > toDate(other).getTime();
250
+ }
251
+ /**
252
+ * Check if date is between two dates
253
+ */
254
+ isBetween(start, end, inclusive) {
255
+ return isBetween(this._date, toDate(start), toDate(end), inclusive);
256
+ }
257
+ // ============ Getters (return number) ============
258
+ /**
259
+ * Get difference from another date
260
+ * @example chain(date).diff(other, 'days') // 5
261
+ */
262
+ diff(other, unit = 'milliseconds', precise = true) {
263
+ return differenceInUnits(this._date, toDate(other), unit, precise);
264
+ }
265
+ /**
266
+ * Get the timestamp (milliseconds since epoch)
267
+ */
268
+ valueOf() {
269
+ return this._date.getTime();
270
+ }
271
+ /**
272
+ * Get year
273
+ */
274
+ year() {
275
+ return this._date.getFullYear();
276
+ }
277
+ /**
278
+ * Get month (1-12)
279
+ */
280
+ month() {
281
+ return this._date.getMonth() + 1;
282
+ }
283
+ /**
284
+ * Get day of month (1-31)
285
+ */
286
+ day() {
287
+ return this._date.getDate();
288
+ }
289
+ /**
290
+ * Get day of week (0-6, 0=Sunday)
291
+ */
292
+ weekday() {
293
+ return this._date.getDay();
294
+ }
295
+ /**
296
+ * Get hours (0-23)
297
+ */
298
+ hours() {
299
+ return this._date.getHours();
300
+ }
301
+ /**
302
+ * Get minutes (0-59)
303
+ */
304
+ minutes() {
305
+ return this._date.getMinutes();
306
+ }
307
+ /**
308
+ * Get seconds (0-59)
309
+ */
310
+ seconds() {
311
+ return this._date.getSeconds();
312
+ }
313
+ /**
314
+ * Get milliseconds (0-999)
315
+ */
316
+ milliseconds() {
317
+ return this._date.getMilliseconds();
318
+ }
319
+ /**
320
+ * Get day of year (1-366)
321
+ */
322
+ dayOfYear() {
323
+ const start = new Date(this._date.getFullYear(), 0, 0);
324
+ const diff = this._date.getTime() - start.getTime();
325
+ const oneDay = 1000 * 60 * 60 * 24;
326
+ return Math.floor(diff / oneDay);
327
+ }
328
+ /**
329
+ * Get ISO week number (1-53)
330
+ */
331
+ week() {
332
+ const d = new Date(Date.UTC(this._date.getFullYear(), this._date.getMonth(), this._date.getDate()));
333
+ const dayNum = d.getUTCDay() || 7;
334
+ d.setUTCDate(d.getUTCDate() + 4 - dayNum);
335
+ const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
336
+ return Math.ceil((((d.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
337
+ }
338
+ /**
339
+ * Get quarter (1-4)
340
+ */
341
+ quarter() {
342
+ return Math.floor(this._date.getMonth() / 3) + 1;
343
+ }
344
+ /**
345
+ * Get days in month
346
+ */
347
+ daysInMonth() {
348
+ return new Date(this._date.getFullYear(), this._date.getMonth() + 1, 0).getDate();
349
+ }
350
+ // ============ Conversion ============
351
+ /**
352
+ * Get the underlying Date object
353
+ */
354
+ toDate() {
355
+ return new Date(this._date.getTime());
356
+ }
357
+ /**
358
+ * Get Unix timestamp (seconds)
359
+ */
360
+ unix() {
361
+ return Math.floor(this._date.getTime() / 1000);
362
+ }
363
+ /**
364
+ * Convert to array [year, month, day, hours, minutes, seconds, ms]
365
+ */
366
+ toArray() {
367
+ return [
368
+ this._date.getFullYear(),
369
+ this._date.getMonth() + 1,
370
+ this._date.getDate(),
371
+ this._date.getHours(),
372
+ this._date.getMinutes(),
373
+ this._date.getSeconds(),
374
+ this._date.getMilliseconds()
375
+ ];
376
+ }
377
+ /**
378
+ * Convert to object
379
+ */
380
+ toObject() {
381
+ return {
382
+ year: this._date.getFullYear(),
383
+ month: this._date.getMonth() + 1,
384
+ day: this._date.getDate(),
385
+ hours: this._date.getHours(),
386
+ minutes: this._date.getMinutes(),
387
+ seconds: this._date.getSeconds(),
388
+ milliseconds: this._date.getMilliseconds()
389
+ };
390
+ }
391
+ }
392
+ /**
393
+ * Helper to convert DateInput to Date
394
+ */
395
+ function toDate(input) {
396
+ if (input instanceof Date)
397
+ return input;
398
+ return new Date(input);
399
+ }
400
+ /**
401
+ * Create a chainable date wrapper
402
+ * @example
403
+ * chain(new Date()).add(1, 'day').format('YYYY-MM-DD')
404
+ * chain('2025-01-15').startOf('month').toDate()
405
+ * chain().add(1, 'week').isWeekend()
406
+ */
407
+ export function chain(date) {
408
+ return new ChainedDate(date);
409
+ }
410
+ /**
411
+ * Format a duration in milliseconds
412
+ * Convenience export for use with chain().diff()
413
+ * @example formatMs(chain(a).diff(b)) // "2 days, 3 hours"
414
+ */
415
+ export function formatMs(ms, options) {
416
+ return formatDuration(ms, options);
417
+ }
418
+ // Initialize plugin system if it's available
419
+ // This allows plugins to extend ChainedDate
420
+ if (typeof globalThis !== 'undefined') {
421
+ globalThis.__chainedDateClass = ChainedDate;
422
+ }
@@ -0,0 +1,217 @@
1
+ /**
2
+ * @fileoverview Date comparison, sorting, and array manipulation utilities
3
+ */
4
+ /**
5
+ * Compare two dates for sorting
6
+ * @param a - First date
7
+ * @param b - Second date
8
+ * @returns Negative if a < b, positive if a > b, 0 if equal
9
+ * @example
10
+ * [date3, date1, date2].sort(compareDates) // [date1, date2, date3]
11
+ */
12
+ export declare function compareDates(a: Date, b: Date): number;
13
+ /**
14
+ * Compare two dates in reverse order for sorting
15
+ * @param a - First date
16
+ * @param b - Second date
17
+ * @returns Positive if a < b, negative if a > b, 0 if equal
18
+ * @example
19
+ * [date1, date3, date2].sort(compareDatesDesc) // [date3, date2, date1]
20
+ */
21
+ export declare function compareDatesDesc(a: Date, b: Date): number;
22
+ /**
23
+ * Sort an array of dates
24
+ * @param dates - Array of dates to sort
25
+ * @param direction - Sort direction: 'asc' (oldest first) or 'desc' (newest first)
26
+ * @returns New sorted array (does not mutate original)
27
+ * @example
28
+ * sortDates([date3, date1, date2]) // [date1, date2, date3]
29
+ * sortDates([date1, date2, date3], 'desc') // [date3, date2, date1]
30
+ */
31
+ export declare function sortDates(dates: Date[], direction?: 'asc' | 'desc'): Date[];
32
+ /**
33
+ * Find the minimum (earliest) date in an array
34
+ * @param dates - Array of dates
35
+ * @returns The earliest date, or undefined if array is empty
36
+ * @example
37
+ * minDate([date2, date1, date3]) // date1
38
+ */
39
+ export declare function minDate(dates: Date[]): Date | undefined;
40
+ /**
41
+ * Find the maximum (latest) date in an array
42
+ * @param dates - Array of dates
43
+ * @returns The latest date, or undefined if array is empty
44
+ * @example
45
+ * maxDate([date1, date3, date2]) // date3
46
+ */
47
+ export declare function maxDate(dates: Date[]): Date | undefined;
48
+ /**
49
+ * Find the date range (min and max) in an array
50
+ * @param dates - Array of dates
51
+ * @returns Object with min and max dates, or undefined if array is empty
52
+ * @example
53
+ * dateRange([date2, date1, date3]) // { min: date1, max: date3 }
54
+ */
55
+ export declare function dateExtent(dates: Date[]): {
56
+ min: Date;
57
+ max: Date;
58
+ } | undefined;
59
+ /**
60
+ * Remove duplicate dates from an array
61
+ * @param dates - Array of dates
62
+ * @param precision - Precision for comparison: 'ms' (exact), 'second', 'minute', 'hour', 'day'
63
+ * @returns New array with duplicates removed (preserves first occurrence)
64
+ * @example
65
+ * uniqueDates([date1, date1Copy, date2]) // [date1, date2]
66
+ */
67
+ export declare function uniqueDates(dates: Date[], precision?: 'ms' | 'second' | 'minute' | 'hour' | 'day'): Date[];
68
+ /**
69
+ * Find the closest date to a target from an array of candidates
70
+ * @param target - The target date
71
+ * @param candidates - Array of candidate dates
72
+ * @returns The closest date, or undefined if candidates is empty
73
+ * @example
74
+ * closestDate(targetDate, [date1, date2, date3]) // closest to target
75
+ */
76
+ export declare function closestDate(target: Date, candidates: Date[]): Date | undefined;
77
+ /**
78
+ * Find the closest future date to a target
79
+ * @param target - The target date
80
+ * @param candidates - Array of candidate dates
81
+ * @returns The closest future date, or undefined if none found
82
+ */
83
+ export declare function closestFutureDate(target: Date, candidates: Date[]): Date | undefined;
84
+ /**
85
+ * Find the closest past date to a target
86
+ * @param target - The target date
87
+ * @param candidates - Array of candidate dates
88
+ * @returns The closest past date, or undefined if none found
89
+ */
90
+ export declare function closestPastDate(target: Date, candidates: Date[]): Date | undefined;
91
+ /**
92
+ * Clamp a date to be within a range
93
+ * @param date - The date to clamp
94
+ * @param min - Minimum allowed date
95
+ * @param max - Maximum allowed date
96
+ * @returns The clamped date
97
+ * @example
98
+ * clampDate(earlyDate, minDate, maxDate) // returns minDate
99
+ * clampDate(lateDate, minDate, maxDate) // returns maxDate
100
+ * clampDate(middleDate, minDate, maxDate) // returns middleDate
101
+ */
102
+ export declare function clampDate(date: Date, min: Date, max: Date): Date;
103
+ /**
104
+ * Check if a date is within a range (inclusive)
105
+ * @param date - The date to check
106
+ * @param min - Start of range
107
+ * @param max - End of range
108
+ * @returns True if date is within range
109
+ */
110
+ export declare function isDateInRange(date: Date, min: Date, max: Date): boolean;
111
+ /**
112
+ * Filter dates to only those within a range
113
+ * @param dates - Array of dates
114
+ * @param min - Start of range
115
+ * @param max - End of range
116
+ * @returns New array with only dates in range
117
+ */
118
+ export declare function filterDatesInRange(dates: Date[], min: Date, max: Date): Date[];
119
+ /**
120
+ * Group dates by a key function
121
+ * @param dates - Array of dates
122
+ * @param keyFn - Function to generate group key from date
123
+ * @returns Map of key to array of dates
124
+ * @example
125
+ * groupDates(dates, d => d.getFullYear()) // Map { 2023 => [...], 2024 => [...] }
126
+ * groupDates(dates, d => d.toISOString().slice(0, 7)) // Group by month
127
+ */
128
+ export declare function groupDates<K>(dates: Date[], keyFn: (date: Date) => K): Map<K, Date[]>;
129
+ /**
130
+ * Group dates by year
131
+ * @param dates - Array of dates
132
+ * @returns Map of year to array of dates
133
+ */
134
+ export declare function groupDatesByYear(dates: Date[]): Map<number, Date[]>;
135
+ /**
136
+ * Group dates by month (YYYY-MM format)
137
+ * @param dates - Array of dates
138
+ * @returns Map of month key to array of dates
139
+ */
140
+ export declare function groupDatesByMonth(dates: Date[]): Map<string, Date[]>;
141
+ /**
142
+ * Group dates by day (YYYY-MM-DD format)
143
+ * @param dates - Array of dates
144
+ * @returns Map of day key to array of dates
145
+ */
146
+ export declare function groupDatesByDay(dates: Date[]): Map<string, Date[]>;
147
+ /**
148
+ * Group dates by day of week (0-6, Sunday-Saturday)
149
+ * @param dates - Array of dates
150
+ * @returns Map of day of week to array of dates
151
+ */
152
+ export declare function groupDatesByDayOfWeek(dates: Date[]): Map<number, Date[]>;
153
+ /**
154
+ * Calculate the median date from an array
155
+ * @param dates - Array of dates
156
+ * @returns The median date, or undefined if array is empty
157
+ */
158
+ export declare function medianDate(dates: Date[]): Date | undefined;
159
+ /**
160
+ * Calculate the average/mean date from an array
161
+ * @param dates - Array of dates
162
+ * @returns The average date, or undefined if array is empty
163
+ */
164
+ export declare function averageDate(dates: Date[]): Date | undefined;
165
+ /**
166
+ * Round a date to the nearest unit
167
+ * @param date - The date to round
168
+ * @param unit - Unit to round to
169
+ * @returns New rounded date
170
+ * @example
171
+ * roundDate(new Date('2024-03-15T14:37:00'), 'hour') // 2024-03-15T15:00:00
172
+ * roundDate(new Date('2024-03-15T14:22:00'), 'hour') // 2024-03-15T14:00:00
173
+ */
174
+ export declare function roundDate(date: Date, unit: 'minute' | 'hour' | 'day'): Date;
175
+ /**
176
+ * Snap a date to a grid interval
177
+ * @param date - The date to snap
178
+ * @param intervalMinutes - Interval in minutes (e.g., 15 for quarter-hour)
179
+ * @param mode - Snap mode: 'floor' (down), 'ceil' (up), or 'round' (nearest)
180
+ * @returns New snapped date
181
+ * @example
182
+ * snapDate(new Date('2024-03-15T14:37:00'), 15) // 2024-03-15T14:30:00
183
+ * snapDate(new Date('2024-03-15T14:37:00'), 15, 'ceil') // 2024-03-15T14:45:00
184
+ */
185
+ export declare function snapDate(date: Date, intervalMinutes: number, mode?: 'floor' | 'ceil' | 'round'): Date;
186
+ /**
187
+ * Check if dates are in chronological order
188
+ * @param dates - Array of dates
189
+ * @param strict - If true, requires strictly increasing (no duplicates)
190
+ * @returns True if dates are in order
191
+ */
192
+ export declare function isChronological(dates: Date[], strict?: boolean): boolean;
193
+ /**
194
+ * Get the span (duration) between min and max dates
195
+ * @param dates - Array of dates
196
+ * @returns Duration in milliseconds, or 0 if less than 2 dates
197
+ */
198
+ export declare function dateSpan(dates: Date[]): number;
199
+ /**
200
+ * Partition dates into buckets based on a predicate
201
+ * @param dates - Array of dates
202
+ * @param predicate - Function that returns true for dates in first partition
203
+ * @returns Tuple of [matching, non-matching] date arrays
204
+ */
205
+ export declare function partitionDates(dates: Date[], predicate: (date: Date) => boolean): [Date[], Date[]];
206
+ /**
207
+ * Get the nth date from an array (supports negative indices)
208
+ * @param dates - Array of dates (will be sorted)
209
+ * @param n - Index (0-based, negative counts from end)
210
+ * @returns The nth date, or undefined if out of bounds
211
+ * @example
212
+ * nthDate(dates, 0) // earliest
213
+ * nthDate(dates, -1) // latest
214
+ * nthDate(dates, 2) // third earliest
215
+ */
216
+ export declare function nthDate(dates: Date[], n: number): Date | undefined;
217
+ //# sourceMappingURL=compare.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"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"}