@c9up/chronos 0.1.14 → 0.1.16

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 (52) hide show
  1. package/README.md +63 -16
  2. package/dist/DateTime.d.ts +145 -4
  3. package/dist/DateTime.d.ts.map +1 -1
  4. package/dist/DateTime.js +504 -87
  5. package/dist/DateTime.js.map +1 -1
  6. package/dist/Duration.d.ts +37 -20
  7. package/dist/Duration.d.ts.map +1 -1
  8. package/dist/Duration.js +287 -120
  9. package/dist/Duration.js.map +1 -1
  10. package/dist/Interval.d.ts +50 -7
  11. package/dist/Interval.d.ts.map +1 -1
  12. package/dist/Interval.js +142 -29
  13. package/dist/Interval.js.map +1 -1
  14. package/dist/atlas.d.ts +11 -15
  15. package/dist/atlas.d.ts.map +1 -1
  16. package/dist/atlas.js +22 -17
  17. package/dist/atlas.js.map +1 -1
  18. package/dist/format.d.ts +37 -0
  19. package/dist/format.d.ts.map +1 -0
  20. package/dist/format.js +387 -0
  21. package/dist/format.js.map +1 -0
  22. package/dist/index.d.ts +5 -5
  23. package/dist/index.d.ts.map +1 -1
  24. package/dist/index.js +3 -3
  25. package/dist/index.js.map +1 -1
  26. package/dist/native/generated.d.ts +2 -2
  27. package/dist/native/generated.d.ts.map +1 -1
  28. package/dist/native.js +2 -2
  29. package/dist/native.js.map +1 -1
  30. package/dist/rrule.d.ts +25 -1
  31. package/dist/rrule.d.ts.map +1 -1
  32. package/dist/rrule.js +130 -32
  33. package/dist/rrule.js.map +1 -1
  34. package/index.darwin-arm64.node +0 -0
  35. package/index.darwin-x64.node +0 -0
  36. package/index.linux-arm64-gnu.node +0 -0
  37. package/index.linux-x64-gnu.node +0 -0
  38. package/index.win32-x64-msvc.node +0 -0
  39. package/package.json +3 -2
  40. package/src/DateTime.ts +645 -96
  41. package/src/Duration.ts +318 -139
  42. package/src/Interval.ts +160 -53
  43. package/src/atlas.ts +23 -17
  44. package/src/format.ts +449 -0
  45. package/src/index.ts +17 -7
  46. package/src/native/generated.ts +6 -2
  47. package/src/native.ts +3 -3
  48. package/src/rrule.ts +189 -37
  49. package/wasm/chronos_engine_wasm.d.ts +4 -4
  50. package/wasm/chronos_engine_wasm.js +26 -16
  51. package/wasm/chronos_engine_wasm_bg.wasm +0 -0
  52. package/wasm/chronos_engine_wasm_bg.wasm.d.ts +2 -2
package/src/rrule.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { type DateInput, DateTime } from "./DateTime.js";
1
2
  import { nativeChronos } from "./native.js";
2
3
 
3
4
  export type RRuleWeekday = "MO" | "TU" | "WE" | "TH" | "FR" | "SA" | "SU";
@@ -27,37 +28,124 @@ export interface RRuleBuild {
27
28
  until?: string;
28
29
  }
29
30
 
