@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/dist/DateTime.js CHANGED
@@ -1,3 +1,4 @@
1
+ var _a;
1
2
  /**
2
3
  * DateTime — immutable UTC datetime value object for the Ream framework.
3
4
  *
@@ -10,6 +11,8 @@
10
11
  *
11
12
  * @implements Epic 36 — Chronos
12
13
  */
14
+ import { Duration, } from "./Duration.js";
15
+ import { formatLuxon } from "./format.js";
13
16
  import { nativeChronos } from "./native.js";
14
17
  import { normalizeIso } from "./utils.js";
15
18
  // ─── Internal helpers ────────────────────────────────────────
@@ -52,51 +55,160 @@ function daysInMonthOf(year, month) {
52
55
  return daysPerMonthOf(year)[month - 1] ?? 31;
53
56
  }
54
57
  /**
55
- * Refuse a calendar date that does not exist, instead of sliding to the next
56
- * one that does.
57
- *
58
- * `new Date('2026-02-30')` answers 2026-03-02: the overflow semantics are right
59
- * for arithmetic — adding a month to January 31st has to land somewhere — and
60
- * wrong for reading input, where the same slide turns a typo into a fact. The
61
- * inconsistency was the dangerous part: '2026-13-45' threw while '2026-02-30'
62
- * came back as a date, so a caller wrapping this in try/catch had covered the
63
- * loud half and left the half that writes something false to the database.
58
+ * The only strings a `DateTime` reads: ISO 8601 calendar dates, optionally with
59
+ * a time (`T` or, as SQL writes it, a space) and an offset (`Z`, `±HH`,
60
+ * `±HHMM`, `±HH:MM`). Anything else is refused: V8's fallback parser turns
61
+ * `"1"` or `"foo 2026"` into a date, and reads an offset-less time in the
62
+ * HOST zone, so the same text named a different instant on every machine.
63
+ */
64
+ const ISO_8601 = /^(\d{4})-(\d{2})-(\d{2})(?:[Tt ](\d{2}):(\d{2})(?::(\d{2})(?:[.,](\d{1,9}))?)?(?:\s?([Zz])|\s?([+-])(\d{2})(?::?(\d{2}))?)?)?$/;
65
+ /** First and last instants a value may hold: what a four-digit ISO year writes. */
66
+ const MIN_MS = -62_167_219_200_000; // 0000-01-01T00:00:00.000Z
67
+ const MAX_MS = 253_402_300_799_999; // 9999-12-31T23:59:59.999Z
68
+ /**
69
+ * Refuse a wall-clock value that does not exist, instead of sliding to the
70
+ * next one that does.
64
71
  *
65
- * `fromObject` has always refused the same input; this is that check on the
66
- * door that was missing it. Only the written date is examined, never the
67
- * instant it resolves to, so an offset that legitimately moves the UTC day
68
- * ('2026-08-10T23:00:00-05:00' → the 11th) is untouched.
72
+ * `new Date('2026-02-30')` answers 2026-03-02 and `Date.UTC(…, 10, 90)` reads
73
+ * minute 90 as 11:30: the overflow semantics are right for arithmetic — adding
74
+ * a month to January 31st has to land somewhere — and wrong for reading input,
75
+ * where the same slide turns a typo into a fact. Only the written value is
76
+ * examined, never the instant it resolves to, so an offset that legitimately
77
+ * moves the UTC day ('2026-08-10T23:00:00-05:00' → the 11th) is untouched.
69
78
  */
