ts-time-utils 1.0.0 → 1.1.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 +226 -1
- package/dist/calculate.d.ts.map +1 -1
- package/dist/calculate.js +24 -10
- package/dist/countdown.d.ts +217 -0
- package/dist/countdown.d.ts.map +1 -0
- package/dist/countdown.js +298 -0
- package/dist/dateRange.d.ts +266 -0
- package/dist/dateRange.d.ts.map +1 -0
- package/dist/dateRange.js +433 -0
- package/dist/esm/calculate.d.ts.map +1 -1
- package/dist/esm/calculate.js +24 -10
- package/dist/esm/countdown.d.ts +217 -0
- package/dist/esm/countdown.d.ts.map +1 -0
- package/dist/esm/countdown.js +298 -0
- package/dist/esm/dateRange.d.ts +266 -0
- package/dist/esm/dateRange.d.ts.map +1 -0
- package/dist/esm/dateRange.js +433 -0
- package/dist/esm/index.d.ts +5 -1
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +8 -0
- package/dist/esm/naturalLanguage.d.ts +107 -0
- package/dist/esm/naturalLanguage.d.ts.map +1 -0
- package/dist/esm/naturalLanguage.js +344 -0
- package/dist/esm/recurrence.d.ts +149 -0
- package/dist/esm/recurrence.d.ts.map +1 -0
- package/dist/esm/recurrence.js +404 -0
- package/dist/esm/types.d.ts +21 -0
- package/dist/esm/types.d.ts.map +1 -1
- package/dist/index.d.ts +5 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -0
- package/dist/naturalLanguage.d.ts +107 -0
- package/dist/naturalLanguage.d.ts.map +1 -0
- package/dist/naturalLanguage.js +344 -0
- package/dist/recurrence.d.ts +149 -0
- package/dist/recurrence.d.ts.map +1 -0
- package/dist/recurrence.js +404 -0
- package/dist/types.d.ts +21 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +30 -2
package/README.md
CHANGED
|
@@ -8,7 +8,43 @@ A lightweight TypeScript utility library for time formatting, calculations, and
|
|
|
8
8
|
- **⚡ Fast** - Zero dependencies, pure JavaScript functions
|
|
9
9
|
- **🔧 TypeScript** - Full type safety and IntelliSense support
|
|
10
10
|
- **🌳 Tree-shakable** - Import individual functions to minimize bundle size
|
|
11
|
-
- **📚 Comprehensive** -
|
|
11
|
+
- **📚 Comprehensive** - 19 utility categories with 150+ functions
|
|
12
|
+
|
|
13
|
+
### 🔄 Recurrence utilities **(NEW!)**
|
|
14
|
+
|
|
15
|
+
- RRULE-inspired recurring event patterns
|
|
16
|
+
- Daily, weekly, monthly, and yearly recurrences
|
|
17
|
+
- Complex recurrence rules with byWeekday, byMonthDay, byMonth
|
|
18
|
+
- Get next occurrence, all occurrences, or occurrences within range
|
|
19
|
+
- Human-readable recurrence descriptions
|
|
20
|
+
- Full support for count and until limits
|
|
21
|
+
|
|
22
|
+
### ⏲️ Countdown & Timer utilities **(NEW!)**
|
|
23
|
+
|
|
24
|
+
- Real-time countdown timers with callbacks
|
|
25
|
+
- Get remaining time broken down by units
|
|
26
|
+
- Format countdowns as human-readable strings
|
|
27
|
+
- Check if dates are expired
|
|
28
|
+
- Calculate progress percentage between dates
|
|
29
|
+
- Deadline tracking with helper methods
|
|
30
|
+
|
|
31
|
+
### 📊 Date Range utilities **(NEW!)**
|
|
32
|
+
|
|
33
|
+
- Advanced range operations (overlap, intersection, union)
|
|
34
|
+
- Merge overlapping ranges
|
|
35
|
+
- Find gaps between ranges
|
|
36
|
+
- Split ranges into chunks
|
|
37
|
+
- Expand and shrink ranges
|
|
38
|
+
- Subtract ranges from each other
|
|
39
|
+
- Check containment and sort ranges
|
|
40
|
+
|
|
41
|
+
### 💬 Natural Language Parsing **(NEW!)**
|
|
42
|
+
|
|
43
|
+
- Parse human-friendly date strings ("tomorrow", "next Friday", "in 2 weeks")
|
|
44
|
+
- Extract dates from text automatically
|
|
45
|
+
- Context-aware date suggestions ("end of month", "EOY")
|
|
46
|
+
- Support for relative phrases and absolute dates
|
|
47
|
+
- Confidence scoring for extracted dates
|
|
12
48
|
|
|
13
49
|
### ⏱️ Duration utilities
|
|
14
50
|
|
|
@@ -157,10 +193,199 @@ import {
|
|
|
157
193
|
formatDateLocale,
|
|
158
194
|
detectLocale,
|
|
159
195
|
} from "ts-time-utils/locale";
|
|
196
|
+
// New modules!
|
|
197
|
+
import { createRecurrence, getNextOccurrence } from "ts-time-utils/recurrence";
|
|
198
|
+
import { createCountdown, getRemainingTime } from "ts-time-utils/countdown";
|
|
199
|
+
import { mergeDateRanges, findGaps } from "ts-time-utils/dateRange";
|
|
200
|
+
import {
|
|
201
|
+
parseNaturalDate,
|
|
202
|
+
extractDatesFromText,
|
|
203
|
+
} from "ts-time-utils/naturalLanguage";
|
|
160
204
|
```
|
|
161
205
|
|
|
162
206
|
## 📖 Examples
|
|
163
207
|
|
|
208
|
+
### Recurrence Utilities (NEW!)
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
import { createRecurrence, recurrenceToString } from "ts-time-utils/recurrence";
|
|
212
|
+
|
|
213
|
+
// Daily recurrence
|
|
214
|
+
const daily = createRecurrence({
|
|
215
|
+
frequency: "daily",
|
|
216
|
+
interval: 2,
|
|
217
|
+
startDate: new Date("2024-01-01"),
|
|
218
|
+
count: 10,
|
|
219
|
+
});
|
|
220
|
+
|
|
221
|
+
const next = daily.getNextOccurrence(new Date());
|
|
222
|
+
const allOccurrences = daily.getAllOccurrences();
|
|
223
|
+
|
|
224
|
+
// Weekly on specific days
|
|
225
|
+
const weekly = createRecurrence({
|
|
226
|
+
frequency: "weekly",
|
|
227
|
+
interval: 1,
|
|
228
|
+
startDate: new Date("2024-01-01"),
|
|
229
|
+
byWeekday: [1, 3, 5], // Monday, Wednesday, Friday
|
|
230
|
+
});
|
|
231
|
+
|
|
232
|
+
const description = recurrenceToString(weekly.rule);
|
|
233
|
+
// "Every week on Monday, Wednesday, Friday"
|
|
234
|
+
|
|
235
|
+
// Monthly on the 15th
|
|
236
|
+
const monthly = createRecurrence({
|
|
237
|
+
frequency: "monthly",
|
|
238
|
+
interval: 1,
|
|
239
|
+
startDate: new Date("2024-01-01"),
|
|
240
|
+
byMonthDay: [15],
|
|
241
|
+
until: new Date("2024-12-31"),
|
|
242
|
+
});
|
|
243
|
+
|
|
244
|
+
const occurrencesInRange = monthly.getOccurrencesBetween(
|
|
245
|
+
new Date("2024-03-01"),
|
|
246
|
+
new Date("2024-06-30")
|
|
247
|
+
);
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### Countdown & Timer Utilities (NEW!)
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
import {
|
|
254
|
+
createCountdown,
|
|
255
|
+
getRemainingTime,
|
|
256
|
+
formatCountdown,
|
|
257
|
+
} from "ts-time-utils/countdown";
|
|
258
|
+
|
|
259
|
+
// Create a countdown timer
|
|
260
|
+
const countdown = createCountdown(new Date("2024-12-31T23:59:59"), {
|
|
261
|
+
onTick: (remaining) => {
|
|
262
|
+
console.log(`${remaining.days}d ${remaining.hours}h ${remaining.minutes}m`);
|
|
263
|
+
},
|
|
264
|
+
onComplete: () => {
|
|
265
|
+
console.log("Happy New Year!");
|
|
266
|
+
},
|
|
267
|
+
interval: 1000, // Update every second
|
|
268
|
+
});
|
|
269
|
+
|
|
270
|
+
countdown.start();
|
|
271
|
+
// Later...
|
|
272
|
+
countdown.stop();
|
|
273
|
+
|
|
274
|
+
// Get remaining time
|
|
275
|
+
const remaining = getRemainingTime(new Date("2024-12-31"));
|
|
276
|
+
console.log(`${remaining.days} days, ${remaining.hours} hours remaining`);
|
|
277
|
+
|
|
278
|
+
// Format countdown
|
|
279
|
+
const formatted = formatCountdown(new Date("2024-12-31"), {
|
|
280
|
+
units: ["days", "hours", "minutes"],
|
|
281
|
+
short: true,
|
|
282
|
+
});
|
|
283
|
+
// "45d 12h 30m"
|
|
284
|
+
|
|
285
|
+
// Progress tracking
|
|
286
|
+
import { getProgressPercentage } from "ts-time-utils/countdown";
|
|
287
|
+
|
|
288
|
+
const progress = getProgressPercentage(
|
|
289
|
+
new Date("2024-01-01"),
|
|
290
|
+
new Date("2024-12-31"),
|
|
291
|
+
new Date("2024-07-01")
|
|
292
|
+
);
|
|
293
|
+
console.log(`${progress}% complete`); // ~50%
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
### Date Range Utilities (NEW!)
|
|
297
|
+
|
|
298
|
+
```ts
|
|
299
|
+
import {
|
|
300
|
+
mergeDateRanges,
|
|
301
|
+
findGaps,
|
|
302
|
+
dateRangeOverlap,
|
|
303
|
+
splitRange,
|
|
304
|
+
} from "ts-time-utils/dateRange";
|
|
305
|
+
|
|
306
|
+
// Merge overlapping ranges
|
|
307
|
+
const ranges = [
|
|
308
|
+
{ start: new Date("2024-01-01"), end: new Date("2024-01-10") },
|
|
309
|
+
{ start: new Date("2024-01-05"), end: new Date("2024-01-15") },
|
|
310
|
+
{ start: new Date("2024-01-20"), end: new Date("2024-01-25") },
|
|
311
|
+
];
|
|
312
|
+
|
|
313
|
+
const merged = mergeDateRanges(ranges);
|
|
314
|
+
// [
|
|
315
|
+
// { start: Date('2024-01-01'), end: Date('2024-01-15') },
|
|
316
|
+
// { start: Date('2024-01-20'), end: Date('2024-01-25') }
|
|
317
|
+
// ]
|
|
318
|
+
|
|
319
|
+
// Find gaps between busy times
|
|
320
|
+
const busyTimes = [
|
|
321
|
+
{ start: new Date("2024-01-01T09:00"), end: new Date("2024-01-01T11:00") },
|
|
322
|
+
{ start: new Date("2024-01-01T14:00"), end: new Date("2024-01-01T16:00") },
|
|
323
|
+
];
|
|
324
|
+
|
|
325
|
+
const gaps = findGaps(busyTimes, {
|
|
326
|
+
start: new Date("2024-01-01T08:00"),
|
|
327
|
+
end: new Date("2024-01-01T18:00"),
|
|
328
|
+
});
|
|
329
|
+
// Returns available time slots
|
|
330
|
+
|
|
331
|
+
// Split into chunks
|
|
332
|
+
const range = {
|
|
333
|
+
start: new Date("2024-01-01"),
|
|
334
|
+
end: new Date("2024-01-31"),
|
|
335
|
+
};
|
|
336
|
+
|
|
337
|
+
const weeks = splitRange(range, 1, "week");
|
|
338
|
+
// Splits January into weekly chunks
|
|
339
|
+
|
|
340
|
+
// Check overlap
|
|
341
|
+
const overlap = dateRangeOverlap(
|
|
342
|
+
{ start: new Date("2024-01-01"), end: new Date("2024-01-15") },
|
|
343
|
+
{ start: new Date("2024-01-10"), end: new Date("2024-01-20") }
|
|
344
|
+
); // true
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
### Natural Language Parsing (NEW!)
|
|
348
|
+
|
|
349
|
+
```ts
|
|
350
|
+
import {
|
|
351
|
+
parseNaturalDate,
|
|
352
|
+
extractDatesFromText,
|
|
353
|
+
suggestDateFromContext,
|
|
354
|
+
} from "ts-time-utils/naturalLanguage";
|
|
355
|
+
|
|
356
|
+
// Parse natural language dates
|
|
357
|
+
parseNaturalDate("tomorrow at 3pm");
|
|
358
|
+
// Returns Date for tomorrow at 15:00
|
|
359
|
+
|
|
360
|
+
parseNaturalDate("next Friday");
|
|
361
|
+
// Returns Date for next Friday
|
|
362
|
+
|
|
363
|
+
parseNaturalDate("in 2 weeks");
|
|
364
|
+
// Returns Date 2 weeks from now
|
|
365
|
+
|
|
366
|
+
parseNaturalDate("3 days ago");
|
|
367
|
+
// Returns Date 3 days ago
|
|
368
|
+
|
|
369
|
+
// Extract dates from text
|
|
370
|
+
const text = "Meeting tomorrow at 3pm and lunch next Friday at noon";
|
|
371
|
+
const dates = extractDatesFromText(text);
|
|
372
|
+
// [
|
|
373
|
+
// { date: Date(...), text: 'tomorrow at 3pm', index: 8, confidence: 0.9 },
|
|
374
|
+
// { date: Date(...), text: 'next Friday at noon', index: 35, confidence: 0.85 }
|
|
375
|
+
// ]
|
|
376
|
+
|
|
377
|
+
// Context-aware suggestions
|
|
378
|
+
const suggestions = suggestDateFromContext("deadline is end of month");
|
|
379
|
+
// [{ date: Date(last day of current month), text: 'end of month', confidence: 0.85 }]
|
|
380
|
+
|
|
381
|
+
// Supported phrases:
|
|
382
|
+
// - "tomorrow", "yesterday", "today"
|
|
383
|
+
// - "next Monday", "last Friday"
|
|
384
|
+
// - "in 2 hours", "5 days ago"
|
|
385
|
+
// - "end of month/week/year" (or EOM/EOW/EOY)
|
|
386
|
+
// - "beginning of month/year"
|
|
387
|
+
```
|
|
388
|
+
|
|
164
389
|
### Duration Utilities
|
|
165
390
|
|
|
166
391
|
```ts
|
package/dist/calculate.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"calculate.d.ts","sourceRoot":"","sources":["../src/calculate.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,QAAQ,EACT,MAAM,gBAAgB,CAAC;AAExB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,IAAI,EACX,KAAK,EAAE,IAAI,EACX,IAAI,GAAE,QAAyB,EAC/B,OAAO,GAAE,OAAc,GACtB,MAAM,CAkCR;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,
|
|
1
|
+
{"version":3,"file":"calculate.d.ts","sourceRoot":"","sources":["../src/calculate.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,QAAQ,EACT,MAAM,gBAAgB,CAAC;AAExB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,IAAI,EACX,KAAK,EAAE,IAAI,EACX,IAAI,GAAE,QAAyB,EAC/B,OAAO,GAAE,OAAc,GACtB,MAAM,CAkCR;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAgDxE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CA4BrG;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CA4BnG;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGrE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,CAa1E"}
|
package/dist/calculate.js
CHANGED
|
@@ -46,35 +46,49 @@ export function differenceInUnits(date1, date2, unit = 'milliseconds', precise =
|
|
|
46
46
|
*/
|
|
47
47
|
export function addTime(date, amount, unit) {
|
|
48
48
|
const result = new Date(date);
|
|
49
|
-
let milliseconds;
|
|
50
49
|
switch (unit) {
|
|
50
|
+
case 'year':
|
|
51
51
|
case 'years':
|
|
52
|
-
|
|
52
|
+
case 'y':
|
|
53
|
+
result.setFullYear(result.getFullYear() + amount);
|
|
53
54
|
break;
|
|
55
|
+
case 'month':
|
|
54
56
|
case 'months':
|
|
55
|
-
|
|
57
|
+
case 'M':
|
|
58
|
+
result.setMonth(result.getMonth() + amount);
|
|
56
59
|
break;
|
|
60
|
+
case 'week':
|
|
57
61
|
case 'weeks':
|
|
58
|
-
|
|
62
|
+
case 'w':
|
|
63
|
+
result.setDate(result.getDate() + (amount * 7));
|
|
59
64
|
break;
|
|
65
|
+
case 'day':
|
|
60
66
|
case 'days':
|
|
61
|
-
|
|
67
|
+
case 'd':
|
|
68
|
+
result.setDate(result.getDate() + amount);
|
|
62
69
|
break;
|
|
70
|
+
case 'hour':
|
|
63
71
|
case 'hours':
|
|
64
|
-
|
|
72
|
+
case 'h':
|
|
73
|
+
result.setHours(result.getHours() + amount);
|
|
65
74
|
break;
|
|
75
|
+
case 'minute':
|
|
66
76
|
case 'minutes':
|
|
67
|
-
|
|
77
|
+
case 'm':
|
|
78
|
+
result.setMinutes(result.getMinutes() + amount);
|
|
68
79
|
break;
|
|
80
|
+
case 'second':
|
|
69
81
|
case 'seconds':
|
|
70
|
-
|
|
82
|
+
case 's':
|
|
83
|
+
result.setSeconds(result.getSeconds() + amount);
|
|
71
84
|
break;
|
|
85
|
+
case 'millisecond':
|
|
72
86
|
case 'milliseconds':
|
|
87
|
+
case 'ms':
|
|
73
88
|
default:
|
|
74
|
-
|
|
89
|
+
result.setMilliseconds(result.getMilliseconds() + amount);
|
|
75
90
|
break;
|
|
76
91
|
}
|
|
77
|
-
result.setTime(result.getTime() + milliseconds);
|
|
78
92
|
return result;
|
|
79
93
|
}
|
|
80
94
|
/**
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Countdown and timer utilities for tracking time until/since a target date
|
|
3
|
+
* Provides countdown timers, remaining time calculations, and progress tracking
|
|
4
|
+
*/
|
|
5
|
+
import type { DateInput } from './types.js';
|
|
6
|
+
/**
|
|
7
|
+
* Represents the remaining time broken down by units
|
|
8
|
+
*/
|
|
9
|
+
export interface RemainingTime {
|
|
10
|
+
/** Total milliseconds remaining */
|
|
11
|
+
totalMilliseconds: number;
|
|
12
|
+
/** Total seconds remaining */
|
|
13
|
+
totalSeconds: number;
|
|
14
|
+
/** Total minutes remaining */
|
|
15
|
+
totalMinutes: number;
|
|
16
|
+
/** Total hours remaining */
|
|
17
|
+
totalHours: number;
|
|
18
|
+
/** Total days remaining */
|
|
19
|
+
totalDays: number;
|
|
20
|
+
/** Milliseconds component (0-999) */
|
|
21
|
+
milliseconds: number;
|
|
22
|
+
/** Seconds component (0-59) */
|
|
23
|
+
seconds: number;
|
|
24
|
+
/** Minutes component (0-59) */
|
|
25
|
+
minutes: number;
|
|
26
|
+
/** Hours component (0-23) */
|
|
27
|
+
hours: number;
|
|
28
|
+
/** Days component */
|
|
29
|
+
days: number;
|
|
30
|
+
/** Weeks component */
|
|
31
|
+
weeks: number;
|
|
32
|
+
/** Whether the target date has passed */
|
|
33
|
+
isExpired: boolean;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Options for countdown creation
|
|
37
|
+
*/
|
|
38
|
+
export interface CountdownOptions {
|
|
39
|
+
/** Callback fired on each tick */
|
|
40
|
+
onTick?: (remaining: RemainingTime) => void;
|
|
41
|
+
/** Callback fired when countdown reaches zero */
|
|
42
|
+
onComplete?: () => void;
|
|
43
|
+
/** Callback fired if target date is in the past */
|
|
44
|
+
onExpired?: () => void;
|
|
45
|
+
/** Tick interval in milliseconds (default: 1000) */
|
|
46
|
+
interval?: number;
|
|
47
|
+
/** Whether to fire onTick immediately (default: true) */
|
|
48
|
+
immediate?: boolean;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Countdown timer instance
|
|
52
|
+
*/
|
|
53
|
+
export interface Countdown {
|
|
54
|
+
/** Start the countdown */
|
|
55
|
+
start: () => void;
|
|
56
|
+
/** Stop the countdown */
|
|
57
|
+
stop: () => void;
|
|
58
|
+
/** Reset countdown with a new target date */
|
|
59
|
+
reset: (targetDate: DateInput) => void;
|
|
60
|
+
/** Get current remaining time */
|
|
61
|
+
getRemaining: () => RemainingTime;
|
|
62
|
+
/** Check if countdown is running */
|
|
63
|
+
isRunning: () => boolean;
|
|
64
|
+
/** Check if target date has passed */
|
|
65
|
+
isExpired: () => boolean;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Creates a countdown timer to a target date
|
|
69
|
+
* @param targetDate - The date to count down to
|
|
70
|
+
* @param options - Countdown options and callbacks
|
|
71
|
+
* @returns A countdown instance with control methods
|
|
72
|
+
*
|
|
73
|
+
* @example
|
|
74
|
+
* ```ts
|
|
75
|
+
* const countdown = createCountdown(
|
|
76
|
+
* new Date('2024-12-31T23:59:59'),
|
|
77
|
+
* {
|
|
78
|
+
* onTick: (remaining) => {
|
|
79
|
+
* console.log(`${remaining.days}d ${remaining.hours}h ${remaining.minutes}m ${remaining.seconds}s`);
|
|
80
|
+
* },
|
|
81
|
+
* onComplete: () => {
|
|
82
|
+
* console.log('Happy New Year!');
|
|
83
|
+
* }
|
|
84
|
+
* }
|
|
85
|
+
* );
|
|
86
|
+
*
|
|
87
|
+
* countdown.start();
|
|
88
|
+
* // Later...
|
|
89
|
+
* countdown.stop();
|
|
90
|
+
* ```
|
|
91
|
+
*/
|
|
92
|
+
export declare function createCountdown(targetDate: DateInput, options?: CountdownOptions): Countdown;
|
|
93
|
+
/**
|
|
94
|
+
* Gets the remaining time until/since a target date
|
|
95
|
+
* @param targetDate - The target date
|
|
96
|
+
* @param fromDate - The date to calculate from (defaults to now)
|
|
97
|
+
* @returns Object with remaining time broken down by units
|
|
98
|
+
*
|
|
99
|
+
* @example
|
|
100
|
+
* ```ts
|
|
101
|
+
* const remaining = getRemainingTime(new Date('2024-12-31'));
|
|
102
|
+
* console.log(`${remaining.days} days, ${remaining.hours} hours remaining`);
|
|
103
|
+
*
|
|
104
|
+
* // Check if expired
|
|
105
|
+
* if (remaining.isExpired) {
|
|
106
|
+
* console.log('Target date has passed');
|
|
107
|
+
* }
|
|
108
|
+
* ```
|
|
109
|
+
*/
|
|
110
|
+
export declare function getRemainingTime(targetDate: DateInput, fromDate?: DateInput): RemainingTime;
|
|
111
|
+
/**
|
|
112
|
+
* Formats the remaining time as a human-readable string
|
|
113
|
+
* @param targetDate - The target date
|
|
114
|
+
* @param options - Formatting options
|
|
115
|
+
* @returns Formatted countdown string
|
|
116
|
+
*
|
|
117
|
+
* @example
|
|
118
|
+
* ```ts
|
|
119
|
+
* formatCountdown(new Date('2024-12-31'));
|
|
120
|
+
* // "45d 12h 30m 15s"
|
|
121
|
+
*
|
|
122
|
+
* formatCountdown(new Date('2024-12-31'), { units: ['days', 'hours'] });
|
|
123
|
+
* // "45 days, 12 hours"
|
|
124
|
+
*
|
|
125
|
+
* formatCountdown(new Date('2024-12-31'), { short: false });
|
|
126
|
+
* // "45 days 12 hours 30 minutes 15 seconds"
|
|
127
|
+
* ```
|
|
128
|
+
*/
|
|
129
|
+
export declare function formatCountdown(targetDate: DateInput, options?: {
|
|
130
|
+
/** Date to calculate from (defaults to now) */
|
|
131
|
+
from?: DateInput;
|
|
132
|
+
/** Units to include in output */
|
|
133
|
+
units?: ('weeks' | 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds')[];
|
|
134
|
+
/** Use short format (d, h, m, s) */
|
|
135
|
+
short?: boolean;
|
|
136
|
+
/** Maximum number of units to show */
|
|
137
|
+
maxUnits?: number;
|
|
138
|
+
/** Show zero values */
|
|
139
|
+
showZero?: boolean;
|
|
140
|
+
/** Separator between units */
|
|
141
|
+
separator?: string;
|
|
142
|
+
}): string;
|
|
143
|
+
/**
|
|
144
|
+
* Checks if a date has expired (is in the past)
|
|
145
|
+
* @param date - The date to check
|
|
146
|
+
* @param fromDate - The reference date (defaults to now)
|
|
147
|
+
* @returns True if the date is in the past
|
|
148
|
+
*
|
|
149
|
+
* @example
|
|
150
|
+
* ```ts
|
|
151
|
+
* isExpired(new Date('2020-01-01')); // true
|
|
152
|
+
* isExpired(new Date('2030-01-01')); // false
|
|
153
|
+
* ```
|
|
154
|
+
*/
|
|
155
|
+
export declare function isExpired(date: DateInput, fromDate?: DateInput): boolean;
|
|
156
|
+
/**
|
|
157
|
+
* Calculates the progress percentage between two dates
|
|
158
|
+
* @param startDate - The start date
|
|
159
|
+
* @param endDate - The end date
|
|
160
|
+
* @param currentDate - The current date (defaults to now)
|
|
161
|
+
* @returns Progress percentage (0-100), clamped to range
|
|
162
|
+
*
|
|
163
|
+
* @example
|
|
164
|
+
* ```ts
|
|
165
|
+
* const progress = getProgressPercentage(
|
|
166
|
+
* new Date('2024-01-01'),
|
|
167
|
+
* new Date('2024-12-31'),
|
|
168
|
+
* new Date('2024-07-01')
|
|
169
|
+
* );
|
|
170
|
+
* console.log(`${progress}% complete`); // ~50% complete
|
|
171
|
+
* ```
|
|
172
|
+
*/
|
|
173
|
+
export declare function getProgressPercentage(startDate: DateInput, endDate: DateInput, currentDate?: DateInput): number;
|
|
174
|
+
/**
|
|
175
|
+
* Gets time until a target date in a specific unit
|
|
176
|
+
* @param targetDate - The target date
|
|
177
|
+
* @param unit - The unit to return
|
|
178
|
+
* @param fromDate - The date to calculate from (defaults to now)
|
|
179
|
+
* @returns Time remaining in the specified unit
|
|
180
|
+
*
|
|
181
|
+
* @example
|
|
182
|
+
* ```ts
|
|
183
|
+
* getTimeUntil(new Date('2024-12-31'), 'days'); // 45.5
|
|
184
|
+
* getTimeUntil(new Date('2024-12-31'), 'hours'); // 1092
|
|
185
|
+
* getTimeUntil(new Date('2024-12-31'), 'weeks'); // 6.5
|
|
186
|
+
* ```
|
|
187
|
+
*/
|
|
188
|
+
export declare function getTimeUntil(targetDate: DateInput, unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks', fromDate?: DateInput): number;
|
|
189
|
+
/**
|
|
190
|
+
* Creates a deadline object with useful methods
|
|
191
|
+
* @param targetDate - The deadline date
|
|
192
|
+
* @returns An object with deadline-related methods
|
|
193
|
+
*
|
|
194
|
+
* @example
|
|
195
|
+
* ```ts
|
|
196
|
+
* const deadline = createDeadline(new Date('2024-12-31'));
|
|
197
|
+
*
|
|
198
|
+
* deadline.isExpired(); // false
|
|
199
|
+
* deadline.daysRemaining(); // 45
|
|
200
|
+
* deadline.hoursRemaining(); // 1092
|
|
201
|
+
* deadline.formatRemaining(); // "45d 12h 30m"
|
|
202
|
+
* deadline.progressFrom(new Date('2024-01-01')); // 67.5%
|
|
203
|
+
* ```
|
|
204
|
+
*/
|
|
205
|
+
export declare function createDeadline(targetDate: DateInput): {
|
|
206
|
+
target: Date;
|
|
207
|
+
isExpired: () => boolean;
|
|
208
|
+
getRemaining: () => RemainingTime;
|
|
209
|
+
daysRemaining: () => number;
|
|
210
|
+
hoursRemaining: () => number;
|
|
211
|
+
minutesRemaining: () => number;
|
|
212
|
+
secondsRemaining: () => number;
|
|
213
|
+
formatRemaining: (options?: Parameters<typeof formatCountdown>[1]) => string;
|
|
214
|
+
progressFrom: (startDate: DateInput) => number;
|
|
215
|
+
countdown: (options?: CountdownOptions) => Countdown;
|
|
216
|
+
};
|
|
217
|
+
//# sourceMappingURL=countdown.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"countdown.d.ts","sourceRoot":"","sources":["../src/countdown.ts"],"names":[],"mappings":"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"}
|