@c9up/chronos 0.1.15 → 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 +1 -1
  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/Interval.ts CHANGED
@@ -8,7 +8,11 @@
8
8
  * @implements Story 36.9
9
9
  */
10
10
  import { type DateInput, DateTime, type DateUnit } from "./DateTime.js";
11
- import { Duration, type DurationUnit } from "./Duration.js";
11
+ import {
12
+ Duration,
13
+ type DurationObject,
14
+ type DurationUnit,
15
+ } from "./Duration.js";
12
16
 
13
17
  /**
14
18
  * Milliseconds in one unit, refusing a unit it does not know.
@@ -46,6 +50,17 @@ function msPerUnit(unit: string, caller: string): number {
46
50
  return ms;
47
51
  }
48
52
 
53
+ /** The `{ amount, unit }` shorthand as a Duration; anything else as given. */
54
+ function toDuration(
55
+ duration: Duration | DurationObject | { amount: number; unit: DateUnit },
56
+ ): Duration {
57
+ if (duration instanceof Duration) return duration;
58
+ if ("amount" in duration && "unit" in duration) {
59
+ return Duration.fromObject({ [`${duration.unit}s`]: duration.amount });
60
+ }
61
+ return Duration.fromObject(duration);
62
+ }
63
+
49
64
  export class Interval {
50
65
  readonly #start: DateTime;
51
66
  readonly #end: DateTime;
@@ -71,22 +86,51 @@ export class Interval {
71
86
  return new Interval(DateTime.from(start), DateTime.from(end));
72
87
  }
73
88
 
74
- /** Build from a start + duration forward. */
89
+ /**
90
+ * Build from a start and a duration forward, as Luxon does: the end is
91
+ * `start.plus(duration)`, calendar arithmetic in the start's zone — so
92
+ * January 31st plus one month ends on February 28th, not March 2nd.
93
+ */
75
94
  static after(
76
95
  start: DateInput,
77
- duration: Duration | { amount: number; unit: DateUnit },
96
+ duration: Duration | DurationObject | { amount: number; unit: DateUnit },
78
97
  ): Interval {
79
98
  const s = DateTime.from(start);
80
- // For Duration objects, convert to total milliseconds and add as ms —
81
- // NOT as seconds (which was the original bug: Duration.fromMillis(1500)
82
- // was being treated as 1500 seconds instead of 1.5 seconds).
83
- const e =
84
- "amount" in duration
85
- ? s.plus(duration.amount, duration.unit as DateUnit)
86
- : DateTime.fromMillis(
87
- s.toMillis() + Math.round(duration.as("milliseconds")),
88
- );
89
- return new Interval(s, e);
99
+ return new Interval(s, s.plus(toDuration(duration)));
100
+ }
101
+
102
+ /** The interval of `duration` ending at `end` (Luxon's `Interval.before`). */
103
+ static before(
104
+ end: DateInput,
105
+ duration: Duration | DurationObject | { amount: number; unit: DateUnit },
106
+ ): Interval {
107
+ const e = DateTime.from(end);
108
+ return new Interval(e.minus(toDuration(duration)), e);
109
+ }
110
+
111
+ /**
112
+ * Parse an ISO 8601 interval: `start/end`, `start/duration` or
113
+ * `duration/end` (Luxon's `Interval.fromISO`). Offset-less times are read in
114
+ * `options.zone` (UTC by default).
115
+ *
116
+ * @throws RangeError when neither half reads as a date.
117
+ */
118
+ static fromISO(text: string, options: { zone?: string } = {}): Interval {
119
+ const [s, e] = text.split("/", 2);
120
+ const read = (part: string | undefined): DateTime | undefined => {
121
+ if (!part) return undefined;
122
+ try {
123
+ return DateTime.fromISO(part, options);
124
+ } catch {
125
+ return undefined;
126
+ }
127
+ };
128
+ const start = read(s);
129
+ const end = read(e);
130
+ if (start && end) return new Interval(start, end);
131
+ if (start && e) return Interval.after(start, Duration.fromISO(e));
132
+ if (end && s) return Interval.before(end, Duration.fromISO(s));
133
+ throw new RangeError(`Invalid ISO 8601 interval: ${text}`);
90
134
  }
91
135
 
92
136
  // ─── Accessors ──────────────────────────────────────────
@@ -104,6 +148,20 @@ export class Interval {
104
148
  return ms / msPerUnit(unit, "Interval.length");
105
149
  }
106
150
 
151
+ /**
152
+ * How many `unit`s the interval touches, counting partial ones — a day
153
+ * starting at noon and ending the next noon touches two days (Luxon's
154
+ * `count`).
155
+ */
156
+ count(unit: DateUnit): number {
157
+ const start = this.#start.startOf(unit);
158
+ const end = this.#end.startOf(unit);
159
+ return (
160
+ Math.floor(end.diff(start, unit).as(unit)) +
161
+ (end.toMillis() !== this.#end.toMillis() ? 1 : 0)
162
+ );
163
+ }
164
+
107
165
  /** Duration object between start and end. */
108
166
  toDuration(): Duration {
109
167
  return Duration.fromMillis(this.#end.toMillis() - this.#start.toMillis());
@@ -162,55 +220,104 @@ export class Interval {
162
220
 
163
221
  /** The overlapping sub-interval, or `null` if disjoint. */
164
222
  intersection(other: Interval): Interval | null {
165
- const s = Math.max(this.#start.toMillis(), other.#start.toMillis());
166
- const e = Math.min(this.#end.toMillis(), other.#end.toMillis());
167
- if (s >= e) return null;
168
- return Interval.fromDateTimes(
169
- DateTime.fromMillis(s),
170
- DateTime.fromMillis(e),
223
+ const s = this.#start.isBefore(other.#start) ? other.#start : this.#start;
224
+ const e = this.#end.isAfter(other.#end) ? other.#end : this.#end;
225
+ if (!s.isBefore(e)) return null;
226
+ return new Interval(s, e);
227
+ }
228
+
229
+ /**
230
+ * The interval from the earlier start to the later end, gap included, as
231
+ * Luxon's `union`. Use {@link Interval.merge} to keep disjoint pieces apart.
232
+ */
233
+ union(other: Interval): Interval {
234
+ return new Interval(
235
+ other.#start.isBefore(this.#start) ? other.#start : this.#start,
236
+ other.#end.isAfter(this.#end) ? other.#end : this.#end,
171
237
  );
172
238
  }
173
239
 
174
- /** The smallest interval that covers both, or `null` if they don't overlap or abut. */
175
- union(other: Interval): Interval | null {
176
- if (
177
- !this.overlaps(other) &&
178
- !this.abutsStart(other) &&
179
- !this.abutsEnd(other)
180
- ) {
181
- return null;
182
- }
183
- return Interval.fromDateTimes(
184
- DateTime.fromMillis(
185
- Math.min(this.#start.toMillis(), other.#start.toMillis()),
186
- ),
187
- DateTime.fromMillis(
188
- Math.max(this.#end.toMillis(), other.#end.toMillis()),
189
- ),
240
+ /**
241
+ * The minimal set of intervals covering the same time: overlapping and
242
+ * abutting intervals are joined, disjoint ones kept, in ascending order.
243
+ */
244
+ static merge(intervals: readonly Interval[]): Interval[] {
245
+ const sorted = [...intervals].sort(
246
+ (a, b) => a.#start.toMillis() - b.#start.toMillis(),
190
247
  );
248
+ const out: Interval[] = [];
249
+ let current: Interval | undefined;
250
+ for (const item of sorted) {
251
+ if (current === undefined) {
252
+ current = item;
253
+ } else if (current.overlaps(item) || current.abutsStart(item)) {
254
+ current = current.union(item);
255
+ } else {
256
+ out.push(current);
257
+ current = item;
258
+ }
259
+ }
260
+ if (current !== undefined) out.push(current);
261
+ return out;
191
262
  }
192
263
 
193
- // ─── Split ──────────────────────────────────────────────
264
+ /**
265
+ * The time covered by exactly one of the intervals (Luxon's `Interval.xor`).
266
+ */
267
+ static xor(intervals: readonly Interval[]): Interval[] {
268
+ const edges = intervals
269
+ .flatMap((i) => [
270
+ { time: i.#start, start: true },
271
+ { time: i.#end, start: false },
272
+ ])
273
+ .sort((a, b) => a.time.toMillis() - b.time.toMillis());
274
+ let open: DateTime | undefined;
275
+ let depth = 0;
276
+ const results: Interval[] = [];
277
+ for (const edge of edges) {
278
+ depth += edge.start ? 1 : -1;
279
+ if (depth === 1) {
280
+ open = edge.time;
281
+ } else {
282
+ if (open && open.toMillis() !== edge.time.toMillis()) {
283
+ results.push(new Interval(open, edge.time));
284
+ }
285
+ open = undefined;
286
+ }
287
+ }
288
+ return Interval.merge(results);
289
+ }
194
290
 
195
- /** Split this interval into N sub-intervals of roughly equal `duration` length. */
196
- splitBy(duration: Duration | { amount: number; unit: DateUnit }): Interval[] {
197
- const stepMs =
198
- "amount" in duration
199
- ? duration.amount * msPerUnit(duration.unit, "Interval.splitBy")
200
- : duration.as("milliseconds");
201
- if (stepMs <= 0) throw new Error("splitBy duration must be positive");
291
+ /** The parts of this interval none of `intervals` covers (Luxon's `difference`). */
292
+ difference(...intervals: Interval[]): Interval[] {
293
+ return Interval.xor([this, ...intervals])
294
+ .map((i) => this.intersection(i))
295
+ .filter((i): i is Interval => i !== null && !i.isEmpty());
296
+ }
297
+
298
+ // ─── Split ──────────────────────────────────────────────
202
299
 
300
+ /**
301
+ * Split into consecutive pieces of `duration`, the last one shorter if it
302
+ * does not divide evenly. Each boundary is `start.plus(duration × n)`, as in
303
+ * Luxon, so months split on month boundaries and days on the zone's days.
304
+ */
305
+ splitBy(
306
+ duration: Duration | DurationObject | { amount: number; unit: DateUnit },
307
+ ): Interval[] {
308
+ if ("unit" in duration && !(duration instanceof Duration)) {
309
+ msPerUnit(duration.unit, "Interval.splitBy");
310
+ }
311
+ const step = toDuration(duration);
312
+ if (step.as("milliseconds") <= 0) {
313
+ throw new Error("splitBy duration must be positive");
314
+ }
203
315
  const result: Interval[] = [];
204
- let cursor = this.#start.toMillis();
205
- const endMs = this.#end.toMillis();
206
- while (cursor < endMs) {
207
- const next = Math.min(cursor + stepMs, endMs);
208
- result.push(
209
- Interval.fromDateTimes(
210
- DateTime.fromMillis(cursor),
211
- DateTime.fromMillis(next),
212
- ),
213
- );
316
+ let cursor = this.#start;
317
+ for (let n = 1; cursor.isBefore(this.#end); n++) {
318
+ const added = this.#start.plus(step.mapUnits((value) => value * n));
319
+ const next = added.isAfter(this.#end) ? this.#end : added;
320
+ result.push(new Interval(cursor, next));
214
321
  cursor = next;
215
322
  }
216
323
  return result;
package/src/atlas.ts CHANGED
@@ -44,8 +44,10 @@ import { DateTime } from "./DateTime.js";
44
44
  function isDateTimeLike(value: unknown): value is DateTime {
45
45
  if (value instanceof DateTime) return true;
46
46
  if (value === null || typeof value !== "object") return false;
47
- const obj = value as { toISO?: unknown; equals?: unknown };
48
- return typeof obj.toISO === "function" && typeof obj.equals === "function";
47
+ return (
48
+ typeof Reflect.get(value, "toISO") === "function" &&
49
+ typeof Reflect.get(value, "equals") === "function"
50
+ );
49
51
  }
50
52
 
51
53
  /**
@@ -68,20 +70,20 @@ function isDateTimeLike(value: unknown): value is DateTime {
68
70
  * string would otherwise silently land in the bind parameter and bypass the
69
71
  * chronos engine's normalization.
70
72
  *
71
- * **Round-trip canonicalization:** chronos's internal ISO normalization
72
- * collapses trailing `.000Z` to a bare `Z`. So
73
- * `prepare(consume('2026-04-30T12:00:00.000Z'))` returns
74
- * `'2026-04-30T12:00:00Z'` — same instant, compact form. Subsecond precision
75
- * with non-zero digits (e.g., `.123Z`) is preserved verbatim.
73
+ * **Round-trip canonicalization:** `prepare` writes the UTC ISO form with
74
+ * milliseconds always present, as Luxon's `toISO()` does, whatever the value's
75
+ * zone: `prepare(consume('2026-04-30T12:00:00.000Z'))` is
76
+ * `'2026-04-30T12:00:00.000Z'`, and a value in Europe/Paris is stored as the
77
+ * same UTC instant. Precision below the millisecond is not kept.
76
78
  *
77
79
  * **Driver expectations:** `timestamp` columns may come back from the driver
78
80
  * as either an ISO 8601 `string`, a JS `Date`, or (rarely) an integer epoch.
79
81
  * `node-postgres` returns `Date` for `timestamp` / `timestamptz` by default;
80
82
  * SQLite returns whatever the bound type was; configuring drivers to emit
81
- * ISO strings or `Date` is the supported path. Strings that are NOT parseable
82
- * ISO 8601 will surface a `RangeError: Invalid time value` from the
83
- * underlying `Date` constructor — align your DB column / driver settings with
84
- * ISO 8601 wire format.
83
+ * ISO strings or `Date` is the supported path. A string that is not ISO 8601
84
+ * (`YYYY-MM-DD[ HH:mm:ss[.SSS]][offset]`, `T` or space) is refused with a
85
+ * `RangeError` — align your DB column / driver settings with that wire format.
86
+ * Values outside years 0000-9999 are refused the same way.
85
87
  *
86
88
  * **Timezone handling — UTC-only:** chronos's internal storage is always UTC.
87
89
  * Consequences for this adapter:
@@ -95,12 +97,8 @@ function isDateTimeLike(value: unknown): value is DateTime {
95
97
  * fidelity matters — you will lose the offset on read and silently
96
98
  * rebase on write.
97
99
  * - Naive ISO (`'2026-04-30T12:00:00'` or SQLite-style
98
- * `'2026-04-30 12:00:00'`, no `Z`, no offset) → parsed by `new Date(...)`
99
- * in the JS runtime's **local** zone. This means the same DB row hydrates
100
- * differently across machines (CI host on UTC vs. dev laptop in
101
- * Europe/Zurich). Do **not** store naive timestamps in columns reaching
102
- * this adapter; configure your DB / driver to emit Z-suffixed strings or
103
- * `Date` instances, or pre-process via `DateTime.fromSQL`.
100
+ * `'2026-04-30 12:00:00'`, no `Z`, no offset) → read as UTC, on every
101
+ * host. Store UTC in such columns, or emit offset-bearing strings.
104
102
  *
105
103
  * **Auto-timestamps stack cleanly.** As of the atlas date-engine switch, atlas
106
104
  * hydrates every `@column.date()` / `@column.dateTime()` to a Chronos `DateTime`
@@ -148,6 +146,14 @@ export const dateTimeAtlasAdapter = Object.freeze({
148
146
  "Wrap the value with `new DateTime(...)` before assigning to a column tagged with this adapter.",
149
147
  );
150
148
  }
149
+ // The UTC form whatever the value's zone: `toISO()` writes a zoned value
150
+ // with its local offset (as Luxon does), and stored text has to sort and
151
+ // compare as one canonical instant.
152
+ const toUTC: unknown = Reflect.get(value, "toUTC");
153
+ if (typeof toUTC === "function") {
154
+ const utc: unknown = Reflect.apply(toUTC, value, []);
155
+ if (isDateTimeLike(utc)) return utc.toISO();
156
+ }
151
157
  return value.toISO();
152
158
  },
153
159
  });