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.
- package/README.md +567 -12
- package/dist/calculate.d.ts +7 -2
- package/dist/calculate.d.ts.map +1 -1
- package/dist/calculate.js +13 -3
- package/dist/calendar.d.ts +103 -0
- package/dist/calendar.d.ts.map +1 -1
- package/dist/calendar.js +224 -0
- package/dist/chain.d.ts +269 -0
- package/dist/chain.d.ts.map +1 -0
- package/dist/chain.js +422 -0
- package/dist/compare.d.ts +217 -0
- package/dist/compare.d.ts.map +1 -0
- package/dist/compare.js +417 -0
- package/dist/cron.d.ts +82 -0
- package/dist/cron.d.ts.map +1 -0
- package/dist/cron.js +294 -0
- package/dist/esm/calculate.d.ts +7 -2
- package/dist/esm/calculate.d.ts.map +1 -1
- package/dist/esm/calculate.js +13 -3
- package/dist/esm/calendar.d.ts +103 -0
- package/dist/esm/calendar.d.ts.map +1 -1
- package/dist/esm/calendar.js +224 -0
- package/dist/esm/chain.d.ts +269 -0
- package/dist/esm/chain.d.ts.map +1 -0
- package/dist/esm/chain.js +422 -0
- package/dist/esm/compare.d.ts +217 -0
- package/dist/esm/compare.d.ts.map +1 -0
- package/dist/esm/compare.js +417 -0
- package/dist/esm/cron.d.ts +82 -0
- package/dist/esm/cron.d.ts.map +1 -0
- package/dist/esm/cron.js +294 -0
- package/dist/esm/fiscal.d.ts +195 -0
- package/dist/esm/fiscal.d.ts.map +1 -0
- package/dist/esm/fiscal.js +295 -0
- package/dist/esm/format.d.ts +65 -0
- package/dist/esm/format.d.ts.map +1 -1
- package/dist/esm/format.js +202 -0
- package/dist/esm/holidays.d.ts +62 -0
- package/dist/esm/holidays.d.ts.map +1 -0
- package/dist/esm/holidays.js +793 -0
- package/dist/esm/index.d.ts +18 -6
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +20 -6
- package/dist/esm/iterate.d.ts +212 -0
- package/dist/esm/iterate.d.ts.map +1 -0
- package/dist/esm/iterate.js +409 -0
- package/dist/esm/parse.d.ts +45 -0
- package/dist/esm/parse.d.ts.map +1 -1
- package/dist/esm/parse.js +207 -0
- package/dist/esm/plugins.d.ts +129 -0
- package/dist/esm/plugins.d.ts.map +1 -0
- package/dist/esm/plugins.js +173 -0
- package/dist/esm/timezone.d.ts +52 -0
- package/dist/esm/timezone.d.ts.map +1 -1
- package/dist/esm/timezone.js +171 -0
- package/dist/esm/validate.d.ts +51 -0
- package/dist/esm/validate.d.ts.map +1 -1
- package/dist/esm/validate.js +92 -0
- package/dist/esm/workingHours.d.ts +70 -0
- package/dist/esm/workingHours.d.ts.map +1 -1
- package/dist/esm/workingHours.js +161 -0
- package/dist/fiscal.d.ts +195 -0
- package/dist/fiscal.d.ts.map +1 -0
- package/dist/fiscal.js +295 -0
- package/dist/format.d.ts +65 -0
- package/dist/format.d.ts.map +1 -1
- package/dist/format.js +202 -0
- package/dist/holidays.d.ts +62 -0
- package/dist/holidays.d.ts.map +1 -0
- package/dist/holidays.js +793 -0
- package/dist/index.d.ts +18 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +20 -6
- package/dist/iterate.d.ts +212 -0
- package/dist/iterate.d.ts.map +1 -0
- package/dist/iterate.js +409 -0
- package/dist/parse.d.ts +45 -0
- package/dist/parse.d.ts.map +1 -1
- package/dist/parse.js +207 -0
- package/dist/plugins.d.ts +129 -0
- package/dist/plugins.d.ts.map +1 -0
- package/dist/plugins.js +173 -0
- package/dist/timezone.d.ts +52 -0
- package/dist/timezone.d.ts.map +1 -1
- package/dist/timezone.js +171 -0
- package/dist/validate.d.ts +51 -0
- package/dist/validate.d.ts.map +1 -1
- package/dist/validate.js +92 -0
- package/dist/workingHours.d.ts +70 -0
- package/dist/workingHours.d.ts.map +1 -1
- package/dist/workingHours.js +161 -0
- 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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"}
|