@northguild/gmt 1.14.2

package/dist/utc/interval/intervalDifferenceUtc.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Return the portion(s) of interval A not covered by interval B.
+ *
+ * - Uses `Temporal.Instant.compare` for comparison.
+ * - Returns `[]` when B fully covers A.
+ * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns `[]` if either interval is invalid (`start > end`).
+ * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
+ *
+ * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-05-31T17:00:00Z" }, { start: "2024-07-01T13:00:01Z", end: "2024-12-31T17:00:00Z" }]
+ * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z") // []
+ * @example intervalDifferenceUtc("invalid", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // []
+ */
+export declare function intervalDifferenceUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/utc/interval/intervalDifferenceUtc.js

@@ -0,0 +1,76 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { utcDateTime } from "../../regex/utc-date-time.js";
+/**
+ * Return the portion(s) of interval A not covered by interval B.
+ *
+ * - Uses `Temporal.Instant.compare` for comparison.
+ * - Returns `[]` when B fully covers A.
+ * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns `[]` if either interval is invalid (`start > end`).
+ * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
+ *
+ * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // [{ start: "2024-01-01T09:00:00Z", end: "2024-05-31T17:00:00Z" }, { start: "2024-07-01T13:00:01Z", end: "2024-12-31T17:00:00Z" }]
+ * @example intervalDifferenceUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z") // []
+ * @example intervalDifferenceUtc("invalid", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // []
+ */
+export function intervalDifferenceUtc(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return [];
+    }
+    if (!utcDateTime.test(aStart) ||
+        !utcDateTime.test(aEnd) ||
+        !utcDateTime.test(bStart) ||
+        !utcDateTime.test(bEnd)) {
+        return [];
+    }
+    if (isLeapSecond(aStart) ||
+        isLeapSecond(aEnd) ||
+        isLeapSecond(bStart) ||
+        isLeapSecond(bEnd)) {
+        return [];
+    }
+    try {
+        const aS = Temporal.Instant.from(aStart);
+        const aE = Temporal.Instant.from(aEnd);
+        const bS = Temporal.Instant.from(bStart);
+        const bE = Temporal.Instant.from(bEnd);
+        if (Temporal.Instant.compare(aS, aE) > 0) {
+            return [];
+        }
+        if (Temporal.Instant.compare(bS, bE) > 0) {
+            return [];
+        }
+        const result = [];
+        // Left piece: A before B starts
+        if (Temporal.Instant.compare(aS, bS) < 0) {
+            const leftEnd = Temporal.Instant.compare(aE, bS) < 0
+                ? aE
+                : bS.subtract({ nanoseconds: 1 });
+            if (Temporal.Instant.compare(leftEnd, aS) >= 0) {
+                result.push({ start: aS.toString(), end: leftEnd.toString() });
+            }
+        }
+        // Right piece: A after B ends
+        if (Temporal.Instant.compare(aE, bE) > 0) {
+            result.push({
+                start: bE.add({ nanoseconds: 1 }).toString(),
+                end: aE.toString(),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/utc/interval/intervalDivideEquallyUtc.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Split a UTC interval into `n` equal-length sub-intervals.
+ *
+ * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
+ *   record's `end` equal to the next record's `start`.
+ * - Boundaries are computed from the total elapsed nanoseconds (via `Duration.prototype.total`
+ *   with `relativeTo` set to `start`) — no DST is involved, since UTC has no time zone offset.
+ * - `n === 1` returns the original interval unchanged, as a single-element array.
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
+ * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
+ *   start/end, `start > end`, leap-second strings).
+ *
+ * @param start ISO UTC datetime string for the interval start
+ * @param end ISO UTC datetime string for the interval end
+ * @param n number of equal sub-intervals to produce (positive integer)
+ * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, { start: "2024-01-02T00:00:00Z", end: "2024-01-03T00:00:00Z" }, { start: "2024-01-03T00:00:00Z", end: "2024-01-04T00:00:00Z" }]
+ * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 1) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-04T00:00:00Z" }]
+ * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 0) // []
+ * @example intervalDivideEquallyUtc("invalid", "2024-01-04T00:00:00Z", 3) // []
+ */
+export declare function intervalDivideEquallyUtc(start: string, end: string, n: number): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/utc/interval/intervalDivideEquallyUtc.js

@@ -0,0 +1,65 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { isValidUtcInterval } from "./validate/index.js";
+/**
+ * Split a UTC interval into `n` equal-length sub-intervals.
+ *
+ * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
+ *   record's `end` equal to the next record's `start`.
+ * - Boundaries are computed from the total elapsed nanoseconds (via `Duration.prototype.total`
+ *   with `relativeTo` set to `start`) — no DST is involved, since UTC has no time zone offset.
+ * - `n === 1` returns the original interval unchanged, as a single-element array.
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
+ * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
+ *   start/end, `start > end`, leap-second strings).
+ *
+ * @param start ISO UTC datetime string for the interval start
+ * @param end ISO UTC datetime string for the interval end
+ * @param n number of equal sub-intervals to produce (positive integer)
+ * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }, { start: "2024-01-02T00:00:00Z", end: "2024-01-03T00:00:00Z" }, { start: "2024-01-03T00:00:00Z", end: "2024-01-04T00:00:00Z" }]
+ * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 1) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-04T00:00:00Z" }]
+ * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 0) // []
+ * @example intervalDivideEquallyUtc("invalid", "2024-01-04T00:00:00Z", 3) // []
+ */
+export function intervalDivideEquallyUtc(start, end, n) {
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+        return [];
+    }
+    if (isLeapSecond(start) || isLeapSecond(end)) {
+        return [];
+    }
+    if (!isValidUtcInterval(start, end)) {
+        return [];
+    }
+    try {
+        const startVal = Temporal.Instant.from(start);
+        const endVal = Temporal.Instant.from(end);
+        if (startVal.equals(endVal)) {
+            return Array.from({ length: n }, () => ({
+                start: startVal.toString(),
+                end: endVal.toString(),
+            }));
+        }
+        const totalNs = startVal
+            .until(endVal, { largestUnit: "nanosecond" })
+            .total("nanosecond");
+        const boundaries = [startVal];
+        for (let i = 1; i < n; i++) {
+            boundaries.push(startVal.add({ nanoseconds: Math.round((totalNs * i) / n) }));
+        }
+        boundaries.push(endVal);
+        const result = [];
+        for (let i = 0; i < boundaries.length - 1; i++) {
+            result.push({
+                start: boundaries[i].toString(),
+                end: boundaries[i + 1].toString(),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/utc/interval/intervalEngulfsUtc.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Return true when interval B is fully contained within interval A — every instant of B
+ * falls within A.
+ *
+ * - Uses `Temporal.Instant.compare` for comparison.
+ * - Equivalent to 4-argument `intervalContainsUtc(aStart, aEnd, bStart, bEnd)`.
+ * - Returns `false` if either interval is invalid (`start > end`).
+ * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the outer interval start
+ * @param aEnd ISO 8601 UTC datetime string for the outer interval end
+ * @param bStart ISO 8601 UTC datetime string for the inner interval start
+ * @param bEnd ISO 8601 UTC datetime string for the inner interval end
+ * @returns true if B is fully contained in A, or false on invalid input
+ *
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // true
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z") // true (equal intervals)
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-06-30T12:00:00Z") // true
+ * @example intervalEngulfsUtc("2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z", "2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z") // false
+ * @example intervalEngulfsUtc("invalid", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // false
+ */
+export declare function intervalEngulfsUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): boolean;

package/dist/utc/interval/intervalEngulfsUtc.js

@@ -0,0 +1,61 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { utcDateTime } from "../../regex/utc-date-time.js";
+/**
+ * Return true when interval B is fully contained within interval A — every instant of B
+ * falls within A.
+ *
+ * - Uses `Temporal.Instant.compare` for comparison.
+ * - Equivalent to 4-argument `intervalContainsUtc(aStart, aEnd, bStart, bEnd)`.
+ * - Returns `false` if either interval is invalid (`start > end`).
+ * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the outer interval start
+ * @param aEnd ISO 8601 UTC datetime string for the outer interval end
+ * @param bStart ISO 8601 UTC datetime string for the inner interval start
+ * @param bEnd ISO 8601 UTC datetime string for the inner interval end
+ * @returns true if B is fully contained in A, or false on invalid input
+ *
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // true
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z") // true (equal intervals)
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z", "2024-01-01T09:00:00Z", "2024-06-30T12:00:00Z") // true
+ * @example intervalEngulfsUtc("2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z", "2024-01-01T09:00:00Z", "2024-12-31T17:00:00Z") // false
+ * @example intervalEngulfsUtc("invalid", "2024-12-31T17:00:00Z", "2024-06-01T12:00:00Z", "2024-07-01T13:00:00Z") // false
+ */
+export function intervalEngulfsUtc(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return false;
+    }
+    if (!utcDateTime.test(aStart) ||
+        !utcDateTime.test(aEnd) ||
+        !utcDateTime.test(bStart) ||
+        !utcDateTime.test(bEnd)) {
+        return false;
+    }
+    if (isLeapSecond(aStart) ||
+        isLeapSecond(aEnd) ||
+        isLeapSecond(bStart) ||
+        isLeapSecond(bEnd)) {
+        return false;
+    }
+    try {
+        const aS = Temporal.Instant.from(aStart);
+        const aE = Temporal.Instant.from(aEnd);
+        const bS = Temporal.Instant.from(bStart);
+        const bE = Temporal.Instant.from(bEnd);
+        if (Temporal.Instant.compare(aS, aE) > 0) {
+            return false;
+        }
+        if (Temporal.Instant.compare(bS, bE) > 0) {
+            return false;
+        }
+        return (Temporal.Instant.compare(aS, bS) <= 0 &&
+            Temporal.Instant.compare(bE, aE) <= 0);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utc/interval/intervalFromDurationUtc.d.ts

@@ -0,0 +1,35 @@
+import type { Overflow } from "../../types/index.js";
+/**
+ * Construct a UTC interval from a single point plus an ISO 8601 duration, anchored at either end.
+ *
+ * - `anchor: "start"` treats `value` as the interval start and adds `duration` to get the end.
+ * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
+ * - Converts to `ZonedDateTime("UTC")`, adds/subtracts the duration there, then converts back to an
+ *   Instant — this is what lets calendar units (years/months/weeks/days) resolve without a
+ *   `relativeTo`: unlike a bare `Temporal.Instant`, the `ZonedDateTime` supplies its own implicit
+ *   reference point (mirrors `addUtc`).
+ * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
+ *   happens, mirroring `intervalIntersectionUtc`'s `start > end` rejection.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
+ * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
+ *   than `"start"`/`"end"`).
+ *
+ * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
+ * @param duration ISO 8601 duration string
+ * @param anchor "start" | "end" — which endpoint `value` represents
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns `{ start, end }` with the constructed span (UTC Instant strings), or null on invalid input
+ *
+ * @example intervalFromDurationUtc("2024-01-01T00:00:00Z", "P1D", "start") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }
+ * @example intervalFromDurationUtc("2024-01-02T00:00:00Z", "P1D", "end") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }
+ * @example intervalFromDurationUtc("2024-01-31T00:00:00Z", "P1M", "start", { overflow: "reject" }) // null
+ * @example intervalFromDurationUtc("2024-01-05T00:00:00Z", "-P10D", "start") // null (inverted span)
+ * @example intervalFromDurationUtc("invalid", "P1D", "start") // null
+ */
+export declare function intervalFromDurationUtc(value: string, duration: string, anchor: "start" | "end", options?: {
+    overflow?: Overflow;
+}): {
+    start: string;
+    end: string;
+} | null;

package/dist/utc/interval/intervalFromDurationUtc.js

@@ -0,0 +1,64 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDuration } from "../../duration/validate/index.js";
+import { resolveOverflow } from "../../internal/index.js";
+import { isValidUtc } from "../validate/isValidUtc.js";
+/**
+ * Construct a UTC interval from a single point plus an ISO 8601 duration, anchored at either end.
+ *
+ * - `anchor: "start"` treats `value` as the interval start and adds `duration` to get the end.
+ * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
+ * - Converts to `ZonedDateTime("UTC")`, adds/subtracts the duration there, then converts back to an
+ *   Instant — this is what lets calendar units (years/months/weeks/days) resolve without a
+ *   `relativeTo`: unlike a bare `Temporal.Instant`, the `ZonedDateTime` supplies its own implicit
+ *   reference point (mirrors `addUtc`).
+ * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
+ *   happens, mirroring `intervalIntersectionUtc`'s `start > end` rejection.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
+ * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
+ *   than `"start"`/`"end"`).
+ *
+ * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
+ * @param duration ISO 8601 duration string
+ * @param anchor "start" | "end" — which endpoint `value` represents
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns `{ start, end }` with the constructed span (UTC Instant strings), or null on invalid input
+ *
+ * @example intervalFromDurationUtc("2024-01-01T00:00:00Z", "P1D", "start") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }
+ * @example intervalFromDurationUtc("2024-01-02T00:00:00Z", "P1D", "end") // { start: "2024-01-01T00:00:00Z", end: "2024-01-02T00:00:00Z" }
+ * @example intervalFromDurationUtc("2024-01-31T00:00:00Z", "P1M", "start", { overflow: "reject" }) // null
+ * @example intervalFromDurationUtc("2024-01-05T00:00:00Z", "-P10D", "start") // null (inverted span)
+ * @example intervalFromDurationUtc("invalid", "P1D", "start") // null
+ */
+export function intervalFromDurationUtc(value, duration, anchor, options) {
+    if (typeof value !== "string" || !isValidUtc(value)) {
+        return null;
+    }
+    if (!isValidDuration(duration)) {
+        return null;
+    }
+    if (anchor !== "start" && anchor !== "end") {
+        return null;
+    }
+    try {
+        const instant = Temporal.Instant.from(value);
+        const point = instant.toZonedDateTimeISO("UTC");
+        const dur = Temporal.Duration.from(duration);
+        const overflow = resolveOverflow(options?.overflow);
+        const other = anchor === "start"
+            ? point.add(dur, { overflow })
+            : point.subtract(dur, { overflow });
+        const start = anchor === "start" ? point : other;
+        const end = anchor === "start" ? other : point;
+        if (Temporal.ZonedDateTime.compare(start, end) > 0) {
+            return null;
+        }
+        return {
+            start: start.toInstant().toString(),
+            end: end.toInstant().toString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utc/interval/intervalIntersectionUtc.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Return the overlapping span of two UTC intervals, or null when they do not overlap.
+ *
+ * - Uses `Temporal.Instant.compare` for comparison (same instant semantics).
+ * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap
+ *
+ * @example intervalIntersectionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // { start: "2024-04-01T00:00:00Z", end: "2024-06-30T23:59:59Z" }
+ * @example intervalIntersectionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ * @example intervalIntersectionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-02T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ * @example intervalIntersectionUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ */
+export declare function intervalIntersectionUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): {
+    start: string;
+    end: string;
+} | null;

package/dist/utc/interval/intervalIntersectionUtc.js

@@ -0,0 +1,64 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { utcDateTime } from "../../regex/utc-date-time.js";
+/**
+ * Return the overlapping span of two UTC intervals, or null when they do not overlap.
+ *
+ * - Uses `Temporal.Instant.compare` for comparison (same instant semantics).
+ * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap
+ *
+ * @example intervalIntersectionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // { start: "2024-04-01T00:00:00Z", end: "2024-06-30T23:59:59Z" }
+ * @example intervalIntersectionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ * @example intervalIntersectionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-02T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ * @example intervalIntersectionUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ */
+export function intervalIntersectionUtc(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return null;
+    }
+    if (!utcDateTime.test(aStart) ||
+        !utcDateTime.test(aEnd) ||
+        !utcDateTime.test(bStart) ||
+        !utcDateTime.test(bEnd)) {
+        return null;
+    }
+    if (isLeapSecond(aStart) ||
+        isLeapSecond(aEnd) ||
+        isLeapSecond(bStart) ||
+        isLeapSecond(bEnd)) {
+        return null;
+    }
+    try {
+        const aSI = Temporal.Instant.from(aStart);
+        const aEI = Temporal.Instant.from(aEnd);
+        const bSI = Temporal.Instant.from(bStart);
+        const bEI = Temporal.Instant.from(bEnd);
+        if (Temporal.Instant.compare(aSI, aEI) > 0) {
+            return null;
+        }
+        if (Temporal.Instant.compare(bSI, bEI) > 0) {
+            return null;
+        }
+        if (Temporal.Instant.compare(aEI, bSI) < 0 ||
+            Temporal.Instant.compare(bEI, aSI) < 0) {
+            return null;
+        }
+        const start = Temporal.Instant.compare(aSI, bSI) >= 0 ? aSI : bSI;
+        const end = Temporal.Instant.compare(aEI, bEI) <= 0 ? aEI : bEI;
+        return { start: start.toString(), end: end.toString() };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utc/interval/intervalLengthUtc.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Return the exact length of a UTC interval in `unit`, as a real (possibly fractional) number.
+ *
+ * - Distinct from `intervalCountUtc`, which counts calendar `unit` boundaries *crossed* rather
+ *   than measuring exact duration — an interval from 23:59 to 00:01 touches 2 day boundaries
+ *   via `intervalCountUtc` but has an exact length of ~0.0014 days via `intervalLengthUtc`.
+ * - Boundaries are UTC boundaries — no DST is involved.
+ * - Returns `0` for a zero-length interval (`start === end`).
+ * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
+ *   leap-second strings).
+ *
+ * @param start ISO UTC datetime string for the interval start
+ * @param end ISO UTC datetime string for the interval end
+ * @param unit unit string — any `DateTimeUnit`
+ * @returns exact length of the interval expressed in `unit`, or null on invalid input
+ *
+ * @example intervalLengthUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "day") // 0.001388888888888889
+ * @example intervalLengthUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "minute") // 2
+ * @example intervalLengthUtc("2024-01-01T00:00:00Z", "2024-01-01T00:00:00Z", "day") // 0
+ * @example intervalLengthUtc("invalid", "2024-01-02T00:00:00Z", "day") // null
+ */
+export declare function intervalLengthUtc(start: string, end: string, unit: string): number | null;

package/dist/utc/interval/intervalLengthUtc.js

@@ -0,0 +1,52 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveDateTimeUnit } from "../../internal/index.js";
+import { isValidDateTimeUnit } from "../../plain/validate/index.js";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { isValidUtcInterval } from "./validate/index.js";
+/**
+ * Return the exact length of a UTC interval in `unit`, as a real (possibly fractional) number.
+ *
+ * - Distinct from `intervalCountUtc`, which counts calendar `unit` boundaries *crossed* rather
+ *   than measuring exact duration — an interval from 23:59 to 00:01 touches 2 day boundaries
+ *   via `intervalCountUtc` but has an exact length of ~0.0014 days via `intervalLengthUtc`.
+ * - Boundaries are UTC boundaries — no DST is involved.
+ * - Returns `0` for a zero-length interval (`start === end`).
+ * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
+ *   leap-second strings).
+ *
+ * @param start ISO UTC datetime string for the interval start
+ * @param end ISO UTC datetime string for the interval end
+ * @param unit unit string — any `DateTimeUnit`
+ * @returns exact length of the interval expressed in `unit`, or null on invalid input
+ *
+ * @example intervalLengthUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "day") // 0.001388888888888889
+ * @example intervalLengthUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "minute") // 2
+ * @example intervalLengthUtc("2024-01-01T00:00:00Z", "2024-01-01T00:00:00Z", "day") // 0
+ * @example intervalLengthUtc("invalid", "2024-01-02T00:00:00Z", "day") // null
+ */
+export function intervalLengthUtc(start, end, unit) {
+    if (typeof unit !== "string") {
+        return null;
+    }
+    const resolvedUnit = resolveDateTimeUnit(unit);
+    if (!isValidDateTimeUnit(resolvedUnit)) {
+        return null;
+    }
+    if (isLeapSecond(start) || isLeapSecond(end)) {
+        return null;
+    }
+    if (!isValidUtcInterval(start, end)) {
+        return null;
+    }
+    try {
+        const startVal = Temporal.Instant.from(start).toZonedDateTimeISO("UTC");
+        const endVal = Temporal.Instant.from(end).toZonedDateTimeISO("UTC");
+        const duration = startVal.until(endVal, { largestUnit: resolvedUnit });
+        // total() gives the exact elapsed length, unlike intervalCountUtc's boundary-crossing
+        // count — 23:59 -> 00:01 is 2 day boundaries via intervalCountUtc but ~0.0014 days here.
+        return duration.total({ unit: resolvedUnit, relativeTo: startVal });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utc/interval/intervalOverlappingDaysUtc.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Return how many distinct UTC calendar dates two UTC intervals share.
+ *
+ * - Counts the number of UTC dates touched by the closed intersection
+ *   `[max(aStart, bStart), min(aEnd, bEnd)]` — inclusive of both endpoints.
+ * - Boundaries are UTC boundaries — no DST is involved.
+ * - Adjacent intervals (e.g. `aEnd === bStart`) share one date and count as `1`.
+ * - Returns `0` when the intervals do not overlap at all (a well-defined answer, not
+ *   invalid input).
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Diverges from date-fns's `getOverlappingDaysInIntervals`, which rounds up elapsed
+ *   24-hour periods instead of counting calendar dates (its own doc example — Jan 10-20 vs
+ *   Jan 17-21 — returns 3 there, 4 here). To reproduce date-fns's number, compose
+ *   `intervalIntersectionUtc` with `intervalCountUtc`:
+ *   `const span = intervalIntersectionUtc(aStart, aEnd, bStart, bEnd); span ? intervalCountUtc(span.start, span.end, "day") : 0;`
+ *
+ * @param aStart ISO 8601 UTC datetime string for the first interval start
+ * @param aEnd ISO 8601 UTC datetime string for the first interval end
+ * @param bStart ISO 8601 UTC datetime string for the second interval start
+ * @param bEnd ISO 8601 UTC datetime string for the second interval end
+ * @returns number of shared calendar dates, `0` when disjoint, or null on invalid input
+ *
+ * @example intervalOverlappingDaysUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z") // 2
+ * @example intervalOverlappingDaysUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z") // 1 (adjacent)
+ * @example intervalOverlappingDaysUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z", "2024-01-04T00:00:00Z") // 0 (disjoint)
+ * @example intervalOverlappingDaysUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
+ */
+export declare function intervalOverlappingDaysUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): number | null;