ts-time-utils 1.0.0 → 2.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 (102) hide show
  1. package/README.md +682 -11
  2. package/dist/calculate.d.ts +7 -2
  3. package/dist/calculate.d.ts.map +1 -1
  4. package/dist/calculate.js +37 -13
  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/compare.d.ts +217 -0
  9. package/dist/compare.d.ts.map +1 -0
  10. package/dist/compare.js +417 -0
  11. package/dist/countdown.d.ts +217 -0
  12. package/dist/countdown.d.ts.map +1 -0
  13. package/dist/countdown.js +298 -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/dateRange.d.ts +266 -0
  18. package/dist/dateRange.d.ts.map +1 -0
  19. package/dist/dateRange.js +433 -0
  20. package/dist/esm/calculate.d.ts +7 -2
  21. package/dist/esm/calculate.d.ts.map +1 -1
  22. package/dist/esm/calculate.js +37 -13
  23. package/dist/esm/calendar.d.ts +103 -0
  24. package/dist/esm/calendar.d.ts.map +1 -1
  25. package/dist/esm/calendar.js +224 -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/countdown.d.ts +217 -0
  30. package/dist/esm/countdown.d.ts.map +1 -0
  31. package/dist/esm/countdown.js +298 -0
  32. package/dist/esm/cron.d.ts +82 -0
  33. package/dist/esm/cron.d.ts.map +1 -0
  34. package/dist/esm/cron.js +294 -0
  35. package/dist/esm/dateRange.d.ts +266 -0
  36. package/dist/esm/dateRange.d.ts.map +1 -0
  37. package/dist/esm/dateRange.js +433 -0
  38. package/dist/esm/fiscal.d.ts +195 -0
  39. package/dist/esm/fiscal.d.ts.map +1 -0
  40. package/dist/esm/fiscal.js +295 -0
  41. package/dist/esm/format.d.ts +65 -0
  42. package/dist/esm/format.d.ts.map +1 -1
  43. package/dist/esm/format.js +202 -0
  44. package/dist/esm/index.d.ts +18 -7
  45. package/dist/esm/index.d.ts.map +1 -1
  46. package/dist/esm/index.js +22 -6
  47. package/dist/esm/iterate.d.ts +212 -0
  48. package/dist/esm/iterate.d.ts.map +1 -0
  49. package/dist/esm/iterate.js +409 -0
  50. package/dist/esm/naturalLanguage.d.ts +107 -0
  51. package/dist/esm/naturalLanguage.d.ts.map +1 -0
  52. package/dist/esm/naturalLanguage.js +344 -0
  53. package/dist/esm/parse.d.ts +45 -0
  54. package/dist/esm/parse.d.ts.map +1 -1
  55. package/dist/esm/parse.js +207 -0
  56. package/dist/esm/recurrence.d.ts +149 -0
  57. package/dist/esm/recurrence.d.ts.map +1 -0
  58. package/dist/esm/recurrence.js +404 -0
  59. package/dist/esm/timezone.d.ts +52 -0
  60. package/dist/esm/timezone.d.ts.map +1 -1
  61. package/dist/esm/timezone.js +171 -0
  62. package/dist/esm/types.d.ts +21 -0
  63. package/dist/esm/types.d.ts.map +1 -1
  64. package/dist/esm/validate.d.ts +51 -0
  65. package/dist/esm/validate.d.ts.map +1 -1
  66. package/dist/esm/validate.js +92 -0
  67. package/dist/esm/workingHours.d.ts +70 -0
  68. package/dist/esm/workingHours.d.ts.map +1 -1
  69. package/dist/esm/workingHours.js +161 -0
  70. package/dist/fiscal.d.ts +195 -0
  71. package/dist/fiscal.d.ts.map +1 -0
  72. package/dist/fiscal.js +295 -0
  73. package/dist/format.d.ts +65 -0
  74. package/dist/format.d.ts.map +1 -1
  75. package/dist/format.js +202 -0
  76. package/dist/index.d.ts +18 -7
  77. package/dist/index.d.ts.map +1 -1
  78. package/dist/index.js +22 -6
  79. package/dist/iterate.d.ts +212 -0
  80. package/dist/iterate.d.ts.map +1 -0
  81. package/dist/iterate.js +409 -0
  82. package/dist/naturalLanguage.d.ts +107 -0
  83. package/dist/naturalLanguage.d.ts.map +1 -0
  84. package/dist/naturalLanguage.js +344 -0
  85. package/dist/parse.d.ts +45 -0
  86. package/dist/parse.d.ts.map +1 -1
  87. package/dist/parse.js +207 -0
  88. package/dist/recurrence.d.ts +149 -0
  89. package/dist/recurrence.d.ts.map +1 -0
  90. package/dist/recurrence.js +404 -0
  91. package/dist/timezone.d.ts +52 -0
  92. package/dist/timezone.d.ts.map +1 -1
  93. package/dist/timezone.js +171 -0
  94. package/dist/types.d.ts +21 -0
  95. package/dist/types.d.ts.map +1 -1
  96. package/dist/validate.d.ts +51 -0
  97. package/dist/validate.d.ts.map +1 -1
  98. package/dist/validate.js +92 -0
  99. package/dist/workingHours.d.ts +70 -0
  100. package/dist/workingHours.d.ts.map +1 -1
  101. package/dist/workingHours.js +161 -0
  102. package/package.json +59 -12
