@northguild/gmt 1.14.2 → 1.16.0

package/dist/unix/interval/intervalLengthUnix.js

@@ -1,39 +1,62 @@
-import { resolveUnixIntervalPair } from "./resolveUnixIntervalPair.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { durationTotal, zonedUntil } from "../../internal/index.js";
+import { resolveUnixIntervalPair } from "../../internal/resolveUnixIntervalPair.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the exact length of a Unix epoch interval in `unit`, as a real (possibly fractional) number.
  *
  * - Distinct from `intervalCountUnix`, which counts local calendar `unit` boundaries *crossed*
  *   rather than measuring exact duration.
- * - Uses the system timeZone for calendar-unit resolution (consistent with `intervalCountUnix`
- *   and `splitIntervalByUnitUnix`), so month/year lengths are host-dependent; fixed-length units
- *   (hour, minute, second, …) are timeZone-independent.
+ * - Reads `start` and `end` in `options.epochUnit` (`"milliseconds"` by default, `"seconds"`; singular
+ *   accepted). Each is a safe integer or a string of optionally negative ASCII digits.
+ * - Resolves calendar units in `options.timeZone`: omitted is `"UTC"`, `"local"` is the system
+ *   zone, and an unknown zone returns `null`. Fixed-length units (hour, minute, second, …) are
+ *   zone-independent; a day is a local day, so New York's 23-hour 2024-03-10 is 1 day long there.
+ * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
  * - Returns `0` for a zero-length interval (`start === end`).
- * - Returns `null` on invalid input (non-finite/non-integer start/end, `start > end`,
- *   unsupported unit, or invalid timeZone).
+ * - Returns `null` on invalid input (`start`/`end` that is not a safe integer or numeric string of
+ *   one, or lies outside the Temporal instant range, `start > end`, an unsupported unit, an invalid
+ *   `epochUnit` or an unknown `timeZone`).
  *
- * @param start Unix epoch value (seconds or milliseconds) — interval start
- * @param end Unix epoch value (seconds or milliseconds) — interval end
- * @param unit unit string — any `DateTimeUnit`
+ * @param start Unix epoch in `epochUnit` — interval start
+ * @param end Unix epoch in `epochUnit` — interval end
+ * @param unit unit string — any `DateTimeUnit`, singular or plural
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
  * @returns exact length of the interval expressed in `unit`, or null on invalid input
  *
  * @example intervalLengthUnix(0, 86400000, "hour") // 24
  * @example intervalLengthUnix(0, 5400000, "hour") // 1.5
  * @example intervalLengthUnix(0, 0, "hour") // 0
  * @example intervalLengthUnix(86400000, 0, "hour") // null
+ * @example intervalLengthUnix(1710046800000, 1710129600000, "day", { timeZone: "America/New_York" }) // 1 (the 23-hour local day)
+ * @example intervalLengthUnix(1710046800000, 1710129600000, "day") // 0.9583333333333334 (23/24 of a UTC day)
+ * @example intervalLengthUnix("0", "86400", "hours", { epochUnit: "second" }) // 24
  * @example intervalLengthUnix(NaN, 86400000, "hour") // null
  */
