@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.
- 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 +1 -1
- 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/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 {
|
|
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
|
-
/**
|
|
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
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
return new Interval(
|
|
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 =
|
|
166
|
-
const e =
|
|
167
|
-
if (s
|
|
168
|
-
return Interval
|
|
169
|
-
|
|
170
|
-
|
|
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
|
-
/**
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
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
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
const next =
|
|
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
|
-
|
|
48
|
-
|
|
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:**
|
|
72
|
-
*
|
|
73
|
-
* `prepare(consume('2026-04-30T12:00:00.000Z'))`
|
|
74
|
-
* `'2026-04-30T12:00:
|
|
75
|
-
*
|
|
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.
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
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) →
|
|
99
|
-
*
|
|
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
|
});
|