@@ -0,0 +1,149 @@
1
+ /**
2
+ * @fileoverview Recurring events and pattern-based date generation utilities
3
+ * Provides RRULE-inspired recurrence patterns for creating repeating events
4
+ */
5
+ import type { DateInput, RecurrenceRule } from './types.js';
6
+ /**
7
+ * Creates a recurrence pattern generator
8
+ * @param rule - The recurrence rule defining the pattern
9
+ * @returns An object with methods to work with the recurrence
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * // Daily recurrence
14
+ * const daily = createRecurrence({
15
+ * frequency: 'daily',
16
+ * interval: 1,
17
+ * startDate: new Date('2024-01-01')
18
+ * });
19
+ *
20
+ * // Weekly on Monday and Wednesday
21
+ * const weekly = createRecurrence({
22
+ * frequency: 'weekly',
23
+ * interval: 1,
24
+ * startDate: new Date('2024-01-01'),
25
+ * byWeekday: [1, 3] // Monday = 1, Wednesday = 3
26
+ * });
27
+ *
28
+ * // Monthly on the 15th
29
+ * const monthly = createRecurrence({
30
+ * frequency: 'monthly',
31
+ * interval: 1,
32
+ * startDate: new Date('2024-01-01'),
33
+ * byMonthDay: [15]
34
+ * });
35
+ * ```
36
+ */
37
+ export declare function createRecurrence(rule: RecurrenceRule): {
38
+ rule: RecurrenceRule;
39
+ getNextOccurrence: (afterDate?: DateInput) => Date | null;
40
+ getOccurrencesBetween: (start: DateInput, end: DateInput, limit?: number) => Date[];
41
+ isRecurrenceDate: (date: DateInput) => boolean;
42
+ getAllOccurrences: (limit?: number) => Date[];
43
+ };
44
+ /**
45
+ * Gets the next occurrence of a recurring event after a specified date
46
+ * @param rule - The recurrence rule
47
+ * @param afterDate - Date to find next occurrence after (defaults to now)
48
+ * @returns The next occurrence date, or null if no more occurrences
49
+ *
50
+ * @example
51
+ * ```ts
52
+ * const rule = {
53
+ * frequency: 'daily',
54
+ * interval: 2,
55
+ * startDate: new Date('2024-01-01')
56
+ * };
57
+ *
58
+ * const next = getNextOccurrence(rule, new Date('2024-01-05'));
59
+ * // Returns Date('2024-01-07') - every other day
60
+ * ```
61
+ */
62
+ export declare function getNextOccurrence(rule: RecurrenceRule, afterDate?: DateInput): Date | null;
63
+ /**
64
+ * Gets all occurrences of a recurring event between two dates
65
+ * @param rule - The recurrence rule
66
+ * @param start - Start date of the range
67
+ * @param end - End date of the range
68
+ * @param limit - Maximum number of occurrences to return (default: 1000)
69
+ * @returns Array of dates that match the recurrence pattern
70
+ *
71
+ * @example
72
+ * ```ts
73
+ * const rule = {
74
+ * frequency: 'weekly',
75
+ * interval: 1,
76
+ * startDate: new Date('2024-01-01'),
77
+ * byWeekday: [1, 5] // Monday and Friday
78
+ * };
79
+ *
80
+ * const occurrences = getOccurrencesBetween(
81
+ * rule,
82
+ * new Date('2024-01-01'),
83
+ * new Date('2024-01-31')
84
+ * );
85
+ * // Returns all Mondays and Fridays in January 2024
86
+ * ```
87
+ */
88
+ export declare function getOccurrencesBetween(rule: RecurrenceRule, start: DateInput, end: DateInput, limit?: number): Date[];
89
+ /**
90
+ * Checks if a specific date matches a recurrence rule
91
+ * @param date - The date to check
92
+ * @param rule - The recurrence rule
93
+ * @returns True if the date matches the recurrence pattern
94
+ *
95
+ * @example
96
+ * ```ts
97
+ * const rule = {
98
+ * frequency: 'weekly',
99
+ * interval: 1,
100
+ * startDate: new Date('2024-01-01'),
101
+ * byWeekday: [1] // Mondays only
102
+ * };
103
+ *
104
+ * isRecurrenceDate(new Date('2024-01-08'), rule); // true (Monday)
105
+ * isRecurrenceDate(new Date('2024-01-09'), rule); // false (Tuesday)
106
+ * ```
107
+ */
108
+ export declare function isRecurrenceDate(date: DateInput, rule: RecurrenceRule): boolean;
109
+ /**
110
+ * Validates a recurrence rule
111
+ * @param rule - The recurrence rule to validate
112
+ * @returns True if the rule is valid
113
+ *
114
+ * @example
115
+ * ```ts
116
+ * isValidRecurrenceRule({
117
+ * frequency: 'daily',
118
+ * interval: 1,
119
+ * startDate: new Date()
120
+ * }); // true
121
+ *
122
+ * isValidRecurrenceRule({
123
+ * frequency: 'daily',
124
+ * interval: 0, // Invalid
125
+ * startDate: new Date()
126
+ * }); // false
127
+ * ```
128
+ */
129
+ export declare function isValidRecurrenceRule(rule: Partial<RecurrenceRule>): boolean;
130
+ /**
131
+ * Converts a recurrence rule to a human-readable string
132
+ * @param rule - The recurrence rule
133
+ * @returns A human-readable description
134
+ *
135
+ * @example
136
+ * ```ts
137
+ * const rule = {
138
+ * frequency: 'weekly',
139
+ * interval: 2,
140
+ * startDate: new Date('2024-01-01'),
141
+ * byWeekday: [1, 3, 5]
142
+ * };
143
+ *
144
+ * recurrenceToString(rule);
145
+ * // "Every 2 weeks on Monday, Wednesday, Friday"
146
+ * ```
147
+ */
148
+ export declare function recurrenceToString(rule: RecurrenceRule): string;
149
+ //# sourceMappingURL=recurrence.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"recurrence.d.ts","sourceRoot":"","sources":["../src/recurrence.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAuB,MAAM,YAAY,CAAC;AAGjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc;;oCAKjB,SAAS;mCACV,SAAS,OAAO,SAAS,UAAU,MAAM;6BAE/C,SAAS;;EAqBrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAyC1F;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,SAAS,EACd,KAAK,SAAO,GACX,IAAI,EAAE,CA6BR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAW/E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAgC5E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CA6C/D"}
@@ -0,0 +1,404 @@
1
+ /**
2
+ * @fileoverview Recurring events and pattern-based date generation utilities
3
+ * Provides RRULE-inspired recurrence patterns for creating repeating events
4
+ */
5
+ import { addTime } from './calculate.js';
6
+ /**
7
+ * Creates a recurrence pattern generator
8
+ * @param rule - The recurrence rule defining the pattern
9
+ * @returns An object with methods to work with the recurrence
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * // Daily recurrence
14
+ * const daily = createRecurrence({
15
+ * frequency: 'daily',
16
+ * interval: 1,
17
+ * startDate: new Date('2024-01-01')
18
+ * });
19
+ *
20
+ * // Weekly on Monday and Wednesday
21
+ * const weekly = createRecurrence({
22
+ * frequency: 'weekly',
23
+ * interval: 1,
24
+ * startDate: new Date('2024-01-01'),
25
+ * byWeekday: [1, 3] // Monday = 1, Wednesday = 3
26
+ * });
27
+ *
28
+ * // Monthly on the 15th
29
+ * const monthly = createRecurrence({
30
+ * frequency: 'monthly',
31
+ * interval: 1,
32
+ * startDate: new Date('2024-01-01'),
33
+ * byMonthDay: [15]
34
+ * });
35
+ * ```
36
+ */
37
+ export function createRecurrence(rule) {
38
+ const startDate = new Date(rule.startDate);
39
+ return {
40
+ rule,
41
+ getNextOccurrence: (afterDate) => getNextOccurrence(rule, afterDate),
42
+ getOccurrencesBetween: (start, end, limit) => getOccurrencesBetween(rule, start, end, limit),
43
+ isRecurrenceDate: (date) => isRecurrenceDate(date, rule),
44
+ getAllOccurrences: (limit = 100) => {
45
+ const occurrences = [];
46
+ let current = new Date(startDate);
47
+ let count = 0;
48
+ while (count < limit) {
49
+ if (rule.until && current > new Date(rule.until))
50
+ break;
51
+ if (rule.count && count >= rule.count)
52
+ break;
53
+ const next = getNextOccurrence(rule, current);
54
+ if (!next)
55
+ break;
56
+ occurrences.push(next);
57
+ current = new Date(next.getTime() + 1);
58
+ count++;
59
+ }
60
+ return occurrences;
61
+ }
62
+ };
63
+ }
64
+ /**
65
+ * Gets the next occurrence of a recurring event after a specified date
66
+ * @param rule - The recurrence rule
67
+ * @param afterDate - Date to find next occurrence after (defaults to now)
68
+ * @returns The next occurrence date, or null if no more occurrences
69
+ *
70
+ * @example
71
+ * ```ts
72
+ * const rule = {
73
+ * frequency: 'daily',
74
+ * interval: 2,
75
+ * startDate: new Date('2024-01-01')
76
+ * };
77
+ *
78
+ * const next = getNextOccurrence(rule, new Date('2024-01-05'));
79
+ * // Returns Date('2024-01-07') - every other day
80
+ * ```
81
+ */
82
+ export function getNextOccurrence(rule, afterDate) {
83
+ const after = afterDate ? new Date(afterDate) : new Date();
84
+ const start = new Date(rule.startDate);
85
+ // If afterDate is before start, check if start matches
86
+ if (after < start) {
87
+ if (matchesRecurrenceRule(start, rule)) {
88
+ return new Date(start);
89
+ }
90
+ }
91
+ // Check if we've exceeded count or until date
92
+ if (rule.until && after >= new Date(rule.until)) {
93
+ return null;
94
+ }
95
+ // Start searching from the day after 'after'
96
+ // We want strictly greater than after, so start from the next potential occurrence
97
+ let candidate = addTime(after, 1, 'day');
98
+ // Preserve time from start date
99
+ candidate.setHours(start.getHours(), start.getMinutes(), start.getSeconds(), start.getMilliseconds());
100
+ const maxIterations = 1000; // Prevent infinite loops
101
+ let iterations = 0;
102
+ while (iterations < maxIterations) {
103
+ if (rule.until && candidate > new Date(rule.until)) {
104
+ return null;
105
+ }
106
+ if (matchesRecurrenceRule(candidate, rule)) {
107
+ return new Date(candidate);
108
+ }
109
+ // Move to next potential date based on frequency
110
+ candidate = getNextCandidate(candidate, rule);
111
+ iterations++;
112
+ }
113
+ return null;
114
+ }
115
+ /**
116
+ * Gets all occurrences of a recurring event between two dates
117
+ * @param rule - The recurrence rule
118
+ * @param start - Start date of the range
119
+ * @param end - End date of the range
120
+ * @param limit - Maximum number of occurrences to return (default: 1000)
121
+ * @returns Array of dates that match the recurrence pattern
122
+ *
123
+ * @example
124
+ * ```ts
125
+ * const rule = {
126
+ * frequency: 'weekly',
127
+ * interval: 1,
128
+ * startDate: new Date('2024-01-01'),
129
+ * byWeekday: [1, 5] // Monday and Friday
130
+ * };
131
+ *
132
+ * const occurrences = getOccurrencesBetween(
133
+ * rule,
134
+ * new Date('2024-01-01'),
135
+ * new Date('2024-01-31')
136
+ * );
137
+ * // Returns all Mondays and Fridays in January 2024
138
+ * ```
139
+ */
140
+ export function getOccurrencesBetween(rule, start, end, limit = 1000) {
141
+ const startDate = new Date(start);
142
+ const endDate = new Date(end);
143
+ const occurrences = [];
144
+ let current = new Date(rule.startDate);
145
+ // Fast forward to start date if recurrence starts before range
146
+ if (current < startDate) {
147
+ current = new Date(startDate);
148
+ }
149
+ let iterations = 0;
150
+ const maxIterations = limit * 10; // Safety limit
151
+ while (current <= endDate && occurrences.length < limit && iterations < maxIterations) {
152
+ if (rule.until && current > new Date(rule.until)) {
153
+ break;
154
+ }
155
+ if (matchesRecurrenceRule(current, rule) && current >= startDate) {
156
+ occurrences.push(new Date(current));
157
+ }
158
+ current = getNextCandidate(current, rule);
159
+ iterations++;
160
+ }
161
+ return occurrences;
162
+ }
163
+ /**
164
+ * Checks if a specific date matches a recurrence rule
165
+ * @param date - The date to check
166
+ * @param rule - The recurrence rule
167
+ * @returns True if the date matches the recurrence pattern
168
+ *
169
+ * @example
170
+ * ```ts
171
+ * const rule = {
172
+ * frequency: 'weekly',
173
+ * interval: 1,
174
+ * startDate: new Date('2024-01-01'),
175
+ * byWeekday: [1] // Mondays only
176
+ * };
177
+ *
178
+ * isRecurrenceDate(new Date('2024-01-08'), rule); // true (Monday)
179
+ * isRecurrenceDate(new Date('2024-01-09'), rule); // false (Tuesday)
180
+ * ```
181
+ */
182
+ export function isRecurrenceDate(date, rule) {
183
+ const checkDate = new Date(date);
184
+ const start = new Date(rule.startDate);
185
+ // Must be on or after start date
186
+ if (checkDate < start)
187
+ return false;
188
+ // Must be before until date if specified
189
+ if (rule.until && checkDate > new Date(rule.until))
190
+ return false;
191
+ return matchesRecurrenceRule(checkDate, rule);
192
+ }
193
+ /**
194
+ * Validates a recurrence rule
195
+ * @param rule - The recurrence rule to validate
196
+ * @returns True if the rule is valid
197
+ *
198
+ * @example
199
+ * ```ts
200
+ * isValidRecurrenceRule({
201
+ * frequency: 'daily',
202
+ * interval: 1,
203
+ * startDate: new Date()
204
+ * }); // true
205
+ *
206
+ * isValidRecurrenceRule({
207
+ * frequency: 'daily',
208
+ * interval: 0, // Invalid
209
+ * startDate: new Date()
210
+ * }); // false
211
+ * ```
212
+ */
213
+ export function isValidRecurrenceRule(rule) {
214
+ if (!rule.frequency || !rule.startDate)
215
+ return false;
216
+ const validFrequencies = ['daily', 'weekly', 'monthly', 'yearly'];
217
+ if (!validFrequencies.includes(rule.frequency))
218
+ return false;
219
+ if (rule.interval !== undefined && rule.interval < 1)
220
+ return false;
221
+ if (rule.count !== undefined && rule.count < 1)
222
+ return false;
223
+ if (rule.until) {
224
+ const until = new Date(rule.until);
225
+ const start = new Date(rule.startDate);
226
+ if (until <= start)
227
+ return false;
228
+ }
229
+ if (rule.byWeekday) {
230
+ if (!Array.isArray(rule.byWeekday))
231
+ return false;
232
+ if (!rule.byWeekday.every((d) => d >= 0 && d <= 6))
233
+ return false;
234
+ }
235
+ if (rule.byMonthDay) {
236
+ if (!Array.isArray(rule.byMonthDay))
237
+ return false;
238
+ if (!rule.byMonthDay.every((d) => d >= 1 && d <= 31))
239
+ return false;
240
+ }
241
+ if (rule.byMonth) {
242
+ if (!Array.isArray(rule.byMonth))
243
+ return false;
244
+ if (!rule.byMonth.every((m) => m >= 1 && m <= 12))
245
+ return false;
246
+ }
247
+ return true;
248
+ }
249
+ /**
250
+ * Converts a recurrence rule to a human-readable string
251
+ * @param rule - The recurrence rule
252
+ * @returns A human-readable description
253
+ *
254
+ * @example
255
+ * ```ts
256
+ * const rule = {
257
+ * frequency: 'weekly',
258
+ * interval: 2,
259
+ * startDate: new Date('2024-01-01'),
260
+ * byWeekday: [1, 3, 5]
261
+ * };
262
+ *
263
+ * recurrenceToString(rule);
264
+ * // "Every 2 weeks on Monday, Wednesday, Friday"
265
+ * ```
266
+ */
267
+ export function recurrenceToString(rule) {
268
+ const interval = rule.interval || 1;
269
+ let result = interval === 1 ? 'Every' : `Every ${interval}`;
270
+ switch (rule.frequency) {
271
+ case 'daily':
272
+ result += interval === 1 ? ' day' : ' days';
273
+ break;
274
+ case 'weekly':
275
+ result += interval === 1 ? ' week' : ' weeks';
276
+ if (rule.byWeekday && rule.byWeekday.length > 0) {
277
+ const days = rule.byWeekday.map((d) => ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][d]);
278
+ result += ` on ${days.join(', ')}`;
279
+ }
280
+ break;
281
+ case 'monthly':
282
+ result += interval === 1 ? ' month' : ' months';
283
+ if (rule.byMonthDay && rule.byMonthDay.length > 0) {
284
+ result += ` on day ${rule.byMonthDay.join(', ')}`;
285
+ }
286
+ break;
287
+ case 'yearly':
288
+ result += interval === 1 ? ' year' : ' years';
289
+ if (rule.byMonth && rule.byMonth.length > 0) {
290
+ const months = rule.byMonth.map((m) => ['January', 'February', 'March', 'April', 'May', 'June',
291
+ 'July', 'August', 'September', 'October', 'November', 'December'][m - 1]);
292
+ result += ` in ${months.join(', ')}`;
293
+ }
294
+ if (rule.byMonthDay && rule.byMonthDay.length > 0) {
295
+ result += ` on day ${rule.byMonthDay.join(', ')}`;
296
+ }
297
+ break;
298
+ }
299
+ if (rule.count) {
300
+ result += ` (${rule.count} times)`;
301
+ }
302
+ else if (rule.until) {
303
+ result += ` until ${new Date(rule.until).toLocaleDateString()}`;
304
+ }
305
+ return result;
306
+ }
307
+ // Helper functions
308
+ function matchesRecurrenceRule(date, rule) {
309
+ const start = new Date(rule.startDate);
310
+ start.setHours(0, 0, 0, 0);
311
+ const checkDate = new Date(date);
312
+ checkDate.setHours(0, 0, 0, 0);
313
+ const interval = rule.interval || 1;
314
+ // Check if date matches the frequency and interval
315
+ switch (rule.frequency) {
316
+ case 'daily': {
317
+ // Calculate days difference more reliably
318
+ const msPerDay = 1000 * 60 * 60 * 24;
319
+ const daysDiff = Math.round((checkDate.getTime() - start.getTime()) / msPerDay);
320
+ if (daysDiff < 0)
321
+ return false;
322
+ if (daysDiff % interval !== 0)
323
+ return false;
324
+ break;
325
+ }
326
+ case 'weekly': {
327
+ // If byWeekday is specified, check if current day matches
328
+ if (rule.byWeekday && rule.byWeekday.length > 0) {
329
+ if (!rule.byWeekday.includes(date.getDay())) {
330
+ return false;
331
+ }
332
+ }
333
+ else {
334
+ // No specific weekdays - match same day of week as start
335
+ if (date.getDay() !== start.getDay())
336
+ return false;
337
+ }
338
+ // Check interval
339
+ const msPerDay = 1000 * 60 * 60 * 24;
340
+ const daysDiff = Math.round((checkDate.getTime() - start.getTime()) / msPerDay);
341
+ const weeksDiff = Math.floor(daysDiff / 7);
342
+ if (weeksDiff % interval !== 0)
343
+ return false;
344
+ break;
345
+ }
346
+ case 'monthly': {
347
+ const monthsDiff = (date.getFullYear() - start.getFullYear()) * 12 +
348
+ (date.getMonth() - start.getMonth());
349
+ if (monthsDiff < 0)
350
+ return false;
351
+ if (monthsDiff % interval !== 0)
352
+ return false;
353
+ if (rule.byMonthDay && !rule.byMonthDay.includes(date.getDate())) {
354
+ return false;
355
+ }
356
+ break;
357
+ }
358
+ case 'yearly': {
359
+ const yearsDiff = date.getFullYear() - start.getFullYear();
360
+ if (yearsDiff < 0)
361
+ return false;
362
+ if (yearsDiff % interval !== 0)
363
+ return false;
364
+ if (rule.byMonth && !rule.byMonth.includes(date.getMonth() + 1)) {
365
+ return false;
366
+ }
367
+ if (rule.byMonthDay && !rule.byMonthDay.includes(date.getDate())) {
368
+ return false;
369
+ }
370
+ break;
371
+ }
372
+ }
373
+ return true;
374
+ }
375
+ function getNextCandidate(date, rule) {
376
+ const interval = rule.interval || 1;
377
+ switch (rule.frequency) {
378
+ case 'daily':
379
+ // For daily recurrence, always increment by 1 day to check each day
380
+ // matchesRecurrenceRule will filter based on interval
381
+ return addTime(date, 1, 'day');
382
+ case 'weekly':
383
+ // If we have specific weekdays, try next day, otherwise skip full interval
384
+ if (rule.byWeekday && rule.byWeekday.length > 0) {
385
+ return addTime(date, 1, 'day');
386
+ }
387
+ return addTime(date, interval * 7, 'day');
388
+ case 'monthly':
389
+ // If we have specific days of month, try next day, otherwise skip full interval
390
+ if (rule.byMonthDay && rule.byMonthDay.length > 0) {
391
+ return addTime(date, 1, 'day');
392
+ }
393
+ return addTime(date, interval, 'month');
394
+ case 'yearly':
395
+ // If we have specific months or days, try next day, otherwise skip full interval
396
+ if ((rule.byMonth && rule.byMonth.length > 0) ||
397
+ (rule.byMonthDay && rule.byMonthDay.length > 0)) {
398
+ return addTime(date, 1, 'day');
399
+ }
400
+ return addTime(date, interval, 'year');
401
+ default:
402
+ return addTime(date, 1, 'day');
403
+ }
404
+ }
@@ -31,4 +31,56 @@ export declare function compareZoneOffsets(zoneA: string, zoneB: string, date?:
31
31
  * For example useful for naive scheduling.
32
32
  */
33
33
  export declare function reinterpretAsZone(date: Date, targetZone: string): Date | null;
34
+ /**
35
+ * Check if a date is in Daylight Saving Time for a given timezone
36
+ * @param date - date to check
37
+ * @param zone - IANA timezone string
38
+ */
39
+ export declare function isDST(date: Date, zone: string): boolean | null;
40
+ /**
41
+ * Get the next DST transition (if any) for a timezone
42
+ * @param date - starting date
43
+ * @param zone - IANA timezone string
44
+ * @returns next DST transition date or null if no DST in that zone
45
+ */
46
+ export declare function getNextDSTTransition(date: Date, zone: string): Date | null;
47
+ /**
48
+ * Find overlapping working hours between multiple timezones
49
+ * @param zones - array of IANA timezone strings
50
+ * @param workHoursStart - work hours start (0-24)
51
+ * @param workHoursEnd - work hours end (0-24)
52
+ * @param date - reference date (default: today)
53
+ * @returns array of overlapping hour ranges in UTC, or null if no overlap
54
+ */
55
+ export declare function findCommonWorkingHours(zones: string[], workHoursStart?: number, workHoursEnd?: number, date?: Date): {
56
+ startUTC: number;
57
+ endUTC: number;
58
+ } | null;
59
+ /**
60
+ * Get all timezone abbreviations for a zone on a given date
61
+ * @param zone - IANA timezone string
62
+ * @param date - reference date
63
+ */
64
+ export declare function getTimezoneAbbreviation(zone: string, date?: Date): string | null;
65
+ /**
66
+ * Convert a wall clock time from one timezone to another
67
+ * @param date - date with time in source timezone
68
+ * @param fromZone - source timezone
69
+ * @param toZone - target timezone
70
+ */
71
+ export declare function convertBetweenZones(date: Date, fromZone: string, toZone: string): Date | null;
72
+ /**
73
+ * Get the time difference between two timezones in hours
74
+ * @param zoneA - first timezone
75
+ * @param zoneB - second timezone
76
+ * @param date - reference date
77
+ */
78
+ export declare function getTimezoneDifferenceHours(zoneA: string, zoneB: string, date?: Date): number | null;
79
+ /**
80
+ * Check if two timezones have the same offset at a given date
81
+ * @param zoneA - first timezone
82
+ * @param zoneB - second timezone
83
+ * @param date - reference date
84
+ */
85
+ export declare function isSameTimezone(zoneA: string, zoneB: string, date?: Date): boolean | null;
34
86
  //# sourceMappingURL=timezone.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../src/timezone.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAgBtF;AAED,iCAAiC;AACjC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,qBAA0B,GAAG,MAAM,CAG3G;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIvE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;CAAE,GAAG,IAAI,CAoB9J;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,UAK5B,CAAC;AAEF,0CAA0C;AAC1C,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAKvG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAI7E"}
1
+ {"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../src/timezone.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAgBtF;AAED,iCAAiC;AACjC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,qBAA0B,GAAG,MAAM,CAG3G;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIvE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;CAAE,GAAG,IAAI,CAoB9J;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,UAK5B,CAAC;AAEF,0CAA0C;AAC1C,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAKvG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAI7E;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA0B9D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAiD1E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EAAE,EACf,cAAc,GAAE,MAAU,EAC1B,YAAY,GAAE,MAAW,EACzB,IAAI,GAAE,IAAiB,GACtB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA6B7C;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAY5F;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAa7F;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAI/G;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,OAAO,GAAG,IAAI,CAIpG"}