-export function intervalLengthUnix(start, end, unit) {
-    const resolved = resolveUnixIntervalPair(start, end, unit);
-    if (!resolved)
-        return null;
+export function intervalLengthUnix(start, end, unit, options) {
     try {
-        const { startVal, endVal, resolvedUnit } = resolved;
-        const duration = startVal.until(endVal, { largestUnit: resolvedUnit });
-        // total() gives the exact elapsed length, unlike intervalCountUnix's boundary-crossing
-        // count over the same system-timeZone calendar.
-        return duration.total({ unit: resolvedUnit, relativeTo: startVal });
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const resolved = resolveUnixIntervalPair(start, end, unit, options);
+        if (!resolved)
+            return null;
+        try {
+            const { startVal, endVal, resolvedUnit } = resolved;
+            const duration = zonedUntil(startVal, endVal, {
+                largestUnit: resolvedUnit,
+            });
+            // total() gives the exact elapsed length, unlike intervalCountUnix's boundary-crossing
+            // count over the same zone's calendar.
+            return durationTotal(duration, resolvedUnit, startVal);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/unix/interval/intervalOverlappingDaysUnix.d.ts

@@ -1,16 +1,27 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Return how many distinct calendar dates two Unix epoch intervals share, in a given
  * time zone.
  *
- * - Counts the number of local dates touched by the closed intersection
- *   `[max(aStart, bStart), min(aEnd, bEnd)]` — inclusive of both endpoints.
- * - Uses the system timeZone by default (consistent with `addUnix` and
- *   `intervalCountUnix`), so day counts are host-dependent unless `timeZone` is given.
- * - 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).
+ * - Counts the local dates that hold at least one instant of the half-open intersection
+ *   `[max(aStart, bStart), min(aEnd, bEnd))`. The end is excluded, so an intersection ending at
+ *   local midnight does not touch the date that midnight starts.
+ * - Uses `"UTC"` by default (consistent with `addUnix` and `intervalCountUnix`); `"local"` is the
+ *   system zone and an unknown zone returns `null`.
+ * - Each instant in the intersection contributes its own local date in `timeZone`, and each date
+ *   counts once. A date the zone deleted is not counted (`Pacific/Apia` skipped 2011-12-30), and a
+ *   fall-back into the previous date does not lose that date (`America/Goose_Bay`, 2010-11-07).
+ * - Returns `null` when the intersection crosses more than 10,000 zone transitions (the same cap
+ *   as `intervalCountZoned`).
+ * - Compatibility: before 1.16.0 the count was the calendar difference of the two endpoint dates
+ *   plus one. To get that number for overlapping intervals, with `start`/`end` the intersection:
+ *   `diffDate(convertUnixToPlainDate(start, { timeZone }), convertUnixToPlainDate(end, { timeZone }), "days") + 1`.
+ * - Returns `0` when the intersection is empty (a well-defined answer, not invalid input): when the
+ *   intervals are disjoint, when they touch (e.g. `aEnd === bStart`), or when either is empty.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (non-finite/non-integer epoch values, invalid timeZone).
+ * - Returns `null` on invalid input (epoch values that are not safe integers or numeric strings of
+ *   one — fractions, empty strings and values beyond ±(2^53 − 1) are invalid — or an invalid
+ *   timeZone).
  * - Diverges from date-fns's `getOverlappingDaysInIntervals`, which rounds up elapsed
  *   24-hour periods instead of counting calendar dates. To reproduce date-fns's number,
  *   compose `intervalIntersectionUnix` with `intervalCountUnix`:
@@ -20,15 +31,18 @@
  * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
  * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
  * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA, default: system timeZone)
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
  * @returns number of shared calendar dates, `0` when disjoint, or null on invalid input
  *
- * @example intervalOverlappingDaysUnix(0, 172800000, 86400000, 259200000, { timeZone: "UTC" }) // 2
- * @example intervalOverlappingDaysUnix(0, 86400000, 86400000, 172800000, { timeZone: "UTC" }) // 1 (adjacent)
+ * @example intervalOverlappingDaysUnix(0, 172800000, 86400000, 259200000, { timeZone: "UTC" }) // 1 (the intersection [86400000, 172800000) is 1970-01-02)
+ * @example intervalOverlappingDaysUnix(0, 172800001, 86400000, 259200000, { timeZone: "UTC" }) // 2
+ * @example intervalOverlappingDaysUnix(0, 86400000, 86400000, 172800000, { timeZone: "UTC" }) // 0 (touching: no shared instant)
  * @example intervalOverlappingDaysUnix(0, 86400000, 172800000, 259200000, { timeZone: "UTC" }) // 0 (disjoint)
+ * @example intervalOverlappingDaysUnix(1289098830000, 1289100600000, 1289098830000, 1289100600000, { timeZone: "America/Goose_Bay" }) // 2 (the clock fell back into 2010-11-06)
+ * @example diffDate(convertUnixToPlainDate(1289098830000, { timeZone: "America/Goose_Bay" }), convertUnixToPlainDate(1289100600000, { timeZone: "America/Goose_Bay" }), "days") + 1 // 0 (pre-1.16.0 count)
  * @example intervalOverlappingDaysUnix(NaN, 172800000, 86400000, 259200000, { timeZone: "UTC" }) // null
  */
 export declare function intervalOverlappingDaysUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+    epochUnit?: UnixUnit;
     timeZone?: string;
 }): number | null;