31
+ const FREQUENCIES: ReadonlySet<string> = new Set([
32
+ "SECONDLY",
33
+ "MINUTELY",
34
+ "HOURLY",
35
+ "DAILY",
36
+ "WEEKLY",
37
+ "MONTHLY",
38
+ "YEARLY",
39
+ ]);
40
+ const WEEKDAYS: ReadonlySet<string> = new Set([
41
+ "MO",
42
+ "TU",
43
+ "WE",
44
+ "TH",
45
+ "FR",
46
+ "SA",
47
+ "SU",
48
+ ]);
49
+ const BYDAY_TOKEN =
50
+ /^(?:[+-]?(?:[1-9]|[1-4]\d|5[0-3]))?(?:MO|TU|WE|TH|FR|SA|SU)$/;
51
+
52
+ /**
53
+ * The structured input is only typed, never trusted: a value that reaches the
54
+ * rule text unchecked (`byDay: ["MO;BYSECOND=0,0,…"]` from a JSON body) adds
55
+ * parts the caller never wrote.
56
+ */
57
+ function invalid(field: string, value: unknown): never {
58
+ throw new RangeError(`toRRuleString: invalid ${field} ${String(value)}`);
59
+ }
60
+
61
+ function checkInteger(
62
+ field: string,
63
+ value: unknown,
64
+ min: number,
65
+ max: number,
66
+ allowZero = true,
67
+ ): number {
68
+ if (
69
+ typeof value !== "number" ||
70
+ !Number.isInteger(value) ||
71
+ value < min ||
72
+ value > max ||
73
+ (value === 0 && !allowZero)
74
+ ) {
75
+ return invalid(field, value);
76
+ }
77
+ return value;
78
+ }
79
+
30
80
  function pushNumericList(
31
81
  parts: string[],
32
82
  key: string,
33
- values: number[] | undefined,
83
+ field: string,
84
+ values: readonly unknown[] | undefined,
85
+ range: [min: number, max: number, allowZero: boolean],
34
86
  ): void {
35
- if (!values || values.length === 0) return;
36
- parts.push(`${key}=${values.join(",")}`);
87
+ if (values === undefined) return;
88
+ if (!Array.isArray(values)) invalid(field, values);
89
+ if (values.length === 0) return;
90
+ const checked = values.map((v) => checkInteger(field, v, ...range));
91
+ parts.push(`${key}=${checked.join(",")}`);
37
92
  }
38
93
 
