@northguild/gmt 1.15.0 → 1.16.0

package/dist/internal/zonelessCalendarDate.d.ts

@@ -0,0 +1,12 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Read the calendar date `value` names, where `value` is a zoneless ISO date or datetime.
+ *
+ * The `calendar/` identifier functions share this gate. An offset, a bracketed zone or a `Z`
+ * makes `value` a moment rather than a calendar date, and which date a moment falls on is a
+ * zone decision the caller has to make and state — so those are rejected here rather than
+ * silently answered in whatever zone the string happened to be written in.
+ *
+ * - Returns null on anything `isValidIsoDateLike` rejects, and on a Temporal throw.
+ */
+export declare function zonelessCalendarDate(value: string): Temporal.PlainDate | null;

package/dist/internal/zonelessCalendarDate.js

@@ -0,0 +1,22 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidIsoDateLike } from "../plain/validate/isValidIsoDateLike.js";
+/**
+ * Read the calendar date `value` names, where `value` is a zoneless ISO date or datetime.
+ *
+ * The `calendar/` identifier functions share this gate. An offset, a bracketed zone or a `Z`
+ * makes `value` a moment rather than a calendar date, and which date a moment falls on is a
+ * zone decision the caller has to make and state — so those are rejected here rather than
+ * silently answered in whatever zone the string happened to be written in.
+ *
+ * - Returns null on anything `isValidIsoDateLike` rejects, and on a Temporal throw.
+ */
+export function zonelessCalendarDate(value) {
+    if (!isValidIsoDateLike(value))
+        return null;
+    try {
+        return Temporal.PlainDate.from(value);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/interval/calculate/clampInterval.d.ts

@@ -0,0 +1,22 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * Return the part of `interval` that lies inside `bounds`, or null when none of it does.
+ *
+ * - Exactly `intersectIntervals(interval, bounds)`: half-open, so an interval that only touches
+ *   `bounds` clamps to `null`, as does an empty interval at an edge of `bounds`.
+ * - Endpoints are the caller's own strings. Where an endpoint of `interval` and of `bounds` are
+ *   the same instant, `interval`'s spelling is used (GMT rule: the first argument wins ties).
+ * - For zone-aligned bounds (a local business day), build them with `floorToZone` first.
+ * - Returns `null` on invalid input — either argument not an `Interval`, or inverted.
+ *
+ * @param interval `{ start, end }` record of ISO 8601 instant strings to clamp; its strings win ties
+ * @param bounds `{ start, end }` record of ISO 8601 instant strings to clamp into
+ * @returns `{ start, end }` inside `bounds`, or null when nothing remains or on invalid input
+ *
+ * @example clampInterval({ start: "2024-01-01T08:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }
+ * @example clampInterval({ start: "2024-01-01T06:00:00Z", end: "2024-01-01T20:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }
+ * @example clampInterval({ start: "2024-01-01T17:00:00Z", end: "2024-01-01T18:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // null — touching
+ * @example clampInterval({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T09:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // null — empty, at the edge
+ * @example clampInterval({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }) // null — inverted bounds
+ */
+export declare function clampInterval(interval: Interval, bounds: Interval): Interval | null;

package/dist/interval/calculate/clampInterval.js

@@ -0,0 +1,31 @@
+import { intersectIntervals } from "./intersectIntervals.js";
+/**
+ * Return the part of `interval` that lies inside `bounds`, or null when none of it does.
+ *
+ * - Exactly `intersectIntervals(interval, bounds)`: half-open, so an interval that only touches
+ *   `bounds` clamps to `null`, as does an empty interval at an edge of `bounds`.
+ * - Endpoints are the caller's own strings. Where an endpoint of `interval` and of `bounds` are
+ *   the same instant, `interval`'s spelling is used (GMT rule: the first argument wins ties).
+ * - For zone-aligned bounds (a local business day), build them with `floorToZone` first.
+ * - Returns `null` on invalid input — either argument not an `Interval`, or inverted.
+ *
+ * @param interval `{ start, end }` record of ISO 8601 instant strings to clamp; its strings win ties
+ * @param bounds `{ start, end }` record of ISO 8601 instant strings to clamp into
+ * @returns `{ start, end }` inside `bounds`, or null when nothing remains or on invalid input
+ *
+ * @example clampInterval({ start: "2024-01-01T08:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }
+ * @example clampInterval({ start: "2024-01-01T06:00:00Z", end: "2024-01-01T20:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }
+ * @example clampInterval({ start: "2024-01-01T17:00:00Z", end: "2024-01-01T18:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // null — touching
+ * @example clampInterval({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T09:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // null — empty, at the edge
+ * @example clampInterval({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }) // null — inverted bounds
+ */
+export function clampInterval(interval, bounds) {
+    try {
+        return intersectIntervals(interval, bounds);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/interval/calculate/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./clampInterval.js";
+export * from "./intersectIntervals.js";
+export * from "./mergeIntervals.js";
+export * from "./splitIntervalAt.js";
+export * from "./subtractIntervals.js";
+export * from "./sumIntervals.js";

package/dist/interval/calculate/index.js

@@ -0,0 +1,6 @@
+export * from "./clampInterval.js";
+export * from "./intersectIntervals.js";
+export * from "./mergeIntervals.js";
+export * from "./splitIntervalAt.js";
+export * from "./subtractIntervals.js";
+export * from "./sumIntervals.js";

package/dist/interval/calculate/intersectIntervals.d.ts

@@ -0,0 +1,23 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * Return the half-open interval two intervals share, or null when they share no instant.
+ *
+ * - Non-null exactly when `intervalsOverlap(a, b)` is true: touching intervals return `null`.
+ * - An empty interval strictly inside the other is returned as the intersection.
+ * - Endpoints are the caller's own strings, never re-serialised. When `a` and `b` spell the same
+ *   instant differently, `a`'s spelling is used (GMT rule: the first argument wins ties).
+ * - The positional `intervalIntersectionUtc` (…) follow the same half-open rule and return
+ *   re-serialised endpoints instead of echoing the caller's strings.
+ * - Returns `null` on invalid input — either interval not an `Interval`, or inverted.
+ *
+ * @param a `{ start, end }` record of ISO 8601 instant strings; its strings win ties
+ * @param b `{ start, end }` record of ISO 8601 instant strings
+ * @returns `{ start, end }` of the shared span, or null when disjoint, touching, or on invalid input
+ *
+ * @example intersectIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }) // { start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" }
+ * @example intersectIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T17:00:00Z", end: "2024-01-01T18:00:00Z" }) // null — touching
+ * @example intersectIntervals({ start: "2024-01-01T04:00:00-05:00", end: "2024-01-01T12:00:00-05:00" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // { start: "2024-01-01T04:00:00-05:00", end: "2024-01-01T12:00:00-05:00" } — same instants, first argument's spelling
+ * @example intersectIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }) // null — disjoint
+ * @example intersectIntervals({ start: "invalid", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // null
+ */
+export declare function intersectIntervals(a: Interval, b: Interval): Interval | null;

package/dist/interval/calculate/intersectIntervals.js

@@ -0,0 +1,43 @@
+import { parseIntervalNanoseconds } from "../../internal/index.js";
+/**
+ * Return the half-open interval two intervals share, or null when they share no instant.
+ *
+ * - Non-null exactly when `intervalsOverlap(a, b)` is true: touching intervals return `null`.
+ * - An empty interval strictly inside the other is returned as the intersection.
+ * - Endpoints are the caller's own strings, never re-serialised. When `a` and `b` spell the same
+ *   instant differently, `a`'s spelling is used (GMT rule: the first argument wins ties).
+ * - The positional `intervalIntersectionUtc` (…) follow the same half-open rule and return
+ *   re-serialised endpoints instead of echoing the caller's strings.
+ * - Returns `null` on invalid input — either interval not an `Interval`, or inverted.
+ *
+ * @param a `{ start, end }` record of ISO 8601 instant strings; its strings win ties
+ * @param b `{ start, end }` record of ISO 8601 instant strings
+ * @returns `{ start, end }` of the shared span, or null when disjoint, touching, or on invalid input
+ *
+ * @example intersectIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }) // { start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" }
+ * @example intersectIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T17:00:00Z", end: "2024-01-01T18:00:00Z" }) // null — touching
+ * @example intersectIntervals({ start: "2024-01-01T04:00:00-05:00", end: "2024-01-01T12:00:00-05:00" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // { start: "2024-01-01T04:00:00-05:00", end: "2024-01-01T12:00:00-05:00" } — same instants, first argument's spelling
+ * @example intersectIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }) // null — disjoint
+ * @example intersectIntervals({ start: "invalid", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // null
+ */
+export function intersectIntervals(a, b) {
+    try {
+        const first = parseIntervalNanoseconds(a);
+        const second = parseIntervalNanoseconds(b);
+        if (first === null || second === null) {
+            return null;
+        }
+        if (!(first.start < second.end && second.start < first.end)) {
+            return null;
+        }
+        return {
+            start: first.start >= second.start ? first.startText : second.startText,
+            end: first.end <= second.end ? first.endText : second.endText,
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/interval/calculate/mergeIntervals.d.ts

@@ -0,0 +1,28 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * Collapse a list of half-open intervals into the fewest sorted, non-overlapping intervals.
+ *
+ * - Overlapping and touching intervals (`a.end` is `b.start`) coalesce: `[09, 12) ∪ [12, 17)`
+ *   is `[09, 17)`. Intervals one nanosecond apart do not.
+ * - Input order does not matter; the result is sorted by start, and no two results touch.
+ * - Empty intervals (`start === end`) cover no time: one that touches or lies inside a run is
+ *   absorbed, one that touches nothing is dropped (GMT rule).
+ * - Endpoints are the caller's own strings. A run keeps the start of its first interval (by
+ *   instant, then input order) and the end of the first interval to reach its latest end
+ *   (GMT rule: first wins ties between spellings of one instant).
+ * - `[]` is both a legitimate result (an empty list, or a list of only empty intervals) and the
+ *   invalid-input sentinel; check inputs with `isValidInterval` when the difference matters.
+ * - The positional `mergeIntervalsUtc`, `mergeIntervalsZoned` (…) follow the same half-open rule
+ *   and re-serialise endpoints instead of echoing the caller's strings.
+ * - Returns `[]` when `intervals` is not an array or any element is not a valid `Interval`.
+ *
+ * @param intervals array of `{ start, end }` records of ISO 8601 instant strings
+ * @returns sorted, disjoint, non-touching `{ start, end }` records, or [] on invalid input
+ *
+ * @example mergeIntervals([{ start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example mergeIntervals([{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }] — touching
+ * @example mergeIntervals([{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T10:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T12:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T10:00:00Z" }] — stranded empty dropped
+ * @example mergeIntervals([]) // []
+ * @example mergeIntervals([{ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }]) // [] — inverted
+ */
+export declare function mergeIntervals(intervals: Interval[]): Interval[];

package/dist/interval/calculate/mergeIntervals.js

@@ -0,0 +1,44 @@
+import { coalesceIntervalNanoseconds, parseIntervalNanosecondsList, } from "../../internal/index.js";
+/**
+ * Collapse a list of half-open intervals into the fewest sorted, non-overlapping intervals.
+ *
+ * - Overlapping and touching intervals (`a.end` is `b.start`) coalesce: `[09, 12) ∪ [12, 17)`
+ *   is `[09, 17)`. Intervals one nanosecond apart do not.
+ * - Input order does not matter; the result is sorted by start, and no two results touch.
+ * - Empty intervals (`start === end`) cover no time: one that touches or lies inside a run is
+ *   absorbed, one that touches nothing is dropped (GMT rule).
+ * - Endpoints are the caller's own strings. A run keeps the start of its first interval (by
+ *   instant, then input order) and the end of the first interval to reach its latest end
+ *   (GMT rule: first wins ties between spellings of one instant).
+ * - `[]` is both a legitimate result (an empty list, or a list of only empty intervals) and the
+ *   invalid-input sentinel; check inputs with `isValidInterval` when the difference matters.
+ * - The positional `mergeIntervalsUtc`, `mergeIntervalsZoned` (…) follow the same half-open rule
+ *   and re-serialise endpoints instead of echoing the caller's strings.
+ * - Returns `[]` when `intervals` is not an array or any element is not a valid `Interval`.
+ *
+ * @param intervals array of `{ start, end }` records of ISO 8601 instant strings
+ * @returns sorted, disjoint, non-touching `{ start, end }` records, or [] on invalid input
+ *
+ * @example mergeIntervals([{ start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example mergeIntervals([{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }] — touching
+ * @example mergeIntervals([{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T10:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T12:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T10:00:00Z" }] — stranded empty dropped
+ * @example mergeIntervals([]) // []
+ * @example mergeIntervals([{ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }]) // [] — inverted
+ */
+export function mergeIntervals(intervals) {
+    try {
+        const records = parseIntervalNanosecondsList(intervals);
+        if (records === null) {
+            return [];
+        }
+        return coalesceIntervalNanoseconds(records).map((run) => ({
+            start: run.startText,
+            end: run.endText,
+        }));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
+    }
+}

package/dist/interval/calculate/splitIntervalAt.d.ts

@@ -0,0 +1,28 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * Split a half-open interval at instant boundaries into consecutive half-open pieces.
+ *
+ * - Each piece's `end` is the next piece's `start`; under `[start, end)` the pieces share no
+ *   instant and together cover the interval exactly once.
+ * - `boundaries` may be unsorted. Boundaries at or outside the interval's edges are dropped, so
+ *   no piece is empty; duplicate instants keep their first occurrence's spelling (GMT rule).
+ * - Endpoints are the caller's own strings: the interval's own `start`/`end`, and each boundary
+ *   exactly as passed.
+ * - Splitting an empty interval returns it unchanged, as a single piece.
+ * - Never returns `[]` for valid input — that is the invalid-input sentinel alone.
+ * - To split at zone-aligned boundaries (local midnights), build them with `floorToZone` or
+ *   `bucketRange` first.
+ * - Returns `[]` when `interval` is not a valid `Interval`, `boundaries` is not an array, or any
+ *   boundary is not an ISO 8601 instant string — even one outside the interval.
+ *
+ * @param interval `{ start, end }` record of ISO 8601 instant strings to split
+ * @param boundaries array of ISO 8601 instant strings to split at
+ * @returns consecutive `{ start, end }` pieces covering `interval`, or [] on invalid input
+ *
+ * @example splitIntervalAt({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, ["2024-01-01T12:00:00Z"]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example splitIntervalAt({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, ["2024-01-01T15:00:00Z", "2024-01-01T11:00:00Z"]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T11:00:00Z" }, { start: "2024-01-01T11:00:00Z", end: "2024-01-01T15:00:00Z" }, { start: "2024-01-01T15:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example splitIntervalAt({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, ["2024-01-01T09:00:00Z", "2024-01-01T18:00:00Z"]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }] — edge and outside dropped
+ * @example splitIntervalAt({ start: "2024-01-01T12:00:00Z", end: "2024-01-01T12:00:00Z" }, ["2024-01-01T12:00:00Z"]) // [{ start: "2024-01-01T12:00:00Z", end: "2024-01-01T12:00:00Z" }] — empty interval
+ * @example splitIntervalAt({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, ["2024-01-01T12:00:00"]) // [] — no offset
+ */
+export declare function splitIntervalAt(interval: Interval, boundaries: string[]): Interval[];

package/dist/interval/calculate/splitIntervalAt.js

@@ -0,0 +1,63 @@
+import { parseInstantNanoseconds, parseIntervalNanoseconds, } from "../../internal/index.js";
+/**
+ * Split a half-open interval at instant boundaries into consecutive half-open pieces.
+ *
+ * - Each piece's `end` is the next piece's `start`; under `[start, end)` the pieces share no
+ *   instant and together cover the interval exactly once.
+ * - `boundaries` may be unsorted. Boundaries at or outside the interval's edges are dropped, so
+ *   no piece is empty; duplicate instants keep their first occurrence's spelling (GMT rule).
+ * - Endpoints are the caller's own strings: the interval's own `start`/`end`, and each boundary
+ *   exactly as passed.
+ * - Splitting an empty interval returns it unchanged, as a single piece.
+ * - Never returns `[]` for valid input — that is the invalid-input sentinel alone.
+ * - To split at zone-aligned boundaries (local midnights), build them with `floorToZone` or
+ *   `bucketRange` first.
+ * - Returns `[]` when `interval` is not a valid `Interval`, `boundaries` is not an array, or any
+ *   boundary is not an ISO 8601 instant string — even one outside the interval.
+ *
+ * @param interval `{ start, end }` record of ISO 8601 instant strings to split
+ * @param boundaries array of ISO 8601 instant strings to split at
+ * @returns consecutive `{ start, end }` pieces covering `interval`, or [] on invalid input
+ *
+ * @example splitIntervalAt({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, ["2024-01-01T12:00:00Z"]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example splitIntervalAt({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, ["2024-01-01T15:00:00Z", "2024-01-01T11:00:00Z"]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T11:00:00Z" }, { start: "2024-01-01T11:00:00Z", end: "2024-01-01T15:00:00Z" }, { start: "2024-01-01T15:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example splitIntervalAt({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, ["2024-01-01T09:00:00Z", "2024-01-01T18:00:00Z"]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }] — edge and outside dropped
+ * @example splitIntervalAt({ start: "2024-01-01T12:00:00Z", end: "2024-01-01T12:00:00Z" }, ["2024-01-01T12:00:00Z"]) // [{ start: "2024-01-01T12:00:00Z", end: "2024-01-01T12:00:00Z" }] — empty interval
+ * @example splitIntervalAt({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, ["2024-01-01T12:00:00"]) // [] — no offset
+ */
+export function splitIntervalAt(interval, boundaries) {
+    try {
+        const record = parseIntervalNanoseconds(interval);
+        if (record === null || !Array.isArray(boundaries)) {
+            return [];
+        }
+        const inside = [];
+        for (let index = 0; index < boundaries.length; index++) {
+            const text = boundaries[index];
+            const instant = parseInstantNanoseconds(text);
+            if (instant === null) {
+                return [];
+            }
+            if (record.start < instant && instant < record.end) {
+                inside.push({ instant, text });
+            }
+        }
+        // Array.prototype.sort is stable (ES2019): equal instants keep their input order.
+        inside.sort((x, y) => x.instant < y.instant ? -1 : x.instant > y.instant ? 1 : 0);
+        const texts = [record.startText];
+        for (let index = 0; index < inside.length; index++) {
+            if (index === 0 || inside[index].instant !== inside[index - 1].instant) {
+                texts.push(inside[index].text);
+            }
+        }
+        texts.push(record.endText);
+        return texts
+            .slice(0, -1)
+            .map((start, index) => ({ start, end: texts[index + 1] }));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
+    }
+}

package/dist/interval/calculate/subtractIntervals.d.ts

@@ -0,0 +1,31 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * Return the parts of `from` that no interval in `remove` covers, as sorted half-open intervals.
+ *
+ * - A removal strictly inside `from` splits it in two; one covering an edge trims it; one
+ *   covering all of it leaves `[]`.
+ * - Half-open: a removal that only touches `from` removes nothing, and pieces never include an
+ *   instant any removal covers.
+ * - `remove` may be unsorted and overlapping. Removing an empty interval changes nothing;
+ *   subtracting from an empty `from` returns `[]`.
+ * - Endpoints are the caller's own strings, and `from`'s spelling is kept wherever `from` and a
+ *   removal name the same instant (GMT rule).
+ * - `[]` is both a legitimate result (everything removed) and the invalid-input sentinel; check
+ *   inputs with `isValidInterval` when the difference matters.
+ * - The positional `intervalDifferenceUtc` (…) follow the same half-open rule for a single
+ *   removal: pieces end exactly where the removal starts.
+ * - For zone-aligned removals (non-working local days), build them with `floorToZone` first.
+ * - Returns `[]` when `from` is not a valid `Interval`, `remove` is not an array, or any element
+ *   of `remove` is not a valid `Interval` — even one outside `from`.
+ *
+ * @param from `{ start, end }` record of ISO 8601 instant strings to subtract from
+ * @param remove array of `{ start, end }` records of ISO 8601 instant strings to remove
+ * @returns sorted, non-touching `{ start, end }` records of what remains, or [] on invalid input
+ *
+ * @example subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, [{ start: "2024-01-01T12:00:00Z", end: "2024-01-01T13:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, [{ start: "2024-01-01T17:00:00Z", end: "2024-01-01T18:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }] — touching
+ * @example subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, [{ start: "2024-01-01T08:00:00Z", end: "2024-01-01T18:00:00Z" }]) // [] — fully covered
+ * @example subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, []) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, [{ start: "2024-01-01T12:00:00Z", end: "2016-12-31T23:59:60Z" }]) // [] — invalid removal
+ */
+export declare function subtractIntervals(from: Interval, remove: Interval[]): Interval[];

package/dist/interval/calculate/subtractIntervals.js

@@ -0,0 +1,64 @@
+import { coalesceIntervalNanoseconds, parseIntervalNanoseconds, parseIntervalNanosecondsList, } from "../../internal/index.js";
+/**
+ * Return the parts of `from` that no interval in `remove` covers, as sorted half-open intervals.
+ *
+ * - A removal strictly inside `from` splits it in two; one covering an edge trims it; one
+ *   covering all of it leaves `[]`.
+ * - Half-open: a removal that only touches `from` removes nothing, and pieces never include an
+ *   instant any removal covers.
+ * - `remove` may be unsorted and overlapping. Removing an empty interval changes nothing;
+ *   subtracting from an empty `from` returns `[]`.
+ * - Endpoints are the caller's own strings, and `from`'s spelling is kept wherever `from` and a
+ *   removal name the same instant (GMT rule).
+ * - `[]` is both a legitimate result (everything removed) and the invalid-input sentinel; check
+ *   inputs with `isValidInterval` when the difference matters.
+ * - The positional `intervalDifferenceUtc` (…) follow the same half-open rule for a single
+ *   removal: pieces end exactly where the removal starts.
+ * - For zone-aligned removals (non-working local days), build them with `floorToZone` first.
+ * - Returns `[]` when `from` is not a valid `Interval`, `remove` is not an array, or any element
+ *   of `remove` is not a valid `Interval` — even one outside `from`.
+ *
+ * @param from `{ start, end }` record of ISO 8601 instant strings to subtract from
+ * @param remove array of `{ start, end }` records of ISO 8601 instant strings to remove
+ * @returns sorted, non-touching `{ start, end }` records of what remains, or [] on invalid input
+ *
+ * @example subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, [{ start: "2024-01-01T12:00:00Z", end: "2024-01-01T13:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T13:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, [{ start: "2024-01-01T17:00:00Z", end: "2024-01-01T18:00:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }] — touching
+ * @example subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, [{ start: "2024-01-01T08:00:00Z", end: "2024-01-01T18:00:00Z" }]) // [] — fully covered
+ * @example subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, []) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }]
+ * @example subtractIntervals({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, [{ start: "2024-01-01T12:00:00Z", end: "2016-12-31T23:59:60Z" }]) // [] — invalid removal
+ */
+export function subtractIntervals(from, remove) {
+    try {
+        const source = parseIntervalNanoseconds(from);
+        const removals = parseIntervalNanosecondsList(remove);
+        if (source === null || removals === null) {
+            return [];
+        }
+        const pieces = [];
+        let cursor = source.start;
+        let cursorText = source.startText;
+        for (const removal of coalesceIntervalNanoseconds(removals)) {
+            if (cursor >= source.end || removal.start >= source.end) {
+                break;
+            }
+            if (removal.end <= cursor) {
+                continue;
+            }
+            if (removal.start > cursor) {
+                pieces.push({ start: cursorText, end: removal.startText });
+            }
+            cursor = removal.end;
+            cursorText = removal.endText;
+        }
+        if (cursor < source.end) {
+            pieces.push({ start: cursorText, end: source.endText });
+        }
+        return pieces;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
+    }
+}

package/dist/interval/calculate/sumIntervals.d.ts

@@ -0,0 +1,26 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * Return the time covered by a list of half-open intervals, as an exact ISO 8601 duration.
+ *
+ * - Covered time is the length of the union: overlapping time counts once, touching intervals
+ *   add up, empty intervals add nothing.
+ * - Hours are the largest unit, exactly as `Temporal.Instant.prototype.until` with
+ *   `largestUnit: "hour"` renders it — an instant has no calendar, so there are no days.
+ *   `PT49H30M`, not `P2DT1H30M`.
+ * - Exact to the nanosecond at any size, including past 2^53 nanoseconds (about 104 days) and
+ *   across the whole representable instant range (`PT4800000000H`).
+ * - Measures elapsed time, never wall-clock distance: a New York day across spring-forward is
+ *   `PT23H`.
+ * - `[]` returns `"PT0S"` — no time covered, not invalid input.
+ * - Returns `""` when `intervals` is not an array or any element is not a valid `Interval`.
+ *
+ * @param intervals array of `{ start, end }` records of ISO 8601 instant strings
+ * @returns ISO 8601 duration string of the covered time, or "" on invalid input
+ *
+ * @example sumIntervals([{ start: "2024-01-01T00:00:00Z", end: "2024-01-03T01:30:00Z" }]) // "PT49H30M"
+ * @example sumIntervals([{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T13:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" }]) // "PT8H" — overlap counted once
+ * @example sumIntervals([{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T00:00:01.5Z" }]) // "PT1.5S"
+ * @example sumIntervals([]) // "PT0S"
+ * @example sumIntervals([{ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }]) // ""
+ */
+export declare function sumIntervals(intervals: Interval[]): string;

package/dist/interval/calculate/sumIntervals.js

@@ -0,0 +1,40 @@
+import { coalesceIntervalNanoseconds, formatHourDuration, parseIntervalNanosecondsList, } from "../../internal/index.js";
+/**
+ * Return the time covered by a list of half-open intervals, as an exact ISO 8601 duration.
+ *
+ * - Covered time is the length of the union: overlapping time counts once, touching intervals
+ *   add up, empty intervals add nothing.
+ * - Hours are the largest unit, exactly as `Temporal.Instant.prototype.until` with
+ *   `largestUnit: "hour"` renders it — an instant has no calendar, so there are no days.
+ *   `PT49H30M`, not `P2DT1H30M`.
+ * - Exact to the nanosecond at any size, including past 2^53 nanoseconds (about 104 days) and
+ *   across the whole representable instant range (`PT4800000000H`).
+ * - Measures elapsed time, never wall-clock distance: a New York day across spring-forward is
+ *   `PT23H`.
+ * - `[]` returns `"PT0S"` — no time covered, not invalid input.
+ * - Returns `""` when `intervals` is not an array or any element is not a valid `Interval`.
+ *
+ * @param intervals array of `{ start, end }` records of ISO 8601 instant strings
+ * @returns ISO 8601 duration string of the covered time, or "" on invalid input
+ *
+ * @example sumIntervals([{ start: "2024-01-01T00:00:00Z", end: "2024-01-03T01:30:00Z" }]) // "PT49H30M"
+ * @example sumIntervals([{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T13:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T17:00:00Z" }]) // "PT8H" — overlap counted once
+ * @example sumIntervals([{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T00:00:01.5Z" }]) // "PT1.5S"
+ * @example sumIntervals([]) // "PT0S"
+ * @example sumIntervals([{ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }]) // ""
+ */
+export function sumIntervals(intervals) {
+    try {
+        const records = parseIntervalNanosecondsList(intervals);
+        if (records === null) {
+            return "";
+        }
+        const total = coalesceIntervalNanoseconds(records).reduce((sum, run) => sum + (run.end - run.start), 0n);
+        return formatHourDuration(total);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/interval/compare/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./intervalContains.js";
+export * from "./intervalsOverlap.js";

package/dist/interval/compare/index.js

@@ -0,0 +1,2 @@
+export * from "./intervalContains.js";
+export * from "./intervalsOverlap.js";

package/dist/interval/compare/intervalContains.d.ts

@@ -0,0 +1,25 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * Return true when an ISO 8601 instant string lies inside a half-open interval.
+ *
+ * - `start ≤ t < end`: `start` is inside, `end` is not.
+ * - Always `false` for an empty interval (`start === end`) — it contains no instant.
+ * - Compares instants: `isoString` may name a different zone from either endpoint.
+ * - The positional `intervalContainsUtc`, `intervalContainsZoned` (…) follow the same half-open
+ *   rule and exclude `end`.
+ * - Returns `false` on invalid input — `interval` not an `Interval`, or `isoString` not an
+ *   instant string (offset required, no leap second, no unknown critical annotation such as
+ *   `[!foo=bar]`). Zone, calendar and elective annotations are ignored, as
+ *   `Temporal.Instant.from` ignores them.
+ *
+ * @param interval `{ start, end }` record of ISO 8601 instant strings
+ * @param isoString ISO 8601 instant string to test
+ * @returns true if the instant is inside the interval, or false on invalid input
+ *
+ * @example intervalContains({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, "2024-01-01T09:00:00Z") // true — start is inside
+ * @example intervalContains({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, "2024-01-01T17:00:00Z") // false — end is not
+ * @example intervalContains({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, "2024-01-01T04:00:00-05:00") // true — same instant as start
+ * @example intervalContains({ start: "2024-01-01T12:00:00Z", end: "2024-01-01T12:00:00Z" }, "2024-01-01T12:00:00Z") // false — empty interval
+ * @example intervalContains({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, "2024-01-01T12:00:00") // false — no offset
+ */
+export declare function intervalContains(interval: Interval, isoString: string): boolean;

package/dist/interval/compare/intervalContains.js

@@ -0,0 +1,39 @@
+import { parseInstantNanoseconds, parseIntervalNanoseconds, } from "../../internal/index.js";
+/**
+ * Return true when an ISO 8601 instant string lies inside a half-open interval.
+ *
+ * - `start ≤ t < end`: `start` is inside, `end` is not.
+ * - Always `false` for an empty interval (`start === end`) — it contains no instant.
+ * - Compares instants: `isoString` may name a different zone from either endpoint.
+ * - The positional `intervalContainsUtc`, `intervalContainsZoned` (…) follow the same half-open
+ *   rule and exclude `end`.
+ * - Returns `false` on invalid input — `interval` not an `Interval`, or `isoString` not an
+ *   instant string (offset required, no leap second, no unknown critical annotation such as
+ *   `[!foo=bar]`). Zone, calendar and elective annotations are ignored, as
+ *   `Temporal.Instant.from` ignores them.
+ *
+ * @param interval `{ start, end }` record of ISO 8601 instant strings
+ * @param isoString ISO 8601 instant string to test
+ * @returns true if the instant is inside the interval, or false on invalid input
+ *
+ * @example intervalContains({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, "2024-01-01T09:00:00Z") // true — start is inside
+ * @example intervalContains({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, "2024-01-01T17:00:00Z") // false — end is not
+ * @example intervalContains({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, "2024-01-01T04:00:00-05:00") // true — same instant as start
+ * @example intervalContains({ start: "2024-01-01T12:00:00Z", end: "2024-01-01T12:00:00Z" }, "2024-01-01T12:00:00Z") // false — empty interval
+ * @example intervalContains({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, "2024-01-01T12:00:00") // false — no offset
+ */
+export function intervalContains(interval, isoString) {
+    try {
+        const record = parseIntervalNanoseconds(interval);
+        const instant = parseInstantNanoseconds(isoString);
+        if (record === null || instant === null) {
+            return false;
+        }
+        return record.start <= instant && instant < record.end;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return false;
+    }
+}

package/dist/interval/compare/intervalsOverlap.d.ts

@@ -0,0 +1,28 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * Return true when two half-open intervals share at least one instant.
+ *
+ * - `a.start < b.end && b.start < a.end`. Touching intervals (`a.end` is `b.start`) do not
+ *   overlap: under `[start, end)` the shared endpoint belongs only to the later interval.
+ * - True exactly when `intersectIntervals(a, b)` is not `null`.
+ * - An empty interval (`start === end`) overlaps an interval it lies strictly inside, and nothing
+ *   else — not at an edge, not another empty interval at the same instant (GMT rule: an empty
+ *   interval covers no time, so only a strictly interior position is shared).
+ * - Compares instants: endpoints may name different zones.
+ * - The positional `intervalsOverlapUtc`, `intervalsOverlapZoned`, `intervalsOverlapDate` (…)
+ *   follow the same half-open rule, so touching intervals do not overlap there either.
+ * - For zone-aligned windows (a local day, a trading session), build the endpoints with
+ *   `floorToZone` first.
+ * - Returns `false` on invalid input — either interval not an `Interval`, or inverted.
+ *
+ * @param a `{ start, end }` record of ISO 8601 instant strings
+ * @param b `{ start, end }` record of ISO 8601 instant strings
+ * @returns true if the intervals share an instant, or false on invalid input
+ *
+ * @example intervalsOverlap({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }) // true
+ * @example intervalsOverlap({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T17:00:00Z", end: "2024-01-01T18:00:00Z" }) // false — touching
+ * @example intervalsOverlap({ start: "2024-01-01T12:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // true — empty, strictly inside
+ * @example intervalsOverlap({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T09:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // false — empty, at the edge
+ * @example intervalsOverlap({ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // false — inverted
+ */
+export declare function intervalsOverlap(a: Interval, b: Interval): boolean;