package/dist/unix/interval/intervalOverlappingDaysUnix.js

@@ -1,18 +1,30 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { resolveUnixTimeZone } from "../../internal/resolveUnixTimeZone.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { countZonedLocalDates, halfOpenIntersection, parseUnixEpochInterval, } from "../../internal/index.js";
+import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return how many distinct calendar dates two Unix epoch intervals share, in a given
  * time zone.
  *
- * - Counts the number of local dates touched by the closed intersection
- *   `[max(aStart, bStart), min(aEnd, bEnd)]` — inclusive of both endpoints.
- * - Uses the system timeZone by default (consistent with `addUnix` and
- *   `intervalCountUnix`), so day counts are host-dependent unless `timeZone` is given.
- * - 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).
+ * - Counts the local dates that hold at least one instant of the half-open intersection
+ *   `[max(aStart, bStart), min(aEnd, bEnd))`. The end is excluded, so an intersection ending at
+ *   local midnight does not touch the date that midnight starts.
+ * - Uses `"UTC"` by default (consistent with `addUnix` and `intervalCountUnix`); `"local"` is the
+ *   system zone and an unknown zone returns `null`.
+ * - Each instant in the intersection contributes its own local date in `timeZone`, and each date
+ *   counts once. A date the zone deleted is not counted (`Pacific/Apia` skipped 2011-12-30), and a
+ *   fall-back into the previous date does not lose that date (`America/Goose_Bay`, 2010-11-07).
+ * - Returns `null` when the intersection crosses more than 10,000 zone transitions (the same cap
+ *   as `intervalCountZoned`).
+ * - Compatibility: before 1.16.0 the count was the calendar difference of the two endpoint dates
+ *   plus one. To get that number for overlapping intervals, with `start`/`end` the intersection:
+ *   `diffDate(convertUnixToPlainDate(start, { timeZone }), convertUnixToPlainDate(end, { timeZone }), "days") + 1`.
+ * - Returns `0` when the intersection is empty (a well-defined answer, not invalid input): when the
+ *   intervals are disjoint, when they touch (e.g. `aEnd === bStart`), or when either is empty.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (non-finite/non-integer epoch values, invalid timeZone).
+ * - Returns `null` on invalid input (epoch values that are not safe integers or numeric strings of
+ *   one — fractions, empty strings and values beyond ±(2^53 − 1) are invalid — or an invalid
+ *   timeZone).
  * - Diverges from date-fns's `getOverlappingDaysInIntervals`, which rounds up elapsed
  *   24-hour periods instead of counting calendar dates. To reproduce date-fns's number,
  *   compose `intervalIntersectionUnix` with `intervalCountUnix`:
@@ -22,68 +34,60 @@ import { resolveUnixTimeZone } from "../../internal/resolveUnixTimeZone.js";
  * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
  * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
  * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA, default: system timeZone)
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
  * @returns number of shared calendar dates, `0` when disjoint, or null on invalid input
  *
- * @example intervalOverlappingDaysUnix(0, 172800000, 86400000, 259200000, { timeZone: "UTC" }) // 2
- * @example intervalOverlappingDaysUnix(0, 86400000, 86400000, 172800000, { timeZone: "UTC" }) // 1 (adjacent)
+ * @example intervalOverlappingDaysUnix(0, 172800000, 86400000, 259200000, { timeZone: "UTC" }) // 1 (the intersection [86400000, 172800000) is 1970-01-02)
+ * @example intervalOverlappingDaysUnix(0, 172800001, 86400000, 259200000, { timeZone: "UTC" }) // 2
+ * @example intervalOverlappingDaysUnix(0, 86400000, 86400000, 172800000, { timeZone: "UTC" }) // 0 (touching: no shared instant)
  * @example intervalOverlappingDaysUnix(0, 86400000, 172800000, 259200000, { timeZone: "UTC" }) // 0 (disjoint)
