@northguild/gmt 1.14.2 → 1.16.0

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

@@ -3,24 +3,37 @@
  *
  * - 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.
+ * - Every piece is half-open `[start, end)`: a boundary belongs only to the piece that starts
+ *   there, so the pieces share no value and together cover the interval exactly once (the rule
+ *   CORE-6's `splitIntervalAt` uses).
+ * - Each boundary is `start + round((end - start) · i / n)` in integer epoch nanoseconds, so the
+ *   split is exact whenever the span divides evenly by `n` and within half a nanosecond of the
+ *   exact cut otherwise, at any span length (no double arithmetic) — 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).
+ * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
+ *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
+ *   before building any piece. An invalid `maxPieces` also returns `[]`.
  *
  * @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)
+ * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
  * @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) // []
+ * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3, { maxPieces: 2 }) // [] (3 pieces exceed the limit)
+ * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3, { maxPieces: 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" }]
  */
-export declare function intervalDivideEquallyUtc(start: string, end: string, n: number): Array<{
+export declare function intervalDivideEquallyUtc(start: string, end: string, n: number, options?: {
+    maxPieces?: number;
+}): Array<{
     start: string;
     end: string;
 }>;

package/dist/utc/interval/intervalDivideEquallyUtc.js

@@ -1,65 +1,85 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
 import { isValidUtcInterval } from "./validate/index.js";
+import { divisionBoundary } from "../../internal/divisionBoundary.js";
+import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.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.
+ * - Every piece is half-open `[start, end)`: a boundary belongs only to the piece that starts
+ *   there, so the pieces share no value and together cover the interval exactly once (the rule
+ *   CORE-6's `splitIntervalAt` uses).
+ * - Each boundary is `start + round((end - start) · i / n)` in integer epoch nanoseconds, so the
+ *   split is exact whenever the span divides evenly by `n` and within half a nanosecond of the
+ *   exact cut otherwise, at any span length (no double arithmetic) — 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).
+ * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
+ *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
+ *   before building any piece. An invalid `maxPieces` also returns `[]`.
  *
  * @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)
+ * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
  * @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) // []
+ * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3, { maxPieces: 2 }) // [] (3 pieces exceed the limit)
+ * @example intervalDivideEquallyUtc("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z", 3, { maxPieces: 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" }]
  */
-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 [];
-    }
+export function intervalDivideEquallyUtc(start, end, n, options) {
     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(),
-            }));
+        if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+            return [];
+        }
+        const maxPieces = resolveMaxPieces(options);
+        if (maxPieces === null || exceedsPieceLimit(n, maxPieces)) {
+            return [];
+        }
+        if (!isValidUtcInterval(start, end)) {
+            return [];
         }
