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.
Files changed (40) hide show
  1. package/README.md +226 -1
  2. package/dist/calculate.d.ts.map +1 -1
  3. package/dist/calculate.js +24 -10
  4. package/dist/countdown.d.ts +217 -0
  5. package/dist/countdown.d.ts.map +1 -0
  6. package/dist/countdown.js +298 -0
  7. package/dist/dateRange.d.ts +266 -0
  8. package/dist/dateRange.d.ts.map +1 -0
  9. package/dist/dateRange.js +433 -0
  10. package/dist/esm/calculate.d.ts.map +1 -1
  11. package/dist/esm/calculate.js +24 -10
  12. package/dist/esm/countdown.d.ts +217 -0
  13. package/dist/esm/countdown.d.ts.map +1 -0
  14. package/dist/esm/countdown.js +298 -0
  15. package/dist/esm/dateRange.d.ts +266 -0
  16. package/dist/esm/dateRange.d.ts.map +1 -0
  17. package/dist/esm/dateRange.js +433 -0
  18. package/dist/esm/index.d.ts +5 -1
  19. package/dist/esm/index.d.ts.map +1 -1
  20. package/dist/esm/index.js +8 -0
  21. package/dist/esm/naturalLanguage.d.ts +107 -0
  22. package/dist/esm/naturalLanguage.d.ts.map +1 -0
  23. package/dist/esm/naturalLanguage.js +344 -0
  24. package/dist/esm/recurrence.d.ts +149 -0
  25. package/dist/esm/recurrence.d.ts.map +1 -0
  26. package/dist/esm/recurrence.js +404 -0
  27. package/dist/esm/types.d.ts +21 -0
  28. package/dist/esm/types.d.ts.map +1 -1
  29. package/dist/index.d.ts +5 -1
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +8 -0
  32. package/dist/naturalLanguage.d.ts +107 -0
  33. package/dist/naturalLanguage.d.ts.map +1 -0
  34. package/dist/naturalLanguage.js +344 -0
  35. package/dist/recurrence.d.ts +149 -0
  36. package/dist/recurrence.d.ts.map +1 -0
  37. package/dist/recurrence.js +404 -0
  38. package/dist/types.d.ts +21 -0
  39. package/dist/types.d.ts.map +1 -1
  40. 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** - 15 utility categories with 115+ functions
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
@@ -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,CAmCxE;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"}
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
- milliseconds = amount * MILLISECONDS_PER_YEAR;
52
+ case 'y':
53
+ result.setFullYear(result.getFullYear() + amount);
53
54
  break;
55
+ case 'month':
54
56
  case 'months':
55
- milliseconds = amount * MILLISECONDS_PER_MONTH;
57
+ case 'M':
58
+ result.setMonth(result.getMonth() + amount);
56
59
  break;
60
+ case 'week':
57
61
  case 'weeks':
58
- milliseconds = amount * MILLISECONDS_PER_WEEK;
62
+ case 'w':
63
+ result.setDate(result.getDate() + (amount * 7));
59
64
  break;
65
+ case 'day':
60
66
  case 'days':
61
- milliseconds = amount * MILLISECONDS_PER_DAY;
67
+ case 'd':
68
+ result.setDate(result.getDate() + amount);
62
69
  break;
70
+ case 'hour':
63
71
  case 'hours':
64
- milliseconds = amount * MILLISECONDS_PER_HOUR;
72
+ case 'h':
73
+ result.setHours(result.getHours() + amount);
65
74
  break;
75
+ case 'minute':
66
76
  case 'minutes':
67
- milliseconds = amount * MILLISECONDS_PER_MINUTE;
77
+ case 'm':
78
+ result.setMinutes(result.getMinutes() + amount);
68
79
  break;
80
+ case 'second':
69
81
  case 'seconds':
70
- milliseconds = amount * MILLISECONDS_PER_SECOND;
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
- milliseconds = amount;
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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"}