70
- const CALENDAR_DATE = /^(\d{4})-(\d{2})-(\d{2})(?=$|[T ])/;
71
- function assertCalendarDateExists(raw) {
72
- const match = CALENDAR_DATE.exec(raw);
73
- // Anything else — RFC 2822, a bare year, a basic-format string — is left to
74
- // `Date`, which already refuses what it cannot read.
75
- if (!match)
76
- return;
77
- const year = Number(match[1]);
78
- const month = Number(match[2]);
79
- const day = Number(match[3]);
80
- if (month < 1 || month > 12) {
81
- throw new Error(`Invalid date '${raw}': there is no month ${month}.`);
79
+ function assertWallClock(c, raw) {
80
+ const integer = (unit, value, min, max) => {
81
+ if (!Number.isInteger(value) || value < min || value > max) {
82
+ throw new RangeError(`Invalid date '${raw}': ${unit} ${String(value)} is out of range (${min}-${max}).`);
83
+ }
84
+ };
85
+ integer("year", c.year, 0, 9999);
86
+ if (!Number.isInteger(c.month) || c.month < 1 || c.month > 12) {
87
+ throw new RangeError(`Invalid date '${raw}': there is no month ${String(c.month)}.`);
88
+ }
89
+ const lastDay = daysInMonthOf(c.year, c.month);
90
+ if (!Number.isInteger(c.day) || c.day < 1 || c.day > lastDay) {
91
+ throw new RangeError(`Invalid date '${raw}': ${MONTH_NAMES[c.month - 1]} ${c.year} has ${lastDay} days, so there is no day ${String(c.day)}.`);
92
+ }
93
+ integer("hour", c.hour, 0, 23);
94
+ integer("minute", c.minute, 0, 59);
95
+ integer("second", c.second, 0, 59);
96
+ integer("millisecond", c.millisecond, 0, 999);
97
+ }
98
+ /** Epoch milliseconds of a UTC wall clock; years 0-99 stay literal (Date.UTC maps them to 19xx). */
99
+ function utcMs(c) {
100
+ const d = new Date(0);
101
+ d.setUTCFullYear(c.year, c.month - 1, c.day);
102
+ d.setUTCHours(c.hour, c.minute, c.second, c.millisecond);
103
+ return d.getTime();
104
+ }
105
+ const pad = (n, width = 2) => String(n).padStart(width, "0");
106
+ /** Epoch milliseconds of a wall clock read in `zone`. */
107
+ function wallClockMs(c, zone) {
108
+ if (zone === "UTC")
109
+ return utcMs(c);
110
+ const naive = `${pad(c.year, 4)}-${pad(c.month)}-${pad(c.day)}T${pad(c.hour)}:${pad(c.minute)}:${pad(c.second)}`;
111
+ return Date.parse(nativeChronos().fromLocal(naive, zone)) + c.millisecond;
112
+ }
113
+ /** The canonical UTC ISO string of an instant, refusing what chronos cannot hold. */
114
+ function isoOfMs(ms, input) {
115
+ if (!Number.isFinite(ms))
116
+ throw new RangeError(`Invalid date ${input()}`);
117
+ if (ms < MIN_MS || ms > MAX_MS) {
118
+ throw new RangeError(`Date ${input()} is out of range: years are limited to 0000-9999.`);
119
+ }
120
+ return new Date(ms).toISOString();
121
+ }
122
+ /** Read an ISO 8601 string; an offset-less one is a wall clock in `zone`. */
123
+ function parseIso(raw, zone) {
124
+ const m = ISO_8601.exec(raw);
125
+ if (!m) {
126
+ throw new RangeError(`Invalid date '${raw}': expected ISO 8601 (YYYY-MM-DD, optionally with THH:mm[:ss[.SSS]] and an offset).`);
127
+ }
128
+ const c = {
129
+ year: Number(m[1]),
130
+ month: Number(m[2]),
131
+ day: Number(m[3]),
132
+ hour: Number(m[4] ?? 0),
133
+ minute: Number(m[5] ?? 0),
134
+ second: Number(m[6] ?? 0),
135
+ millisecond: Math.floor(Number(`0.${m[7] ?? "0"}`) * 1000),
136
+ };
137
+ assertWallClock(c, raw);
138
+ let ms;
139
+ if (m[8] !== undefined) {
140
+ ms = utcMs(c);
141
+ }
142
+ else if (m[9] !== undefined) {
143
+ const hours = Number(m[10]);
144
+ const minutes = Number(m[11] ?? 0);
145
+ if (hours > 23 || minutes > 59) {
146
+ throw new RangeError(`Invalid date '${raw}': the offset is out of range.`);
147
+ }
148
+ const sign = m[9] === "-" ? -1 : 1;
149
+ ms = utcMs(c) - sign * (hours * 60 + minutes) * 60_000;
82
150
  }
83
- const lastDay = daysInMonthOf(year, month);
84
- if (day < 1 || day > lastDay) {
85
- throw new Error(`Invalid date '${raw}': ${MONTH_NAMES[month - 1]} ${year} has ${lastDay} days, so there is no day ${day}.`);
151
+ else {
152
+ ms = wallClockMs(c, zone);
86
153
  }
154
+ return isoOfMs(ms, () => `'${raw}'`);
87
155
  }
88
- function toIso(value) {
156
+ function toIso(value, zone = "UTC") {
89
157
  if (value instanceof DateTime)
90
158
  return value.toISO();
91
- if (value instanceof Date)
92
- return normalizeIso(value.toISOString());
93
- if (typeof value === "string")
94
- assertCalendarDateExists(value);
95
- return normalizeIso(new Date(value).toISOString());
159
+ if (value instanceof Date) {
160
+ return normalizeIso(isoOfMs(value.getTime(), () => "(JS Date)"));
161
+ }
162
+ if (typeof value !== "string") {
163
+ throw new TypeError(`Invalid date input: expected a string, a Date or a DateTime, got ${typeof value}`);
164
+ }
165
+ return normalizeIso(parseIso(value, zone));
96
166
  }
97
167
  function toMs(value) {
98
168
  return new Date(toIso(value)).getTime();
99
169
  }
170
+ const CASUAL_UNIT_MS = {
171
+ second: 1_000,
172
+ minute: 60_000,
173
+ hour: 3_600_000,
174
+ day: 86_400_000,
175
+ week: 604_800_000,
176
+ month: 30 * 86_400_000,
177
+ year: 365 * 86_400_000,
178
+ };
179
+ /** Milliseconds in one unit on Luxon's casual matrix; throws on an unknown unit. */
180
+ function casualUnitMs(unit) {
181
+ const singular = unit.endsWith("s") ? unit.slice(0, -1) : unit;
182
+ const ms = Object.hasOwn(CASUAL_UNIT_MS, singular)
183
+ ? CASUAL_UNIT_MS[singular]
184
+ : undefined;
185
+ if (ms === undefined)
186
+ throw new Error(`Unsupported unit: ${unit}`);
187
+ return ms;
188
+ }
189
+ const DIFF_ORDER = [
190
+ "years",
191
+ "months",
192
+ "weeks",
193
+ "days",
194
+ "hours",
195
+ "minutes",
196
+ "seconds",
197
+ "milliseconds",
198
+ ];
199
+ const CALENDAR_UNITS = new Set([
200
+ "years",
201
+ "months",
202
+ "weeks",
203
+ "days",
204
+ ]);
205
+ function durationUnitOf(unit) {
206
+ const plural = unit.endsWith("s") ? unit : `${unit}s`;
207
+ const found = DIFF_ORDER.find((u) => u === plural);
208
+ if (found === undefined)
209
+ throw new RangeError(`Unsupported unit: ${unit}`);
210
+ return found;
211
+ }
100
212
  function isCalendarUnit(unit) {
101
213
  return (unit === "day" || unit === "week" || unit === "month" || unit === "year");
102
214
  }
@@ -250,55 +362,139 @@ function rangesOverlap(a, b, opt = {}) {
250
362
  ? Math.max(na.start, nb.start) <= Math.min(na.end, nb.end)
251
363
  : Math.max(na.start, nb.start) < Math.min(na.end, nb.end);
252
364
  }
365
+ // ─── Zone validation ─────────────────────────────────────────
366
+ /**
367
+ * Zones the engine has already accepted, exactly as it names them.
368
+ *
369
+ * Every derived value (`plus`, `startOf`, …) is built through the constructor
370
+ * with the zone of the value it came from, so without this each one would pay
371
+ * a native call to re-validate a zone that was checked on the way in. Only a
372
+ * name equal to the engine's canonical spelling is remembered: the set is then
373
+ * bounded by the tz database, whatever spellings a caller sends.
374
+ */
375
+ const acceptedZones = new Set(["UTC"]);
376
+ /**
377
+ * Throw on a zone the tz database does not know — the one check behind every
378
+ * entry that takes a zone (`new DateTime(input, zone)`, `DateTime.now(zone)`,
379
+ * `setZone`), so all three refuse the same names with the same message.
380
+ */
381
+ function assertZone(zone) {
382
+ if (acceptedZones.has(zone))
383
+ return;
384
+ const canonical = nativeChronos().validateTimezone(zone);
385
+ if (canonical === zone)
386
+ acceptedZones.add(zone);
387
+ }
253
388
  // ─── DateTime class ──────────────────────────────────────────
254
389
  export class DateTime {
255
390
  #iso;
256
391
  #zone;
392
+ /** Locale for names in `toFormat` and for `toLocaleString`; en-US unless set. */
393
+ #locale = "en-US";
394
+ /**
395
+ * @throws on a zone the tz database does not know. An unknown zone used to
396
+ * be stored as given and break later, on the first offset or format.
397
+ */
257
398
  constructor(input = new Date(), zone = "UTC") {
258
- this.#iso = toIso(input);
399
+ assertZone(zone);
400
+ this.#iso = toIso(input, zone);
259
401
  this.#zone = zone;
260
402
  }
261
403
  static from(input) {
262
- if (input instanceof DateTime)
263
- return new DateTime(input.#iso, input.#zone);
264
- return new DateTime(toIso(input));
404
+ if (input instanceof _a)
405
+ return input.#derive(input.#iso);
406
+ return new _a(toIso(input));
407
+ }
408
+ /** A value derived from this one: same zone (unless given) and locale. */
409
+ #derive(input, zone = this.#zone) {
410
+ const out = new _a(input, zone);
411
+ out.#locale = this.#locale;
412
+ return out;
413
+ }
414
+ /** Now, or the given wall clock, in the host's zone (Luxon's `DateTime.local`). */
415
+ static local(year, month = 1, day = 1, hour = 0, minute = 0, second = 0, millisecond = 0) {
416
+ const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
417
+ if (year === undefined)
418
+ return _a.now(zone);
419
+ return _a.fromObject({ year, month, day, hour, minute, second, millisecond }, { zone });
420
+ }
421
+ /** Now, or the given wall clock, in UTC (Luxon's `DateTime.utc`). */
422
+ static utc(year, month = 1, day = 1, hour = 0, minute = 0, second = 0, millisecond = 0) {
423
+ if (year === undefined)
424
+ return _a.now();
425
+ return _a.fromObject({
426
+ year,
427
+ month,
428
+ day,
429
+ hour,
430
+ minute,
431
+ second,
432
+ millisecond,
433
+ });
265
434
  }
266
435
  static now(zone) {
267
- return new DateTime(new Date(), zone ?? "UTC");
436
+ return new _a(new Date(), zone ?? "UTC");
268
437
  }
269
438
  static fromMillis(ms) {
270
- return new DateTime(new Date(ms));
439
+ if (typeof ms !== "number") {
440
+ throw new TypeError(`fromMillis expects a number, got ${typeof ms}`);
441
+ }
442
+ return new _a(new Date(ms));
271
443
  }
272
444
  static fromSeconds(seconds) {
273
- return new DateTime(new Date(seconds * 1000));
445
+ return new _a(new Date(seconds * 1000));
274
446
  }
275
447
  static fromUnix(seconds) {
276
- return DateTime.fromSeconds(seconds);
448
+ return _a.fromSeconds(seconds);
277
449
  }
278
450
  static fromJSDate(date) {
279
451
  if (!Number.isFinite(date.getTime()))
280
452
  throw new Error("Invalid Date");
281
- return new DateTime(date);
282
- }
283
- static fromObject(obj) {
284
- if (obj.month < 1 || obj.month > 12)
285
- throw new Error(`Invalid month: ${obj.month}`);
286
- if (obj.day < 1 || obj.day > 31)
287
- throw new Error(`Invalid day: ${obj.day}`);
288
- const d = new Date(Date.UTC(obj.year, obj.month - 1, obj.day, obj.hour ?? 0, obj.minute ?? 0, obj.second ?? 0, obj.ms ?? 0));
289
- if (d.getUTCMonth() !== obj.month - 1 || d.getUTCDate() !== obj.day) {
290
- throw new Error(`Invalid date object: ${JSON.stringify(obj)}`);
291
- }
292
- return new DateTime(d);
453
+ return new _a(date);
454
+ }
455
+ /**
456
+ * Read an ISO 8601 string. An offset-less one is a wall clock in
457
+ * `options.zone` (UTC by default), and the result is in that zone.
458
+ */
459
+ static fromISO(text, options = {}) {
460
+ return new _a(text, options.zone ?? "UTC");
461
+ }
462
+ /**
463
+ * Build from calendar fields, read as a wall clock in `options.zone` (UTC by
464
+ * default). Every field is checked: an integer within its range (minute
465
+ * 0-59, …), and a year read literally (50 is year 0050, not 1950).
466
+ */
467
+ static fromObject(obj, options = {}) {
468
+ const zone = options.zone ?? "UTC";
469
+ assertZone(zone);
470
+ const c = {
471
+ year: obj.year,
472
+ month: obj.month,
473
+ day: obj.day,
474
+ hour: obj.hour ?? 0,
475
+ minute: obj.minute ?? 0,
476
+ second: obj.second ?? 0,
477
+ millisecond: obj.millisecond ?? obj.ms ?? 0,
478
+ };
479
+ assertWallClock(c, JSON.stringify(obj));
480
+ return new _a(isoOfMs(wallClockMs(c, zone), () => JSON.stringify(obj)), zone);
293
481
  }
294
482
  static fromRFC2822(input) {
295
- return new DateTime(nativeChronos().parseRfc2822(input));
483
+ return new _a(nativeChronos().parseRfc2822(input));
296
484
  }
297
- static fromSQL(input) {
298
- return new DateTime(nativeChronos().parseSql(input));
485
+ /**
486
+ * Read a SQL literal: `YYYY-MM-DD`, or `YYYY-MM-DD HH:mm[:ss[.fff]]` with an
487
+ * optional offset (`+00`, `+02:00` — PostgreSQL's `timestamptz` text) or
488
+ * IANA zone. Without one, the value is a wall clock in `options.zone` (UTC
489
+ * by default), and the result is in that zone.
490
+ */
491
+ static fromSQL(input, options = {}) {
492
+ const zone = options.zone ?? "UTC";
493
+ assertZone(zone);
494
+ return new _a(nativeChronos().parseSql(input, zone === "UTC" ? undefined : zone), zone);
299
495
  }
300
496
  static fromHTTP(input) {
301
- return new DateTime(nativeChronos().parseHttp(input));
497
+ return new _a(nativeChronos().parseHttp(input));
302
498
  }
303
499
  // ─── Timezone ───────────────────────────────────────────
304
500
  get zoneName() {
@@ -309,38 +505,192 @@ export class DateTime {
309
505
  return 0;
310
506
  return nativeChronos().zoneOffset(this.#iso, this.#zone);
311
507
  }
312
- setZone(zone) {
313
- nativeChronos().validateTimezone(zone);
314
- return new DateTime(this.#iso, zone);
508
+ /**
509
+ * The same instant in another zone, or — with `keepLocalTime` — the same
510
+ * wall clock in another zone (a different instant), as Luxon's `setZone`.
511
+ */
512
+ setZone(zone, options = {}) {
513
+ assertZone(zone);
514
+ if (!options.keepLocalTime)
515
+ return this.#derive(this.#iso, zone);
516
+ return this.#derive(new Date(wallClockMs(this.calendar, zone)), zone);
315
517
  }
316
518
  toUTC() {
317
- return new DateTime(this.#iso, "UTC");
519
+ return this.#derive(this.#iso, "UTC");
520
+ }
521
+ get locale() {
522
+ return this.#locale;
523
+ }
524
+ /** A copy whose names (`toFormat`) and `toLocaleString` default use `locale`. */
525
+ setLocale(locale) {
526
+ const [canonical] = Intl.getCanonicalLocales(locale);
527
+ if (canonical === undefined)
528
+ throw new RangeError(`Invalid locale: ${locale}`);
529
+ const out = this.#derive(this.#iso);
530
+ out.#locale = canonical;
531
+ return out;
532
+ }
533
+ /** Always true: chronos refuses invalid input instead of building an invalid value. */
534
+ get isValid() {
535
+ return true;
536
+ }
537
+ /**
538
+ * A copy with some calendar fields replaced, read on this value's wall
539
+ * clock (Luxon's `set`). Changing the month keeps the day within it unless
540
+ * the day is given too.
541
+ *
542
+ * @throws RangeError on a field out of range.
543
+ */
544
+ set(values) {
545
+ const c = this.calendar;
546
+ const mixed = {
547
+ year: values.year ?? c.year,
548
+ month: values.month ?? c.month,
549
+ day: values.day ?? c.day,
550
+ hour: values.hour ?? c.hour,
551
+ minute: values.minute ?? c.minute,
552
+ second: values.second ?? c.second,
553
+ millisecond: values.millisecond ?? c.millisecond,
554
+ };
555
+ if (values.day === undefined &&
556
+ Number.isInteger(mixed.month) &&
557
+ mixed.month >= 1 &&
558
+ mixed.month <= 12) {
559
+ mixed.day = Math.min(mixed.day, daysInMonthOf(mixed.year, mixed.month));
560
+ }
561
+ assertWallClock(mixed, JSON.stringify(values));
562
+ return this.#derive(new Date(wallClockMs(mixed, this.#zone)));
318
563
  }
319
564
  toZonedISO() {
320
565
  if (this.#zone === "UTC")
321
566
  return this.#iso;
322
567
  return nativeChronos().toZone(this.#iso, this.#zone).iso;
323
568
  }
324
- // ─── Arithmetic ─────────────────────────────────────────
325
- plus(amount, unit) {
569
+ plus(amountOrDuration, unit) {
570
+ if (typeof amountOrDuration === "object" && amountOrDuration !== null) {
571
+ return this.#plusDuration(amountOrDuration instanceof Duration
572
+ ? amountOrDuration
573
+ : Duration.fromObject(amountOrDuration));
574
+ }
575
+ if (unit === undefined) {
576
+ throw new TypeError("plus(amount, unit) needs a unit");
577
+ }
578
+ return this.#plusUnit(amountOrDuration, unit);
579
+ }
580
+ #plusDuration(duration) {
581
+ const v = duration.toObject();
582
+ const months = Math.trunc(v.years) * 12 + Math.trunc(v.months);
583
+ const days = Math.trunc(v.weeks) * 7 + Math.trunc(v.days);
584
+ const elapsed = Duration.fromObject({
585
+ years: v.years - Math.trunc(v.years),
586
+ months: v.months - Math.trunc(v.months),
587
+ weeks: v.weeks - Math.trunc(v.weeks),
588
+ days: v.days - Math.trunc(v.days),
589
+ hours: v.hours,
590
+ minutes: v.minutes,
591
+ seconds: v.seconds,
592
+ milliseconds: v.milliseconds,
593
+ }).as("milliseconds");
594
+ let out = this.#plusUnit(months, "month");
595
+ if (days !== 0)
596
+ out = out.#plusUnit(days, "day");
597
+ if (elapsed === 0)
598
+ return out;
599
+ return this.#derive(new Date(out.toMillis() + Math.round(elapsed)));
600
+ }
601
+ #plusUnit(amount, unit) {
602
+ if (typeof amount !== "number" || !Number.isFinite(amount)) {
603
+ throw new RangeError(`Invalid unit value ${String(amount)}: plus/minus take a finite number`);
604
+ }
605
+ const unitMs = casualUnitMs(unit);
606
+ const whole = Math.trunc(amount);
607
+ if (!Number.isSafeInteger(whole)) {
608
+ throw new RangeError(`plus(${amount}, '${unit}') is out of range: years are limited to 0000-9999`);
609
+ }
326
610
  const n = nativeChronos();
327
- const out = this.#zone !== "UTC" && isCalendarUnit(unit)
328
- ? n.addInZone(this.#iso, amount, unit, this.#zone)
329
- : n.add(this.#iso, amount, unit);
330
- return new DateTime(out, this.#zone);
611
+ const shifted = whole === 0
612
+ ? this.#iso
613
+ : this.#zone !== "UTC" && isCalendarUnit(unit)
614
+ ? n.addInZone(this.#iso, whole, unit, this.#zone)
615
+ : n.add(this.#iso, whole, unit);
616
+ const fraction = amount - whole;
617
+ if (fraction === 0)
618
+ return this.#derive(shifted);
619
+ return this.#derive(new Date(Date.parse(shifted) + Math.round(fraction * unitMs)));
620
+ }
621
+ minus(amountOrDuration, unit) {
622
+ if (typeof amountOrDuration === "object" && amountOrDuration !== null) {
623
+ const duration = amountOrDuration instanceof Duration
624
+ ? amountOrDuration
625
+ : Duration.fromObject(amountOrDuration);
626
+ return this.#plusDuration(duration.negate());
627
+ }
628
+ if (unit === undefined) {
629
+ throw new TypeError("minus(amount, unit) needs a unit");
630
+ }
631
+ // Checked before negating: `-"1"` would turn a string into a number.
632
+ if (typeof amountOrDuration !== "number") {
633
+ throw new RangeError(`Invalid unit value ${String(amountOrDuration)}: plus/minus take a finite number`);
634
+ }
635
+ return this.#plusUnit(-amountOrDuration, unit);
331
636
  }
332
- minus(amount, unit) {
333
- return this.plus(-amount, unit);
637
+ /**
638
+ * `this - other` as a Duration in the given unit(s), as Luxon's `diff`:
639
+ * calendar units are counted on this value's calendar (a day across a DST
640
+ * change is one day), the lowest unit keeps its fraction, and clock units
641
+ * take what is left. `.as(unit)` reads it as a number.
642
+ */
643
+ diff(other, unit = "milliseconds") {
644
+ const units = (Array.isArray(unit) ? unit : [unit]).map(durationUnitOf);
645
+ const ordered = DIFF_ORDER.filter((u) => units.includes(u));
646
+ if (ordered.length === 0)
647
+ throw new RangeError("diff needs a unit");
648
+ const o = _a.from(other).setZone(this.#zone);
649
+ const thisIsLater = this.toMillis() >= o.toMillis();
650
+ const earlier = thisIsLater ? o : this;
651
+ const later = thisIsLater ? this : o;
652
+ const calendar = ordered.filter((u) => CALENDAR_UNITS.has(u));
653
+ const clock = ordered.filter((u) => !CALENDAR_UNITS.has(u));
654
+ const results = {};
655
+ let cursor = earlier;
656
+ for (const u of calendar) {
657
+ results[u] = Math.trunc(later.#diffNumber(cursor, u));
658
+ cursor = earlier.plus(results);
659
+ }
660
+ let out;
661
+ const lowest = calendar.at(-1);
662
+ if (clock.length === 0 && lowest !== undefined) {
663
+ results[lowest] =
664
+ (results[lowest] ?? 0) + later.#diffNumber(cursor, lowest);
665
+ out = Duration.fromObject(results);
666
+ }
667
+ else {
668
+ out = Duration.fromMillis(later.toMillis() - cursor.toMillis())
669
+ .shiftTo(...clock)
670
+ .plus(results);
671
+ }
672
+ return thisIsLater ? out : out.negate();
334
673
  }
335
- diff(other, unit) {
674
+ /** `this - other` in one unit, as a fractional number (calendar-aware). */
675
+ #diffNumber(other, unit) {
336
676
  const n = nativeChronos();
337
- const otherIso = toIso(other);
338
- return this.#zone !== "UTC" && (unit === "month" || unit === "year")
339
- ? n.diffInZone(this.#iso, otherIso, unit, this.#zone)
340
- : n.diff(this.#iso, otherIso, unit);
677
+ const singular = unit.slice(0, -1);
678
+ return CALENDAR_UNITS.has(unit)
679
+ ? n.diffInZone(this.#iso, other.#iso, singular, this.#zone)
680
+ : n.diff(this.#iso, other.#iso, unit);
341
681
  }
342
682
  // ─── Comparison ─────────────────────────────────────────
683
+ /**
684
+ * Same instant — and, against another DateTime, same zone and locale, as
685
+ * Luxon's `equals`. Compare `toMillis()` (or use `<`, `>`) for the instant
686
+ * alone.
687
+ */
343
688
  equals(other) {
689
+ if (other instanceof _a) {
690
+ return (this.#iso === other.#iso &&
691
+ this.#zone === other.#zone &&
692
+ this.#locale === other.#locale);
693
+ }
344
694
  return this.#iso === toIso(other);
345
695
  }
346
696
  isBefore(other) {
@@ -349,8 +699,10 @@ export class DateTime {
349
699
  isAfter(other) {
350
700
  return toMs(this) > toMs(other);
351
701
  }
702
+ /** Whether `other` falls in the same `unit` as this value, on this value's calendar. */
352
703
  hasSame(other, unit) {
353
- return (this.startOf(unit).toISO() === DateTime.from(other).startOf(unit).toISO());
704
+ const o = _a.from(other).setZone(this.#zone);
705
+ return this.startOf(unit).toMillis() === o.startOf(unit).toMillis();
354
706
  }
355
707
  isSameDay(other) {
356
708
  return this.hasSame(other, "day");
@@ -366,54 +718,118 @@ export class DateTime {
366
718
  */
367
719
  startOf(unit) {
368
720
  const n = nativeChronos();
369
- return new DateTime(this.#zone === "UTC"
721
+ return this.#derive(this.#zone === "UTC"
370
722
  ? n.startOf(this.#iso, unit)
371
- : n.startOfInZone(this.#iso, unit, this.#zone), this.#zone);
723
+ : n.startOfInZone(this.#iso, unit, this.#zone));
372
724
  }
373
725
  /** The last instant of `unit` — see {@link startOf} on the shared routine. */
374
726
  endOf(unit) {
375
727
  const n = nativeChronos();
376
- return new DateTime(this.#zone === "UTC"
728
+ return this.#derive(this.#zone === "UTC"
377
729
  ? n.endOf(this.#iso, unit)
378
- : n.endOfInZone(this.#iso, unit, this.#zone), this.#zone);
730
+ : n.endOfInZone(this.#iso, unit, this.#zone));
379
731
  }
380
732
  // ─── Range ──────────────────────────────────────────────
381
733
  isWithin(range, options = {}) {
382
734
  return rangeContains(range, { start: this.#iso, end: this.#iso }, options);
383
735
  }
384
736
  // ─── Formatting ─────────────────────────────────────────
737
+ /**
738
+ * Format with chronos's moment-style tokens (`YYYY`, `YY`, `MM`, `DD`,
739
+ * `HH`, `mm`, `ss`, `Z`; `[text]` is literal) on this value's wall clock.
740
+ * Luxon's tokens (`yyyy`, `dd`, `LLL`, …) are {@link toFormat}.
741
+ */
385
742
  format(pattern = "YYYY-MM-DD HH:mm:ss") {
386
743
  if (this.#zone !== "UTC") {
387
744
  return formatFromIsoString(nativeChronos().toZone(this.#iso, this.#zone).iso, pattern);
388
745
  }
389
746
  return nativeChronos().format(this.#iso, pattern);
390
747
  }
748
+ /**
749
+ * Format with Luxon's tokens (`yyyy-MM-dd HH:mm`, `dd LLL yyyy`, `EEEE`,
750
+ * `ZZ`, macros such as `DD` or `t`; `'quoted'` text is literal), on this
751
+ * value's wall clock. {@link format} keeps chronos's moment-style tokens.
752
+ */
753
+ toFormat(pattern) {
754
+ return this.#luxonFormat(pattern, false);
755
+ }
756
+ /** `allowZ`: a UTC value writes its offset as `Z` (ISO and SQL output). */
757
+ #luxonFormat(pattern, allowZ = true) {
758
+ return formatLuxon(pattern, {
759
+ parts: this.calendar,
760
+ ts: this.toMillis(),
761
+ offset: this.offset,
762
+ zone: this.#zone,
763
+ locale: this.#locale,
764
+ allowZ: allowZ && this.#zone === "UTC",
765
+ });
766
+ }
391
767
  toDate() {
392
768
  return new Date(this.#iso);
393
769
  }
394
- toISO() {
395
- return this.#iso;
770
+ /**
771
+ * ISO 8601 on this value's wall clock, as Luxon's `toISO`: `…Z` in UTC,
772
+ * the local offset (`2026-08-10T12:00:00.000+02:00`) in any other zone —
773
+ * the same instant either way.
774
+ */
775
+ toISO(options = {}) {
776
+ const plain = options.suppressMilliseconds !== true && options.includeOffset !== false;
777
+ if (this.#zone === "UTC" && plain)
778
+ return this.#iso;
779
+ return this.#luxonFormat(`yyyy-MM-dd'T'${this.#timeFormat(options)}`);
780
+ }
781
+ #timeFormat(options) {
782
+ const ms = options.suppressMilliseconds === true && this.millisecond === 0
783
+ ? ""
784
+ : ".SSS";
785
+ return `HH:mm:ss${ms}${options.includeOffset === false ? "" : "ZZ"}`;
786
+ }
787
+ /** `yyyy-MM-dd` on this value's calendar. */
788
+ toISODate() {
789
+ return this.#luxonFormat("yyyy-MM-dd");
790
+ }
791
+ /** `HH:mm:ss.SSS` plus the offset, on this value's wall clock. */
792
+ toISOTime(options = {}) {
793
+ return this.#luxonFormat(this.#timeFormat(options));
794
+ }
795
+ /** `yyyy-MM-dd`, as SQL writes a date. */
796
+ toSQLDate() {
797
+ return this.toISODate();
798
+ }
799
+ /** `HH:mm:ss.SSS +02:00` (`Z` in UTC), as Luxon's `toSQLTime`. */
800
+ toSQLTime(options = {}) {
801
+ return this.#luxonFormat(options.includeOffset === false ? "HH:mm:ss.SSS" : "HH:mm:ss.SSS ZZ");
802
+ }
803
+ /** `yyyy-MM-dd HH:mm:ss.SSS +02:00`, as Luxon's `toSQL`. */
804
+ toSQL(options = {}) {
805
+ return `${this.toSQLDate()} ${this.toSQLTime(options)}`;
396
806
  }
397
807
  toString() {
398
- return this.#iso;
808
+ return this.toISO();
399
809
  }
400
810
  toJSON() {
401
- return this.#iso;
811
+ return this.toISO();
402
812
  }
403
813
  toMillis() {
404
814
  return new Date(this.#iso).getTime();
405
815
  }
816
+ /** Epoch milliseconds, so `a < b` and `a - b` work as with Luxon. */
817
+ valueOf() {
818
+ return this.toMillis();
819
+ }
406
820
  toSeconds() {
407
821
  return Math.floor(this.toMillis() / 1000);
408
822
  }
409
823
  toLocaleString(locale, options) {
410
- return new Intl.DateTimeFormat(locale, {
411
- ...(this.#zone !== "UTC" ? { timeZone: this.#zone } : {}),
824
+ // The value's own zone, UTC included: without it Intl falls back to the
825
+ // host's zone and the same value prints differently per machine.
826
+ return new Intl.DateTimeFormat(locale ?? this.#locale, {
827
+ timeZone: this.#zone,
412
828
  ...options,
413
829
  }).format(this.toDate());
414
830
  }
415
831
  toRelative(options) {
416
- const base = options?.base ? DateTime.from(options.base) : new DateTime();
832
+ const base = options?.base ? _a.from(options.base) : new _a();
417
833
  const diffMs = this.toMillis() - base.toMillis();
418
834
  const abs = Math.abs(diffMs);
419
835
  let unit;
@@ -499,6 +915,7 @@ export class DateTime {
499
915
  return this.calendar.millisecond;
500
916
  }
501
917
  }
918
+ _a = DateTime;
502
919
  // ─── Standalone range helpers ────────────────────────────────
503
920
  export function inRange(input, range, options = {}) {
504
921
  return DateTime.from(input).isWithin(range, options);