@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.
- package/README.md +63 -16
- package/dist/DateTime.d.ts +145 -4
- package/dist/DateTime.d.ts.map +1 -1
- package/dist/DateTime.js +504 -87
- package/dist/DateTime.js.map +1 -1
- package/dist/Duration.d.ts +37 -20
- package/dist/Duration.d.ts.map +1 -1
- package/dist/Duration.js +287 -120
- package/dist/Duration.js.map +1 -1
- package/dist/Interval.d.ts +50 -7
- package/dist/Interval.d.ts.map +1 -1
- package/dist/Interval.js +142 -29
- package/dist/Interval.js.map +1 -1
- package/dist/atlas.d.ts +11 -15
- package/dist/atlas.d.ts.map +1 -1
- package/dist/atlas.js +22 -17
- package/dist/atlas.js.map +1 -1
- package/dist/format.d.ts +37 -0
- package/dist/format.d.ts.map +1 -0
- package/dist/format.js +387 -0
- package/dist/format.js.map +1 -0
- package/dist/index.d.ts +5 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/dist/native/generated.d.ts +2 -2
- package/dist/native/generated.d.ts.map +1 -1
- package/dist/native.js +2 -2
- package/dist/native.js.map +1 -1
- package/dist/rrule.d.ts +25 -1
- package/dist/rrule.d.ts.map +1 -1
- package/dist/rrule.js +130 -32
- package/dist/rrule.js.map +1 -1
- package/index.darwin-arm64.node +0 -0
- package/index.darwin-x64.node +0 -0
- package/index.linux-arm64-gnu.node +0 -0
- package/index.linux-x64-gnu.node +0 -0
- package/index.win32-x64-msvc.node +0 -0
- package/package.json +3 -2
- package/src/DateTime.ts +645 -96
- package/src/Duration.ts +318 -139
- package/src/Interval.ts +160 -53
- package/src/atlas.ts +23 -17
- package/src/format.ts +449 -0
- package/src/index.ts +17 -7
- package/src/native/generated.ts +6 -2
- package/src/native.ts +3 -3
- package/src/rrule.ts +189 -37
- package/wasm/chronos_engine_wasm.d.ts +4 -4
- package/wasm/chronos_engine_wasm.js +26 -16
- package/wasm/chronos_engine_wasm_bg.wasm +0 -0
- 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
|
-
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
* `
|
|
59
|
-
*
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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
|
-
* `
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
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
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
84
|
-
|
|
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.
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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
|
-
|
|
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
|
|
263
|
-
return
|
|
264
|
-
return new
|
|
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
|
|
436
|
+
return new _a(new Date(), zone ?? "UTC");
|
|
268
437
|
}
|
|
269
438
|
static fromMillis(ms) {
|
|
270
|
-
|
|
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
|
|
445
|
+
return new _a(new Date(seconds * 1000));
|
|
274
446
|
}
|
|
275
447
|
static fromUnix(seconds) {
|
|
276
|
-
return
|
|
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
|
|
282
|
-
}
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
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
|
|
483
|
+
return new _a(nativeChronos().parseRfc2822(input));
|
|
296
484
|
}
|
|
297
|
-
|
|
298
|
-
|
|
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
|
|
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
|
-
|
|
313
|
-
|
|
314
|
-
|
|
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
|
|
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
|
-
|
|
325
|
-
|
|
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
|
|
328
|
-
?
|
|
329
|
-
:
|
|
330
|
-
|
|
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
|
-
|
|
333
|
-
|
|
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
|
-
|
|
674
|
+
/** `this - other` in one unit, as a fractional number (calendar-aware). */
|
|
675
|
+
#diffNumber(other, unit) {
|
|
336
676
|
const n = nativeChronos();
|
|
337
|
-
const
|
|
338
|
-
return
|
|
339
|
-
? n.diffInZone(this.#iso,
|
|
340
|
-
: n.diff(this.#iso,
|
|
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
|
-
|
|
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
|
|
721
|
+
return this.#derive(this.#zone === "UTC"
|
|
370
722
|
? n.startOf(this.#iso, unit)
|
|
371
|
-
: n.startOfInZone(this.#iso, unit, 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
|
|
728
|
+
return this.#derive(this.#zone === "UTC"
|
|
377
729
|
? n.endOf(this.#iso, unit)
|
|
378
|
-
: n.endOfInZone(this.#iso, unit, 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
|
-
|
|
395
|
-
|
|
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
|
|
808
|
+
return this.toISO();
|
|
399
809
|
}
|
|
400
810
|
toJSON() {
|
|
401
|
-
return this
|
|
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
|
-
|
|
411
|
-
|
|
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 ?
|
|
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);
|