-        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) }));
+        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 startNs = startVal.epochNanoseconds;
+            const totalNs = endVal.epochNanoseconds - startNs;
+            const boundaries = [startVal];
+            for (let i = 1; i < n; i++) {
+                boundaries.push(Temporal.Instant.fromEpochNanoseconds(startNs + divisionBoundary(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;
         }
-        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(),
-            });
+        catch {
+            return [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

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

@@ -1,22 +1,27 @@
 /**
- * Return true when interval B is fully contained within interval A — every instant of B
- * falls within A.
+ * Return true when the half-open interval B `[bStart, bEnd)` lies within the half-open interval
+ * A `[aStart, aEnd)` — every instant of B is also in A.
  *
- * - Uses `Temporal.Instant.compare` for comparison.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. B may start at A's start and
+ *   end at A's end, because neither end is part of either interval.
+ * - B must also overlap A, so an empty B (`bStart === bEnd`) counts only strictly inside A, never
+ *   at an edge (CORE-6's `clampInterval` clamps it away there).
  * - Equivalent to 4-argument `intervalContainsUtc(aStart, aEnd, bStart, bEnd)`.
+ * - Uses `Temporal.Instant.compare` for comparison.
  * - Returns `false` if either interval is invalid (`start > end`).
- * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `false` on invalid input (wrong type, non-`Z` strings, 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 aEnd ISO 8601 UTC datetime string for the outer interval end (excluded)
  * @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
+ * @param bEnd ISO 8601 UTC datetime string for the inner interval end (excluded)
+ * @returns true if B lies within 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
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T13:00:00Z") // true
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z") // true (equal intervals)
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // true (same end)
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z") // true (empty interval strictly inside)
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T17:00:00Z") // false (empty interval at the edge)
+ * @example intervalEngulfsUtc("2024-01-01T12:00:00Z", "2024-01-01T13:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z") // false
  */
 export declare function intervalEngulfsUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): boolean;

package/dist/utc/interval/intervalEngulfsUtc.js

@@ -1,26 +1,32 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+import { halfOpenContainsSpan } from "../../internal/index.js";
+import { isValidUtc } from "../validate/index.js";
 /**
- * Return true when interval B is fully contained within interval A — every instant of B
- * falls within A.
+ * Return true when the half-open interval B `[bStart, bEnd)` lies within the half-open interval
+ * A `[aStart, aEnd)` — every instant of B is also in A.
  *
- * - Uses `Temporal.Instant.compare` for comparison.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. B may start at A's start and
+ *   end at A's end, because neither end is part of either interval.
+ * - B must also overlap A, so an empty B (`bStart === bEnd`) counts only strictly inside A, never
+ *   at an edge (CORE-6's `clampInterval` clamps it away there).
  * - Equivalent to 4-argument `intervalContainsUtc(aStart, aEnd, bStart, bEnd)`.
+ * - Uses `Temporal.Instant.compare` for comparison.
  * - Returns `false` if either interval is invalid (`start > end`).
- * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `false` on invalid input (wrong type, non-`Z` strings, 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 aEnd ISO 8601 UTC datetime string for the outer interval end (excluded)
  * @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
+ * @param bEnd ISO 8601 UTC datetime string for the inner interval end (excluded)
+ * @returns true if B lies within 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
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T13:00:00Z") // true
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z") // true (equal intervals)
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // true (same end)
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z") // true (empty interval strictly inside)
+ * @example intervalEngulfsUtc("2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T17:00:00Z", "2024-01-01T17:00:00Z") // false (empty interval at the edge)
+ * @example intervalEngulfsUtc("2024-01-01T12:00:00Z", "2024-01-01T13:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z") // false
  */
 export function intervalEngulfsUtc(aStart, aEnd, bStart, bEnd) {
     if (typeof aStart !== "string" ||
@@ -29,16 +35,10 @@ export function intervalEngulfsUtc(aStart, aEnd, bStart, bEnd) {
         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)) {
+    if (!isValidUtc(aStart) ||
+        !isValidUtc(aEnd) ||
+        !isValidUtc(bStart) ||
+        !isValidUtc(bEnd)) {
         return false;
     }
     try {
@@ -52,8 +52,7 @@ export function intervalEngulfsUtc(aStart, aEnd, bStart, bEnd) {
         if (Temporal.Instant.compare(bS, bE) > 0) {
             return false;
         }
-        return (Temporal.Instant.compare(aS, bS) <= 0 &&
-            Temporal.Instant.compare(bE, aE) <= 0);
+        return halfOpenContainsSpan({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.Instant.compare);
     }
     catch {
         return false;

package/dist/utc/interval/intervalFromDurationUtc.js

@@ -1,7 +1,9 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 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";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Construct a UTC interval from a single point plus an ISO 8601 duration, anchored at either end.
  *
@@ -31,6 +33,9 @@ import { isValidUtc } from "../validate/isValidUtc.js";
  * @example intervalFromDurationUtc("invalid", "P1D", "start") // null
  */
 export function intervalFromDurationUtc(value, duration, anchor, options) {
+    if (!isOptionsArgument(options)) {
+        return null;
+    }
     if (typeof value !== "string" || !isValidUtc(value)) {
         return null;
     }

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

@@ -1,10 +1,16 @@
 /**
  * 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.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The intersection is
+ *   `[max(aStart, bStart), min(aEnd, bEnd))` when `aStart < bEnd && bStart < aEnd` (CORE-6's
+ *   `intersectIntervals`), otherwise `null`.
+ * - Touching intervals (`aEnd === bStart`) share no instant and return `null`.
+ * - An empty interval (`start === end`) intersects only an interval it lies strictly inside, and
+ *   then returns itself.
+ * - Delegates to CORE-6's `intersectIntervals` once the arguments pass the UTC-string gate, and
+ *   re-serialises the result, so it always equals that function's answer in canonical `Z` form.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `null` on invalid input (wrong type, non-`Z` strings, 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
@@ -12,9 +18,9 @@
  * @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("2024-01-01T09:00:00Z", "2024-01-01T13:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // { start: "2024-01-01T12:00:00Z", end: "2024-01-01T13:00:00Z" }
+ * @example intervalIntersectionUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // null (touching)
+ * @example intervalIntersectionUtc("2024-01-01T09:00:00.000Z", "2024-01-01T13:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z") // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T13:00:00Z" } (re-serialised)
  * @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): {

package/dist/utc/interval/intervalIntersectionUtc.js

@@ -1,13 +1,20 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { canonicalInstantIntervals } from "../../internal/index.js";
+import { intersectIntervals } from "../../interval/calculate/index.js";
+import { isValidUtc } from "../validate/index.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.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The intersection is
+ *   `[max(aStart, bStart), min(aEnd, bEnd))` when `aStart < bEnd && bStart < aEnd` (CORE-6's
+ *   `intersectIntervals`), otherwise `null`.
+ * - Touching intervals (`aEnd === bStart`) share no instant and return `null`.
+ * - An empty interval (`start === end`) intersects only an interval it lies strictly inside, and
+ *   then returns itself.
+ * - Delegates to CORE-6's `intersectIntervals` once the arguments pass the UTC-string gate, and
+ *   re-serialises the result, so it always equals that function's answer in canonical `Z` form.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (wrong type, malformed strings, leap seconds).
+ * - Returns `null` on invalid input (wrong type, non-`Z` strings, 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
@@ -15,9 +22,9 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  * @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("2024-01-01T09:00:00Z", "2024-01-01T13:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // { start: "2024-01-01T12:00:00Z", end: "2024-01-01T13:00:00Z" }
+ * @example intervalIntersectionUtc("2024-01-01T09:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T12:00:00Z", "2024-01-01T17:00:00Z") // null (touching)
+ * @example intervalIntersectionUtc("2024-01-01T09:00:00.000Z", "2024-01-01T13:00:00Z", "2024-01-01T09:00:00Z", "2024-01-01T17:00:00Z") // { start: "2024-01-01T09:00:00Z", end: "2024-01-01T13:00:00Z" } (re-serialised)
  * @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) {
@@ -27,38 +34,14 @@ export function intervalIntersectionUtc(aStart, aEnd, bStart, bEnd) {
         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 {
+    if (!isValidUtc(aStart) ||
+        !isValidUtc(aEnd) ||
+        !isValidUtc(bStart) ||
+        !isValidUtc(bEnd)) {
         return null;
     }
+    const shared = intersectIntervals({ start: aStart, end: aEnd }, { start: bStart, end: bEnd });
+    return shared === null
+        ? null
+        : (canonicalInstantIntervals([shared])?.[0] ?? null);
 }

package/dist/utc/interval/intervalLengthUtc.js

@@ -1,7 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveDateTimeUnit } from "../../internal/index.js";
+import { durationTotal, resolveDateTimeUnit, zonedUntil } 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.
@@ -32,19 +31,18 @@ export function intervalLengthUtc(start, end, 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 });
+        const duration = zonedUntil(startVal, 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 });
+        return durationTotal(duration, resolvedUnit, startVal);
     }
     catch {
         return null;

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

@@ -1,19 +1,13 @@
 /**
  * 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).
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The count is the number of
+ *   calendar days holding at least one instant of the intersection `[max(aStart, bStart),
+ *   min(aEnd, bEnd))`. An intersection ending exactly at midnight does not reach that day.
+ * - Touching intervals (`aEnd === bStart`) share no instant and count `0`; so does an empty interval.
+ * - Returns `0` when the intervals share nothing (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
@@ -22,8 +16,8 @@
  * @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("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z") // 1
+ * @example intervalOverlappingDaysUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z") // 0 (touching)
  * @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;

package/dist/utc/interval/intervalOverlappingDaysUtc.js

@@ -1,22 +1,17 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+import { halfOpenIntersection } from "../../internal/index.js";
+import { isValidUtc } from "../validate/index.js";
 /**
  * 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).
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The count is the number of
+ *   calendar days holding at least one instant of the intersection `[max(aStart, bStart),
+ *   min(aEnd, bEnd))`. An intersection ending exactly at midnight does not reach that day.
+ * - Touching intervals (`aEnd === bStart`) share no instant and count `0`; so does an empty interval.
+ * - Returns `0` when the intervals share nothing (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
@@ -25,8 +20,8 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  * @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("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z") // 1
+ * @example intervalOverlappingDaysUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z") // 0 (touching)
  * @example intervalOverlappingDaysUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
  */
 export function intervalOverlappingDaysUtc(aStart, aEnd, bStart, bEnd) {
@@ -36,16 +31,10 @@ export function intervalOverlappingDaysUtc(aStart, aEnd, bStart, bEnd) {
         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)) {
+    if (!isValidUtc(aStart) ||
+        !isValidUtc(aEnd) ||
+        !isValidUtc(bStart) ||
+        !isValidUtc(bEnd)) {
         return null;
     }
     try {
@@ -53,21 +42,21 @@ export function intervalOverlappingDaysUtc(aStart, aEnd, bStart, bEnd) {
         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 null;
-        }
-        if (Temporal.Instant.compare(bS, bE) > 0) {
+        if (Temporal.Instant.compare(aS, aE) > 0 ||
+            Temporal.Instant.compare(bS, bE) > 0) {
             return null;
         }
-        if (Temporal.Instant.compare(aE, bS) < 0 ||
-            Temporal.Instant.compare(bE, aS) < 0) {
+        const shared = halfOpenIntersection({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.Instant.compare);
+        if (shared === null || shared.start.equals(shared.end)) {
             return 0;
         }
-        const start = Temporal.Instant.compare(aS, bS) >= 0 ? aS : bS;
-        const end = Temporal.Instant.compare(aE, bE) <= 0 ? aE : bE;
-        const startDate = start.toZonedDateTimeISO("UTC").toPlainDate();
-        const endDate = end.toZonedDateTimeISO("UTC").toPlainDate();
-        return startDate.until(endDate, { largestUnit: "day" }).days + 1;
+        const start = shared.start.toZonedDateTimeISO("UTC");
+        const end = shared.end.toZonedDateTimeISO("UTC");
+        const endsAtMidnight = end.toPlainTime().equals(new Temporal.PlainTime());
+        const days = start
+            .toPlainDate()
+            .until(end.toPlainDate(), { largestUnit: "day" }).days;
+        return endsAtMidnight ? days : days + 1;
     }
     catch {
         return null;