39
94
  export function toRRuleString(rule: RRuleBuild): string {
95
+ if (!FREQUENCIES.has(rule.freq)) invalid("freq", rule.freq);
40
96
  const parts: string[] = [`FREQ=${rule.freq}`];
41
97
 
42
- if (rule.interval && rule.interval !== 1)
43
- parts.push(`INTERVAL=${rule.interval}`);
44
- if (rule.wkst) parts.push(`WKST=${rule.wkst}`);
45
- if (rule.byDay?.length) parts.push(`BYDAY=${rule.byDay.join(",")}`);
46
-
47
- pushNumericList(parts, "BYMONTHDAY", rule.byMonthDay);
48
- pushNumericList(parts, "BYMONTH", rule.byMonth);
49
- pushNumericList(parts, "BYWEEKNO", rule.byWeekNo);
50
- pushNumericList(parts, "BYYEARDAY", rule.byYearDay);
51
- pushNumericList(parts, "BYSETPOS", rule.bySetPos);
52
- pushNumericList(parts, "BYHOUR", rule.byHour);
53
- pushNumericList(parts, "BYMINUTE", rule.byMinute);
54
- pushNumericList(parts, "BYSECOND", rule.bySecond);
55
-
56
- if (rule.count !== undefined) parts.push(`COUNT=${rule.count}`);
57
- if (rule.until) {
98
+ if (rule.interval !== undefined) {
99
+ const interval = checkInteger("interval", rule.interval, 1, 1_000_000_000);
100
+ if (interval !== 1) parts.push(`INTERVAL=${interval}`);
101
+ }
102
+ if (rule.wkst !== undefined) {
103
+ if (!WEEKDAYS.has(rule.wkst)) invalid("wkst", rule.wkst);
104
+ parts.push(`WKST=${rule.wkst}`);
105
+ }
106
+ if (rule.byDay !== undefined) {
107
+ if (!Array.isArray(rule.byDay)) invalid("byDay", rule.byDay);
108
+ for (const token of rule.byDay) {
109
+ if (typeof token !== "string" || !BYDAY_TOKEN.test(token))
110
+ invalid("byDay", token);
111
+ }
112
+ if (rule.byDay.length > 0) parts.push(`BYDAY=${rule.byDay.join(",")}`);
113
+ }
114
+
115
+ pushNumericList(parts, "BYMONTHDAY", "byMonthDay", rule.byMonthDay, [
116
+ -31,
117
+ 31,
118
+ false,
119
+ ]);
120
+ pushNumericList(parts, "BYMONTH", "byMonth", rule.byMonth, [1, 12, false]);
121
+ pushNumericList(parts, "BYWEEKNO", "byWeekNo", rule.byWeekNo, [
122
+ -53,
123
+ 53,
124
+ false,
125
+ ]);
126
+ pushNumericList(parts, "BYYEARDAY", "byYearDay", rule.byYearDay, [
127
+ -366,
128
+ 366,
129
+ false,
130
+ ]);
131
+ pushNumericList(parts, "BYSETPOS", "bySetPos", rule.bySetPos, [
132
+ -366,
133
+ 366,
134
+ false,
135
+ ]);
136
+ pushNumericList(parts, "BYHOUR", "byHour", rule.byHour, [0, 23, true]);
137
+ pushNumericList(parts, "BYMINUTE", "byMinute", rule.byMinute, [0, 59, true]);
138
+ pushNumericList(parts, "BYSECOND", "bySecond", rule.bySecond, [0, 59, true]);
139
+
140
+ if (rule.count !== undefined)
141
+ parts.push(`COUNT=${checkInteger("count", rule.count, 0, 1_000_000_000)}`);
142
+ if (rule.until !== undefined) {
143
+ const ms =
144
+ typeof rule.until === "string" ? Date.parse(rule.until) : Number.NaN;
145
+ if (!Number.isFinite(ms)) invalid("until", rule.until);
58
146
  // RFC 5545 §3.3.10 UNTIL format: YYYYMMDDTHHMMSSZ (no hyphens/colons/ms).
59
147
  parts.push(
60
- `UNTIL=${new Date(rule.until)
148
+ `UNTIL=${new Date(ms)
61
149
  .toISOString()
62
150
  .replace(/[-:]/g, "")
63
151
  .replace(/\.\d+Z$/, "Z")}`,
@@ -68,24 +156,37 @@ export function toRRuleString(rule: RRuleBuild): string {
68
156
  }
69
157
 
70
158
  /**
71
- * Expand an RRULE into concrete occurrence dates. **NAPI-only** — the Rust
72
- * engine handles the full RFC 5545 spec (BYDAY, BYSETPOS, BYMONTHDAY,
73
- * BYWEEKNO, BYYEARDAY, UNTIL, COUNT, INTERVAL, WKST). No TS fallback.
74
- */
75
- /**
76
- * Hard cap on `expandRRule(... , limit)` so a caller passing an absurd
77
- * number (or one derived from user input) can't ask the Rust engine to
78
- * allocate gigabytes / run for seconds. 10_000 covers any realistic
79
- * pagination + cushion (a year of every-minute occurrences = ~525k, so
80
- * apps wanting that should iterate or stream, not call once).
159
+ * Hard cap on the number of occurrences one call returns, so a caller passing
160
+ * an absurd limit (or one derived from user input) cannot ask for an unbounded
161
+ * result. 10 000 covers any realistic page; page through the series (start
162
+ * from the last occurrence) for more.
81
163
  */
82
164
  const MAX_RRULE_EXPAND = 10_000;
83
165
 
84
- export function expandRRule(
85
- startIso: string,
86
- rrule: string | RRuleBuild,
87
- limit = 100,
88
- ): string[] {
166
+ export interface ExpandRRuleOptions {
167
+ /** Most occurrences to return (1 – 10 000, default 100). */
168
+ limit?: number;
169
+ /**
170
+ * IANA zone whose wall clock the rule runs on (RFC 5545 DTSTART;TZID): a
171
+ * weekly 09:00 series stays at 09:00 local across DST. Defaults to the zone
172
+ * of a zoned `DateTime` start, else UTC.
173
+ */
174
+ tzid?: string;
175
+ }
176
+
177
+ function isRRuleBuild(value: unknown): value is RRuleBuild {
178
+ return typeof value === "object" && value !== null && "freq" in value;
179
+ }
180
+
181
+ function readOptions(
182
+ options: number | ExpandRRuleOptions | undefined,
183
+ ): ExpandRRuleOptions {
184
+ if (options === undefined) return {};
185
+ if (typeof options === "number") return { limit: options };
186
+ return options;
187
+ }
188
+
189
+ function checkLimit(limit: number): number {
89
190
  if (!Number.isInteger(limit) || limit < 1) {
90
191
  throw new RangeError(
91
192
  `expandRRule(limit) must be a positive integer (got ${String(limit)})`,
@@ -97,6 +198,57 @@ export function expandRRule(
97
198
  "Page through the result set instead of asking for everything at once.",
98
199
  );
99
200
  }
100
- const built = typeof rrule === "string" ? rrule : toRRuleString(rrule);
101
- return nativeChronos().rruleExpand(startIso, built, limit);
201
+ return limit;
202
+ }
203
+
204
+ /**
205
+ * Expand an RRULE (RFC 5545) into occurrences, returned as UTC ISO strings.
206
+ *
207
+ * - `expandRRule(start, rule, limit | { limit, tzid })` — `start` is DTSTART;
208
+ * a zoned `DateTime` makes the rule run on its zone's wall clock.
209
+ * - `expandRRule("DTSTART;TZID=Europe/Paris:20260323T090000\nRRULE:…", options)`
210
+ * — the iCalendar form, DTSTART read from the text.
211
+ *
212
+ * The Rust engine bounds the work whatever the rule says (BY* lists are sets,
213
+ * the text is capped at 8 KB, iteration ends at year 9999), so a rule taken
214
+ * from user input or an imported .ics cannot exhaust memory or hold the thread.
215
+ */
216
+ export function expandRRule(
217
+ start: DateInput,
218
+ rrule: string | RRuleBuild,
219
+ options?: number | ExpandRRuleOptions,
220
+ ): string[];
221
+ export function expandRRule(
222
+ rule: string,
223
+ options?: number | ExpandRRuleOptions,
224
+ ): string[];
225
+ export function expandRRule(
226
+ start: DateInput,
227
+ rruleOrOptions?: string | RRuleBuild | number | ExpandRRuleOptions,
228
+ maybeOptions?: number | ExpandRRuleOptions,
229
+ ): string[] {
230
+ if (typeof rruleOrOptions === "string" || isRRuleBuild(rruleOrOptions)) {
231
+ const options = readOptions(maybeOptions);
232
+ const limit = checkLimit(options.limit ?? 100);
233
+ const from = DateTime.from(start);
234
+ const tzid =
235
+ options.tzid ?? (from.zoneName === "UTC" ? undefined : from.zoneName);
236
+ const rule =
237
+ typeof rruleOrOptions === "string"
238
+ ? rruleOrOptions
239
+ : toRRuleString(rruleOrOptions);
240
+ return nativeChronos().rruleExpand(from.toISO(), rule, limit, tzid);
241
+ }
242
+ if (typeof start !== "string") {
243
+ throw new TypeError(
244
+ "expandRRule(rule, options) takes the rule text, with its DTSTART line, as the first argument",
245
+ );
246
+ }
247
+ const options = readOptions(rruleOrOptions);
248
+ return nativeChronos().rruleExpand(
249
+ undefined,
250
+ start,
251
+ checkLimit(options.limit ?? 100),
252
+ options.tzid,
253
+ );
102
254
  }
@@ -23,9 +23,9 @@ export function parse_http(input: string): string;
23
23
 
24
24
  export function parse_rfc2822(input: string): string;
25
25
 
26
- export function parse_sql(input: string): string;
26
+ export function parse_sql(input: string, zone?: string | null): string;
27
27
 
28
- export function rrule_expand(start_iso: string, rrule: string, limit: number): any;
28
+ export function rrule_expand(start_iso: string | null | undefined, rrule: string, limit: number, tzid?: string | null): any;
29
29
 
30
30
  export function start_of(iso: string, unit: string): string;
31
31
 
@@ -52,8 +52,8 @@ export interface InitOutput {
52
52
  readonly from_local: (a: number, b: number, c: number, d: number) => [number, number, number, number];
53
53
  readonly parse_http: (a: number, b: number) => [number, number, number, number];
54
54
  readonly parse_rfc2822: (a: number, b: number) => [number, number, number, number];
55
- readonly parse_sql: (a: number, b: number) => [number, number, number, number];
56
- readonly rrule_expand: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
55
+ readonly parse_sql: (a: number, b: number, c: number, d: number) => [number, number, number, number];
56
+ readonly rrule_expand: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
57
57
  readonly start_of: (a: number, b: number, c: number, d: number) => [number, number, number, number];
58
58
  readonly start_of_in_zone: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
59
59
  readonly to_zone: (a: number, b: number, c: number, d: number) => [number, number, number];
@@ -285,41 +285,47 @@ export function parse_rfc2822(input) {
285
285
 
286
286
  /**
287
287
  * @param {string} input
288
+ * @param {string | null} [zone]
288
289
  * @returns {string}
289
290
  */
290
- export function parse_sql(input) {
291
- let deferred3_0;
292
- let deferred3_1;
291
+ export function parse_sql(input, zone) {
292
+ let deferred4_0;
293
+ let deferred4_1;
293
294
  try {
294
295
  const ptr0 = passStringToWasm0(input, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
295
296
  const len0 = WASM_VECTOR_LEN;
296
- const ret = wasm.parse_sql(ptr0, len0);
297
- var ptr2 = ret[0];
298
- var len2 = ret[1];
297
+ var ptr1 = isLikeNone(zone) ? 0 : passStringToWasm0(zone, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
298
+ var len1 = WASM_VECTOR_LEN;
299
+ const ret = wasm.parse_sql(ptr0, len0, ptr1, len1);
300
+ var ptr3 = ret[0];
301
+ var len3 = ret[1];
299
302
  if (ret[3]) {
300
- ptr2 = 0; len2 = 0;
303
+ ptr3 = 0; len3 = 0;
301
304
  throw takeFromExternrefTable0(ret[2]);
302
305
  }
303
- deferred3_0 = ptr2;
304
- deferred3_1 = len2;
305
- return getStringFromWasm0(ptr2, len2);
306
+ deferred4_0 = ptr3;
307
+ deferred4_1 = len3;
308
+ return getStringFromWasm0(ptr3, len3);
306
309
  } finally {
307
- wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
310
+ wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
308
311
  }
309
312
  }
310
313
 
311
314
  /**
312
- * @param {string} start_iso
315
+ * @param {string | null | undefined} start_iso
313
316
  * @param {string} rrule
314
317
  * @param {number} limit
318
+ * @param {string | null} [tzid]
315
319
  * @returns {any}
316
320
  */
317
- export function rrule_expand(start_iso, rrule, limit) {
318
- const ptr0 = passStringToWasm0(start_iso, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
319
- const len0 = WASM_VECTOR_LEN;
321
+ export function rrule_expand(start_iso, rrule, limit, tzid) {
322
+ var ptr0 = isLikeNone(start_iso) ? 0 : passStringToWasm0(start_iso, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
323
+ var len0 = WASM_VECTOR_LEN;
320
324
  const ptr1 = passStringToWasm0(rrule, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
321
325
  const len1 = WASM_VECTOR_LEN;
322
- const ret = wasm.rrule_expand(ptr0, len0, ptr1, len1, limit);
326
+ var ptr2 = isLikeNone(tzid) ? 0 : passStringToWasm0(tzid, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
327
+ var len2 = WASM_VECTOR_LEN;
328
+ const ret = wasm.rrule_expand(ptr0, len0, ptr1, len1, limit, ptr2, len2);
323
329
  if (ret[2]) {
324
330
  throw takeFromExternrefTable0(ret[1]);
325
331
  }
@@ -518,6 +524,10 @@ function handleError(f, args) {
518
524
  }
519
525
  }
520
526
 
527
+ function isLikeNone(x) {
528
+ return x === undefined || x === null;
529
+ }
530
+
521
531
  function passStringToWasm0(arg, malloc, realloc) {
522
532
  if (realloc === undefined) {
523
533
  const buf = cachedTextEncoder.encode(arg);
Binary file
@@ -12,8 +12,8 @@ export const format: (a: number, b: number, c: number, d: number) => [number, nu
12
12
  export const from_local: (a: number, b: number, c: number, d: number) => [number, number, number, number];
13
13
  export const parse_http: (a: number, b: number) => [number, number, number, number];
14
14
  export const parse_rfc2822: (a: number, b: number) => [number, number, number, number];
15
- export const parse_sql: (a: number, b: number) => [number, number, number, number];
16
- export const rrule_expand: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
15
+ export const parse_sql: (a: number, b: number, c: number, d: number) => [number, number, number, number];
16
+ export const rrule_expand: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
17
17
  export const start_of: (a: number, b: number, c: number, d: number) => [number, number, number, number];
18
18
  export const start_of_in_zone: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
19
19
  export const to_zone: (a: number, b: number, c: number, d: number) => [number, number, number];