+ * @example intervalOverlappingDaysUnix(1289098830000, 1289100600000, 1289098830000, 1289100600000, { timeZone: "America/Goose_Bay" }) // 2 (the clock fell back into 2010-11-06)
+ * @example diffDate(convertUnixToPlainDate(1289098830000, { timeZone: "America/Goose_Bay" }), convertUnixToPlainDate(1289100600000, { timeZone: "America/Goose_Bay" }), "days") + 1 // 0 (pre-1.16.0 count)
  * @example intervalOverlappingDaysUnix(NaN, 172800000, 86400000, 259200000, { timeZone: "UTC" }) // null
  */
 export function intervalOverlappingDaysUnix(aStart, aEnd, bStart, bEnd, options) {
-    if (typeof aStart !== "number" && typeof aStart !== "string") {
-        return null;
-    }
-    if (typeof aEnd !== "number" && typeof aEnd !== "string") {
-        return null;
-    }
-    if (typeof bStart !== "number" && typeof bStart !== "string") {
-        return null;
-    }
-    if (typeof bEnd !== "number" && typeof bEnd !== "string") {
-        return null;
-    }
-    const a1 = typeof aStart === "number" ? aStart : Number(aStart);
-    const a2 = typeof aEnd === "number" ? aEnd : Number(aEnd);
-    const b1 = typeof bStart === "number" ? bStart : Number(bStart);
-    const b2 = typeof bEnd === "number" ? bEnd : Number(bEnd);
-    if (!Number.isFinite(a1) ||
-        !Number.isInteger(a1) ||
-        !Number.isFinite(a2) ||
-        !Number.isInteger(a2) ||
-        !Number.isFinite(b1) ||
-        !Number.isInteger(b1) ||
-        !Number.isFinite(b2) ||
-        !Number.isInteger(b2)) {
-        return null;
-    }
-    if (a1 > a2) {
-        return null;
-    }
-    if (b1 > b2) {
-        return null;
-    }
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    const timeZone = resolveUnixTimeZone(options?.timeZone);
-    if (!timeZone) {
-        return null;
-    }
-    if (a2 < b1 || b2 < a1) {
-        return 0;
-    }
     try {
-        const toMs = (value) => epochUnit === "seconds" ? value * 1000 : value;
-        const start = Math.max(a1, b1);
-        const end = Math.min(a2, b2);
-        const startDate = Temporal.Instant.fromEpochMilliseconds(toMs(start))
-            .toZonedDateTimeISO(timeZone)
-            .toPlainDate();
-        const endDate = Temporal.Instant.fromEpochMilliseconds(toMs(end))
-            .toZonedDateTimeISO(timeZone)
-            .toPlainDate();
-        return startDate.until(endDate, { largestUnit: "day" }).days + 1;
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const a = parseUnixEpochInterval(aStart, aEnd);
+        const b = parseUnixEpochInterval(bStart, bEnd);
+        if (a === null || b === null) {
+            return null;
+        }
+        const { start: a1, end: a2 } = a;
+        const { start: b1, end: b2 } = b;
+        const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (!timeZone || epochUnit === null) {
+            return null;
+        }
+        const overlap = halfOpenIntersection({ start: a1, end: a2 }, { start: b1, end: b2 }, (left, right) => left - right);
+        if (overlap === null) {
+            return 0;
+        }
+        // An empty intersection [t, t) (an empty interval strictly inside the other) holds no instant,
+        // so it holds no date.
+        if (overlap.start === overlap.end) {
+            return 0;
+        }
+        const first = unixEpochToInstant(overlap.start, epochUnit);
+        const afterLast = unixEpochToInstant(overlap.end, epochUnit);
+        if (first === null || afterLast === null) {
+            return null;
+        }
+        try {
+            // The last instant the half-open intersection holds is one nanosecond before its end, so the
+            // closed local-date count runs to there.
+            return countZonedLocalDates(first.toZonedDateTimeISO(timeZone), afterLast.toZonedDateTimeISO(timeZone).subtract({ nanoseconds: 1 }));
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/unix/interval/intervalSplitAtUnix.d.ts

@@ -2,23 +2,28 @@
  * Split a Unix epoch interval at arbitrary `points`, producing consecutive sub-intervals.
  *
  * - `points` need not be sorted — they are sorted internally before splitting.
- * - Points outside `[start, end]` are dropped; they cannot introduce a boundary that isn't
- *   inside the interval.
+ * - Points before `start` or after `end` are dropped; they cannot introduce a boundary that
+ *   isn't inside the interval.
  * - Points exactly on `start` or `end` are dropped too — they would only produce a
  *   zero-length sub-interval at the edge.
  * - Duplicate points collapse to a single boundary.
+ * - Returns consecutive half-open `[start, end)` records, the same tiling as `splitIntervalAt`:
+ *   each record's `end` is the next record's `start` and belongs only to that next record, so the
+ *   pieces share no value and together cover `[start, end)` exactly once.
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
- * - Returns `[]` when `points` is not an array, when any element is not a finite number (or
- *   numeric string), or on invalid input (non-finite/non-integer start/end, `start > end`).
+ * - Returns `[]` when `points` is not an array, or when `start`, `end` or any point is not a safe
+ *   integer (or numeric string of one) — fractions, empty strings and values beyond ±(2^53 − 1)
+ *   are invalid even when they would fall outside the interval — or when `start > end`.
  *
- * @param start Unix epoch value (seconds or milliseconds) — interval start
- * @param end Unix epoch value (seconds or milliseconds) — interval end
+ * @param start Unix epoch value, in the one unit all epoch arguments share — interval start
+ * @param end Unix epoch value, in the one unit all epoch arguments share — interval end
  * @param points array of Unix epoch values to split at
  * @returns array of `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalSplitAtUnix(0, 100000, [50000]) // [{ start: 0, end: 50000 }, { start: 50000, end: 100000 }]
  * @example intervalSplitAtUnix(0, 100000, []) // [{ start: 0, end: 100000 }]
  * @example intervalSplitAtUnix(NaN, 100000, [50000]) // []
+ * @example intervalSplitAtUnix(0, 100000, [50000.5]) // [] (fractional point)
  */
 export declare function intervalSplitAtUnix(start: number | string, end: number | string, points: Array<number | string>): Array<{
     start: number;

package/dist/unix/interval/intervalSplitAtUnix.js

@@ -1,55 +1,62 @@
-import { isValidUnixEpochPair } from "../../internal/resolveUnixTimeZone.js";
+import { parseUnixEpochInterval, parseUnixEpochValue } from "../../internal/index.js";
 /**
  * Split a Unix epoch interval at arbitrary `points`, producing consecutive sub-intervals.
  *
  * - `points` need not be sorted — they are sorted internally before splitting.
- * - Points outside `[start, end]` are dropped; they cannot introduce a boundary that isn't
- *   inside the interval.
+ * - Points before `start` or after `end` are dropped; they cannot introduce a boundary that
+ *   isn't inside the interval.
  * - Points exactly on `start` or `end` are dropped too — they would only produce a
  *   zero-length sub-interval at the edge.
  * - Duplicate points collapse to a single boundary.
+ * - Returns consecutive half-open `[start, end)` records, the same tiling as `splitIntervalAt`:
+ *   each record's `end` is the next record's `start` and belongs only to that next record, so the
+ *   pieces share no value and together cover `[start, end)` exactly once.
  * - Returns `[{ start, end }]` (the whole interval, unsplit) when no valid in-range point remains.
- * - Returns `[]` when `points` is not an array, when any element is not a finite number (or
- *   numeric string), or on invalid input (non-finite/non-integer start/end, `start > end`).
+ * - Returns `[]` when `points` is not an array, or when `start`, `end` or any point is not a safe
+ *   integer (or numeric string of one) — fractions, empty strings and values beyond ±(2^53 − 1)
+ *   are invalid even when they would fall outside the interval — or when `start > end`.
  *
- * @param start Unix epoch value (seconds or milliseconds) — interval start
- * @param end Unix epoch value (seconds or milliseconds) — interval end
+ * @param start Unix epoch value, in the one unit all epoch arguments share — interval start
+ * @param end Unix epoch value, in the one unit all epoch arguments share — interval end
  * @param points array of Unix epoch values to split at
  * @returns array of `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalSplitAtUnix(0, 100000, [50000]) // [{ start: 0, end: 50000 }, { start: 50000, end: 100000 }]
  * @example intervalSplitAtUnix(0, 100000, []) // [{ start: 0, end: 100000 }]
  * @example intervalSplitAtUnix(NaN, 100000, [50000]) // []
+ * @example intervalSplitAtUnix(0, 100000, [50000.5]) // [] (fractional point)
  */
 export function intervalSplitAtUnix(start, end, points) {
-    if (!Array.isArray(points)) {
-        return [];
-    }
-    if (typeof start !== "number" && typeof start !== "string") {
-        return [];
-    }
-    if (typeof end !== "number" && typeof end !== "string") {
-        return [];
+    try {
+        if (!Array.isArray(points)) {
+            return [];
+        }
+        const interval = parseUnixEpochInterval(start, end);
+        if (interval === null) {
+            return [];
+        }
+        const { start: startMs, end: endMs } = interval;
+        const parsedPoints = [];
+        for (const point of points) {
+            const parsed = parseUnixEpochValue(point);
+            if (parsed === null) {
+                return [];
+            }
+            parsedPoints.push(parsed);
+        }
+        const inRangePoints = parsedPoints.filter((point) => point > startMs && point < endMs);
+        inRangePoints.sort((a, b) => a - b);
+        const uniquePoints = inRangePoints.filter((point, index) => index === 0 || point !== inRangePoints[index - 1]);
+        const boundaries = [startMs, ...uniquePoints, endMs];
+        const result = [];
+        for (let i = 0; i < boundaries.length - 1; i++) {
+            result.push({ start: boundaries[i], end: boundaries[i + 1] });
+        }
+        return result;
     }
-    const startMs = typeof start === "number" ? start : Number(start);
-    const endMs = typeof end === "number" ? end : Number(end);
-    if (!isValidUnixEpochPair(startMs, endMs) || startMs > endMs) {
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
-    if (!points.every((point) => typeof point === "number" || typeof point === "string")) {
-        return [];
-    }
-    const parsedPoints = points.map((point) => typeof point === "number" ? point : Number(point));
-    if (!parsedPoints.every((point) => Number.isFinite(point))) {
-        return [];
-    }
-    const inRangePoints = parsedPoints.filter((point) => point > startMs && point < endMs);
-    inRangePoints.sort((a, b) => a - b);
-    const uniquePoints = inRangePoints.filter((point, index) => index === 0 || point !== inRangePoints[index - 1]);
-    const boundaries = [startMs, ...uniquePoints, endMs];
-    const result = [];
-    for (let i = 0; i < boundaries.length - 1; i++) {
-        result.push({ start: boundaries[i], end: boundaries[i + 1] });
-    }
-    return result;
 }

package/dist/unix/interval/intervalUnionUnix.d.ts

@@ -1,20 +1,26 @@
 /**
- * Return the combined span of two Unix epoch intervals, or null when they are disjoint.
+ * Return the combined span of two half-open Unix epoch intervals `[start, end)`, or null when
+ * their union is not one non-empty span.
  *
  * - Compares numeric Unix epoch values directly.
- * - Overlapping intervals return their merged span.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and ARE merged.
+ * - The result is the single run `mergeIntervalsUnix([a, b])` produces, the same rule as
+ *   `mergeIntervals`. Overlapping intervals return their merged span.
+ * - Touching intervals (e.g. `aEnd === bStart`) leave no gap between them and ARE merged.
+ * - An empty interval (`start === end`) holds no instant, so it never changes the result: with a
+ *   non-empty interval the answer is that interval, and two empty intervals give `null`.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (non-numeric types, non-finite values).
+ * - Returns `null` on invalid input: non-numeric types, empty strings, and values that are not
+ *   safe integers (fractions, `NaN`, `±Infinity`, beyond ±(2^53 − 1)).
  *
- * @param aStart Unix epoch value (seconds or milliseconds) — first interval start
- * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
- * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
- * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
+ * @param aStart Unix epoch value, in the one unit all epoch arguments share — first interval start
+ * @param aEnd Unix epoch value, in the one unit all epoch arguments share — first interval end
+ * @param bStart Unix epoch value, in the one unit all epoch arguments share — second interval start
+ * @param bEnd Unix epoch value, in the one unit all epoch arguments share — second interval end
  * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
  *
  * @example intervalUnionUnix(0, 1700000000, 1000000, 2000000) // { start: 0, end: 1700000000 }
- * @example intervalUnionUnix(0, 1000000, 1000000, 2000000) // { start: 0, end: 2000000 }
+ * @example intervalUnionUnix(0, 1000000, 1000000, 2000000) // { start: 0, end: 2000000 } (touching)
+ * @example intervalUnionUnix(0, 1000000, 3000000, 3000000) // { start: 0, end: 1000000 } (an empty interval adds nothing)
  * @example intervalUnionUnix(0, 1000000, 1000001, 2000000) // null
  * @example intervalUnionUnix(NaN, 1700000000, 1000000, 2000000) // null
  * @example intervalUnionUnix("0", "1700000000", "1000000", "2000000") // { start: 0, end: 1700000000 }

package/dist/unix/interval/intervalUnionUnix.js

@@ -1,58 +1,36 @@
+import { halfOpenUnion, parseUnixEpochIntervalPair } from "../../internal/index.js";
 /**
- * Return the combined span of two Unix epoch intervals, or null when they are disjoint.
+ * Return the combined span of two half-open Unix epoch intervals `[start, end)`, or null when
+ * their union is not one non-empty span.
  *
  * - Compares numeric Unix epoch values directly.
- * - Overlapping intervals return their merged span.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and ARE merged.
+ * - The result is the single run `mergeIntervalsUnix([a, b])` produces, the same rule as
+ *   `mergeIntervals`. Overlapping intervals return their merged span.
+ * - Touching intervals (e.g. `aEnd === bStart`) leave no gap between them and ARE merged.
+ * - An empty interval (`start === end`) holds no instant, so it never changes the result: with a
+ *   non-empty interval the answer is that interval, and two empty intervals give `null`.
  * - Returns `null` if either interval is invalid (`start > end`).
- * - Returns `null` on invalid input (non-numeric types, non-finite values).
+ * - Returns `null` on invalid input: non-numeric types, empty strings, and values that are not
+ *   safe integers (fractions, `NaN`, `±Infinity`, beyond ±(2^53 − 1)).
  *
- * @param aStart Unix epoch value (seconds or milliseconds) — first interval start
- * @param aEnd Unix epoch value (seconds or milliseconds) — first interval end
- * @param bStart Unix epoch value (seconds or milliseconds) — second interval start
- * @param bEnd Unix epoch value (seconds or milliseconds) — second interval end
+ * @param aStart Unix epoch value, in the one unit all epoch arguments share — first interval start
+ * @param aEnd Unix epoch value, in the one unit all epoch arguments share — first interval end
+ * @param bStart Unix epoch value, in the one unit all epoch arguments share — second interval start
+ * @param bEnd Unix epoch value, in the one unit all epoch arguments share — second interval end
  * @returns `{ start, end }` with the merged span, or null on invalid input / disjoint intervals
  *
  * @example intervalUnionUnix(0, 1700000000, 1000000, 2000000) // { start: 0, end: 1700000000 }
- * @example intervalUnionUnix(0, 1000000, 1000000, 2000000) // { start: 0, end: 2000000 }
+ * @example intervalUnionUnix(0, 1000000, 1000000, 2000000) // { start: 0, end: 2000000 } (touching)
+ * @example intervalUnionUnix(0, 1000000, 3000000, 3000000) // { start: 0, end: 1000000 } (an empty interval adds nothing)
  * @example intervalUnionUnix(0, 1000000, 1000001, 2000000) // null
  * @example intervalUnionUnix(NaN, 1700000000, 1000000, 2000000) // null
  * @example intervalUnionUnix("0", "1700000000", "1000000", "2000000") // { start: 0, end: 1700000000 }
  */
 export function intervalUnionUnix(aStart, aEnd, bStart, bEnd) {
-    if (typeof aStart !== "number" && typeof aStart !== "string") {
+    const pair = parseUnixEpochIntervalPair(aStart, aEnd, bStart, bEnd);
+    if (pair === null) {
         return null;
     }
-    if (typeof aEnd !== "number" && typeof aEnd !== "string") {
-        return null;
-    }
-    if (typeof bStart !== "number" && typeof bStart !== "string") {
-        return null;
-    }
-    if (typeof bEnd !== "number" && typeof bEnd !== "string") {
-        return null;
-    }
-    const a1 = typeof aStart === "number" ? aStart : Number(aStart);
-    const a2 = typeof aEnd === "number" ? aEnd : Number(aEnd);
-    const b1 = typeof bStart === "number" ? bStart : Number(bStart);
-    const b2 = typeof bEnd === "number" ? bEnd : Number(bEnd);
-    if (!Number.isFinite(a1) ||
-        !Number.isFinite(a2) ||
-        !Number.isFinite(b1) ||
-        !Number.isFinite(b2)) {
-        return null;
-    }
-    if (a1 > a2) {
-        return null;
-    }
-    if (b1 > b2) {
-        return null;
-    }
-    if (a2 < b1 || b2 < a1) {
-        return null;
-    }
-    return {
-        start: Math.min(a1, b1),
-        end: Math.max(a2, b2),
-    };
+    // One merged run, or null when a gap (or no instant at all) leaves no single span.
+    return halfOpenUnion(pair[0], pair[1], (left, right) => left - right);
 }

package/dist/unix/interval/intervalXorAllUnix.d.ts

@@ -3,20 +3,22 @@
  * values covered by an odd number of the input intervals.
  *
  * - List-form generalization of `intervalXorUnix`, which is pairwise only.
- * - Implemented as a coverage sweep: each interval contributes a `+1` at its start and a `-1`
- *   one epoch unit after its end; the result is every maximal run where the running coverage
- *   count is odd. For two intervals this reduces to exactly `intervalXorUnix`'s pairwise result.
+ * - Intervals are half-open `[start, end)`. The result is every maximal run where the coverage
+ *   count is odd, so touching runs join and an empty interval (`start === end`) changes nothing.
+ *   Every boundary is an input's own `start` or `end`; none is stepped by an epoch unit. For two
+ *   intervals this is exactly `intervalXorUnix`'s pairwise result.
  * - Order of the input list does not matter; the result is sorted by start.
  * - Returns `[]` for an empty list, and `[]` when every value is covered an even number of
  *   times (e.g. two identical intervals cancel out).
  * - Returns `[]` when `intervals` is not an array, when any element is not a
- *   `{ start, end }` record of finite numeric (or numeric-string) values, or when any element
- *   has `start > end`.
+ *   `{ start, end }` record of safe-integer (or numeric-string) values — fractions, empty
+ *   strings and values beyond ±(2^53 − 1) are invalid — or when any element has `start > end`.
  *
  * @param intervals array of `{ start, end }` records
  * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
  *
- * @example intervalXorAllUnix([{ start: 0, end: 1500000000 }, { start: 1400000000, end: 1700000000 }]) // [{ start: 0, end: 1399999999 }, { start: 1500000001, end: 1700000000 }]
+ * @example intervalXorAllUnix([{ start: 0, end: 1500000000 }, { start: 1400000000, end: 1700000000 }]) // [{ start: 0, end: 1400000000 }, { start: 1500000000, end: 1700000000 }]
+ * @example intervalXorAllUnix([{ start: 0, end: 5 }, { start: 5, end: 10 }]) // [{ start: 0, end: 10 }] (touching runs join)
  * @example intervalXorAllUnix([]) // []
  */
 export declare function intervalXorAllUnix(intervals: Array<{