@northguild/gmt 1.14.2 → 1.16.0

package/dist/unix/interval/intervalDivideEquallyUnix.js

@@ -1,19 +1,32 @@
-import { isValidUnixEpochPair } from "../../internal/resolveUnixTimeZone.js";
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
+import { parseUnixEpochInterval } from "../../internal/index.js";
+import { divisionBoundary } from "../../internal/divisionBoundary.js";
+import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js";
 /**
  * Split a Unix epoch 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 as plain numeric arithmetic on the epoch values — no timeZone is
- *   involved, so the split is exact whenever the total divides evenly by `n`.
+ * - Returns an array of `n` half-open `[start, end)` records that tile the original interval: 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.
+ * - Each boundary is `start + round((end - start) · i / n)` in integers of the arguments' own epoch
+ *   unit (there is no `epochUnit` option: seconds in give seconds out, milliseconds give
+ *   milliseconds), taken in `bigint` so no product past 2^53 loses a unit: the split is exact
+ *   whenever the total divides evenly by `n`, and within half a unit of the exact cut otherwise (an
+ *   exact half rounds up). No time zone is involved.
  * - `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 (non-finite/non-integer
- *   start/end, `start > end`).
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals, each
+ *   an empty `[start, start)` that holds no instant.
+ * - Returns `[]` when `n` is not a positive integer, or on invalid input (`start`/`end` that is
+ *   not a safe integer or numeric string of one — fractions, empty strings and values beyond
+ *   ±(2^53 − 1) are invalid — or `start > end`).
+ * - `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 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 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 intervalDivideEquallyUnix(0, 90000000, 3) // [{ start: 0, end: 30000000 }, { start: 30000000, end: 60000000 }, { start: 60000000, end: 90000000 }]
@@ -21,34 +34,42 @@ import { isValidUnixEpochPair } from "../../internal/resolveUnixTimeZone.js";
  * @example intervalDivideEquallyUnix(0, 90000000, 1) // [{ start: 0, end: 90000000 }]
  * @example intervalDivideEquallyUnix(0, 90000000, 0) // []
  * @example intervalDivideEquallyUnix(NaN, 90000000, 3) // []
+ * @example intervalDivideEquallyUnix(0, 90000000, 3, { maxPieces: 2 }) // [] (3 pieces exceed the limit)
+ * @example intervalDivideEquallyUnix(0, 90000000, 3, { maxPieces: 3 }) // [{ start: 0, end: 30000000 }, { start: 30000000, end: 60000000 }, { start: 60000000, end: 90000000 }]
  */
-export function intervalDivideEquallyUnix(start, end, n) {
-    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
-        return [];
-    }
-    if (typeof start !== "number" && typeof start !== "string") {
-        return [];
-    }
-    if (typeof end !== "number" && typeof end !== "string") {
-        return [];
+export function intervalDivideEquallyUnix(start, end, n, options) {
+    try {
+        if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+            return [];
+        }
+        const maxPieces = resolveMaxPieces(options);
+        if (maxPieces === null || exceedsPieceLimit(n, maxPieces)) {
+            return [];
+        }
+        const interval = parseUnixEpochInterval(start, end);
+        if (interval === null) {
+            return [];
+        }
+        const { start: startMs, end: endMs } = interval;
+        if (startMs === endMs) {
+            return Array.from({ length: n }, () => ({ start: startMs, end: endMs }));
+        }
+        // Integer milliseconds in bigint: a span near ±8.64e15 times `i` passes 2^53.
+        const totalMs = BigInt(endMs) - BigInt(startMs);
+        const boundaries = [startMs];
+        for (let i = 1; i < n; i++) {
+            boundaries.push(Number(BigInt(startMs) + divisionBoundary(totalMs, i, n)));
+        }
+        boundaries.push(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 (startMs === endMs) {
-        return Array.from({ length: n }, () => ({ start: startMs, end: endMs }));
-    }
-    const totalMs = endMs - startMs;
-    const boundaries = [startMs];
-    for (let i = 1; i < n; i++) {
-        boundaries.push(startMs + Math.round((totalMs * i) / n));
-    }
-    boundaries.push(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/intervalEngulfsUnix.d.ts

@@ -1,21 +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 falls within A.
  *
  * - Compares numeric Unix epoch values directly.
+ * - B is inside A when the intervals overlap and `aStart <= bStart` and `bEnd <= aEnd`. Both ends
+ *   are exclusive, so B may start at A's start and end at A's end.
+ * - An empty B counts only strictly inside A, the same edge rule as `clampInterval`; at either edge
+ *   of A it returns `false`, and an empty A engulfs nothing.
  * - Equivalent to 4-argument `intervalContainsUnix(aStart, aEnd, bStart, bEnd)`.
  * - Returns `false` if either interval is invalid (`start > end`).
- * - Returns `false` on invalid input (non-numeric types, non-finite values).
+ * - Returns `false` 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) — outer interval start
- * @param aEnd Unix epoch value (seconds or milliseconds) — outer interval end
- * @param bStart Unix epoch value (seconds or milliseconds) — inner interval start
- * @param bEnd Unix epoch value (seconds or milliseconds) — inner interval end
+ * @param aStart Unix epoch value, in the one unit all epoch arguments share — outer interval start
+ * @param aEnd Unix epoch value, in the one unit all epoch arguments share — outer interval end
+ * @param bStart Unix epoch value, in the one unit all epoch arguments share — inner interval start
+ * @param bEnd Unix epoch value, in the one unit all epoch arguments share — inner interval end
  * @returns true if B is fully contained in A, or false on invalid input
  *
  * @example intervalEngulfsUnix(0, 1700000000, 1500000000, 1600000000) // true
  * @example intervalEngulfsUnix(0, 1700000000, 0, 1700000000) // true (equal intervals)
  * @example intervalEngulfsUnix(0, 1700000000, 0, 1500000000) // true
+ * @example intervalEngulfsUnix(0, 1700000000, 1700000000, 1700000000) // false (empty B at A's end)
  * @example intervalEngulfsUnix(1500000000, 1600000000, 0, 1700000000) // false
  * @example intervalEngulfsUnix(NaN, 1700000000, 1500000000, 1600000000) // false
  */

package/dist/unix/interval/intervalEngulfsUnix.js

@@ -1,46 +1,34 @@
+import { halfOpenContainsSpan, parseUnixEpochIntervalPair, } from "../../internal/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 falls within A.
  *
  * - Compares numeric Unix epoch values directly.
+ * - B is inside A when the intervals overlap and `aStart <= bStart` and `bEnd <= aEnd`. Both ends
+ *   are exclusive, so B may start at A's start and end at A's end.
+ * - An empty B counts only strictly inside A, the same edge rule as `clampInterval`; at either edge
+ *   of A it returns `false`, and an empty A engulfs nothing.
  * - Equivalent to 4-argument `intervalContainsUnix(aStart, aEnd, bStart, bEnd)`.
  * - Returns `false` if either interval is invalid (`start > end`).
- * - Returns `false` on invalid input (non-numeric types, non-finite values).
+ * - Returns `false` 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) — outer interval start
- * @param aEnd Unix epoch value (seconds or milliseconds) — outer interval end
- * @param bStart Unix epoch value (seconds or milliseconds) — inner interval start
- * @param bEnd Unix epoch value (seconds or milliseconds) — inner interval end
+ * @param aStart Unix epoch value, in the one unit all epoch arguments share — outer interval start
+ * @param aEnd Unix epoch value, in the one unit all epoch arguments share — outer interval end
+ * @param bStart Unix epoch value, in the one unit all epoch arguments share — inner interval start
+ * @param bEnd Unix epoch value, in the one unit all epoch arguments share — inner interval end
  * @returns true if B is fully contained in A, or false on invalid input
  *
  * @example intervalEngulfsUnix(0, 1700000000, 1500000000, 1600000000) // true
  * @example intervalEngulfsUnix(0, 1700000000, 0, 1700000000) // true (equal intervals)
  * @example intervalEngulfsUnix(0, 1700000000, 0, 1500000000) // true
+ * @example intervalEngulfsUnix(0, 1700000000, 1700000000, 1700000000) // false (empty B at A's end)
  * @example intervalEngulfsUnix(1500000000, 1600000000, 0, 1700000000) // false
  * @example intervalEngulfsUnix(NaN, 1700000000, 1500000000, 1600000000) // false
  */
 export function intervalEngulfsUnix(aStart, aEnd, bStart, bEnd) {
-    if ((typeof aStart !== "number" && typeof aStart !== "string") ||
-        (typeof aEnd !== "number" && typeof aEnd !== "string") ||
-        (typeof bStart !== "number" && typeof bStart !== "string") ||
-        (typeof bEnd !== "number" && typeof bEnd !== "string")) {
-        return false;
-    }
-    const n1 = typeof aStart === "number" ? aStart : Number(aStart);
-    const n2 = typeof aEnd === "number" ? aEnd : Number(aEnd);
-    const n3 = typeof bStart === "number" ? bStart : Number(bStart);
-    const n4 = typeof bEnd === "number" ? bEnd : Number(bEnd);
-    if (!Number.isFinite(n1) ||
-        !Number.isFinite(n2) ||
-        !Number.isFinite(n3) ||
-        !Number.isFinite(n4)) {
-        return false;
-    }
-    if (n1 > n2) {
-        return false;
-    }
-    if (n3 > n4) {
-        return false;
-    }
-    return n1 <= n3 && n4 <= n2;
+    const pair = parseUnixEpochIntervalPair(aStart, aEnd, bStart, bEnd);
+    // B overlaps A, and B's start and exclusive end both lie within A's bounds.
+    return (pair !== null &&
+        halfOpenContainsSpan(pair[0], pair[1], (left, right) => left - right));
 }

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

@@ -1,10 +1,12 @@
 import type { Overflow } from "../../types/index.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Construct a Unix epoch 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` (system timeZone by default, consistent with `addUnix`), adds/subtracts
+ * - Converts to `ZonedDateTime` in `timeZone` (`"UTC"` by default, consistent with `addUnix`; `"local"`
+ *   is the system zone), adds/subtracts
  *   the duration there, then converts back to epoch — 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.
@@ -12,23 +14,25 @@ import type { Overflow } from "../../types/index.js";
  *   happens, mirroring `intervalIntersectionUnix`'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 (non-finite/non-integer `value`, invalid `duration`, an `anchor`
- *   other than `"start"`/`"end"`, or an invalid/unavailable timeZone).
+ * - Returns null on invalid input (a `value` that is not a safe integer or numeric string of one —
+ *   fractions, empty strings and values beyond ±(2^53 − 1) are invalid — invalid `duration`, an
+ *   `anchor` other than `"start"`/`"end"`, or an invalid/unavailable timeZone).
  *
- * @param value Unix epoch value (seconds or milliseconds)
+ * @param value Unix epoch value (seconds or milliseconds): a safe integer or a digit string
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject")
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), overflow ("constrain" | "reject")
  * @returns `{ start, end }` with the constructed span (epoch numbers), or null on invalid input
  *
  * @example intervalFromDurationUnix(1704067200000, "P1D", "start", { timeZone: "UTC" }) // { start: 1704067200000, end: 1704153600000 }
  * @example intervalFromDurationUnix(1704153600000, "P1D", "end", { timeZone: "UTC" }) // { start: 1704067200000, end: 1704153600000 }
  * @example intervalFromDurationUnix(1706659200000, "P1M", "start", { timeZone: "UTC", overflow: "reject" }) // null (Jan 31 + 1 month overflows)
  * @example intervalFromDurationUnix(1704067200000, "-P10D", "start", { timeZone: "UTC" }) // null (inverted span)
+ * @example intervalFromDurationUnix("1704067200", "P1D", "start", { epochUnit: "second" }) // { start: 1704067200, end: 1704153600 } (UTC by default)
  * @example intervalFromDurationUnix(NaN, "P1D", "start") // null
  */
 export declare function intervalFromDurationUnix(value: number | string, duration: string, anchor: "start" | "end", options?: {
-    epochUnit?: "seconds" | "milliseconds";
+    epochUnit?: UnixUnit;
     timeZone?: string;
     overflow?: Overflow;
 }): {

package/dist/unix/interval/intervalFromDurationUnix.js

@@ -1,13 +1,17 @@
+// 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 { resolveUnixTimeZone } from "../../internal/resolveUnixTimeZone.js";
+import { addToZoned, resolveOverflow, subtractFromZoned } from "../../internal/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Construct a Unix epoch 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` (system timeZone by default, consistent with `addUnix`), adds/subtracts
+ * - Converts to `ZonedDateTime` in `timeZone` (`"UTC"` by default, consistent with `addUnix`; `"local"`
+ *   is the system zone), adds/subtracts
  *   the duration there, then converts back to epoch — 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.
@@ -15,59 +19,67 @@ import { resolveUnixTimeZone } from "../../internal/resolveUnixTimeZone.js";
  *   happens, mirroring `intervalIntersectionUnix`'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 (non-finite/non-integer `value`, invalid `duration`, an `anchor`
- *   other than `"start"`/`"end"`, or an invalid/unavailable timeZone).
+ * - Returns null on invalid input (a `value` that is not a safe integer or numeric string of one —
+ *   fractions, empty strings and values beyond ±(2^53 − 1) are invalid — invalid `duration`, an
+ *   `anchor` other than `"start"`/`"end"`, or an invalid/unavailable timeZone).
  *
- * @param value Unix epoch value (seconds or milliseconds)
+ * @param value Unix epoch value (seconds or milliseconds): a safe integer or a digit string
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject")
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), overflow ("constrain" | "reject")
  * @returns `{ start, end }` with the constructed span (epoch numbers), or null on invalid input
  *
  * @example intervalFromDurationUnix(1704067200000, "P1D", "start", { timeZone: "UTC" }) // { start: 1704067200000, end: 1704153600000 }
  * @example intervalFromDurationUnix(1704153600000, "P1D", "end", { timeZone: "UTC" }) // { start: 1704067200000, end: 1704153600000 }
  * @example intervalFromDurationUnix(1706659200000, "P1M", "start", { timeZone: "UTC", overflow: "reject" }) // null (Jan 31 + 1 month overflows)
  * @example intervalFromDurationUnix(1704067200000, "-P10D", "start", { timeZone: "UTC" }) // null (inverted span)
+ * @example intervalFromDurationUnix("1704067200", "P1D", "start", { epochUnit: "second" }) // { start: 1704067200, end: 1704153600 } (UTC by default)
  * @example intervalFromDurationUnix(NaN, "P1D", "start") // null
  */
 export function intervalFromDurationUnix(value, duration, anchor, options) {
-    if (typeof value !== "number" && typeof value !== "string") {
-        return null;
-    }
-    const valueMs = typeof value === "number" ? value : Number(value);
-    if (!Number.isFinite(valueMs) || !Number.isInteger(valueMs)) {
-        return null;
-    }
-    if (!isValidDuration(duration)) {
-        return null;
-    }
-    if (anchor !== "start" && anchor !== "end") {
-        return null;
-    }
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    const timeZone = resolveUnixTimeZone(options?.timeZone);
-    if (!timeZone) {
-        return null;
-    }
     try {
-        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? valueMs * 1000 : valueMs);
-        const point = instant.toZonedDateTimeISO(timeZone);
-        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) {
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        if (!isValidDuration(duration)) {
+            return null;
+        }
+        if (anchor !== "start" && anchor !== "end") {
+            return null;
+        }
+        const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (!timeZone || epochUnit === null) {
+            return null;
+        }
+        const instant = unixEpochToInstant(value, epochUnit);
+        if (instant === null) {
+            return null;
+        }
+        try {
+            const point = instant.toZonedDateTimeISO(timeZone);
+            const dur = Temporal.Duration.from(duration);
+            const overflow = resolveOverflow(options?.overflow);
+            const other = anchor === "start"
+                ? addToZoned(point, dur, { overflow })
+                : subtractFromZoned(point, 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: toUnixEpoch(start, epochUnit),
+                end: toUnixEpoch(end, epochUnit),
+            };
+        }
+        catch {
             return null;
         }
-        const toEpoch = (zdt) => epochUnit === "seconds"
-            ? Math.floor(zdt.epochMilliseconds / 1000)
-            : zdt.epochMilliseconds;
-        return { start: toEpoch(start), end: toEpoch(end) };
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -1,22 +1,29 @@
 /**
- * Return the overlapping span of two Unix epoch intervals, or null when they do not overlap.
+ * Return the overlapping span of two half-open Unix epoch intervals `[start, end)`, or null when
+ * they do not overlap.
  *
  * - Compares numeric Unix epoch values directly.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - The result is `[max(aStart, bStart), min(aEnd, bEnd))`, and it exists only when
+ *   `intervalsOverlapUnix` is true — the same rule as `intersectIntervals`.
+ * - Touching intervals (e.g. `aEnd === bStart`) share no instant, because each `end` is excluded,
+ *   and return `null`.
+ * - An empty interval (`start === end`) strictly inside the other returns itself; at either edge,
+ *   or against another empty interval, it returns `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 overlapping span, or null on invalid input / no overlap
  *
- * @example intervalIntersectionUnix(0, 1700000000, 1000000, 2000000) // { start: 1000000, end: 1700000000 }
- * @example intervalIntersectionUnix(0, 1000000, 1000000, 2000000) // { start: 1000000, end: 1000000 }
- * @example intervalIntersectionUnix(0, 1000000, 1000001, 2000000) // null
+ * @example intervalIntersectionUnix(0, 1700000000, 1000000, 2000000) // { start: 1000000, end: 2000000 }
+ * @example intervalIntersectionUnix(0, 1000000, 1000000, 2000000) // null (touching)
+ * @example intervalIntersectionUnix(0, 1000001, 1000000, 2000000) // { start: 1000000, end: 1000001 }
  * @example intervalIntersectionUnix(NaN, 1700000000, 1000000, 2000000) // null
- * @example intervalIntersectionUnix("0", "1700000000", "1000000", "2000000") // { start: 1000000, end: 1700000000 }
+ * @example intervalIntersectionUnix("0", "1700000000", "1000000", "2000000") // { start: 1000000, end: 2000000 }
  */
 export declare function intervalIntersectionUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): {
     start: number;

package/dist/unix/interval/intervalIntersectionUnix.js

@@ -1,57 +1,36 @@
+import { halfOpenIntersection, parseUnixEpochIntervalPair, } from "../../internal/index.js";
 /**
- * Return the overlapping span of two Unix epoch intervals, or null when they do not overlap.
+ * Return the overlapping span of two half-open Unix epoch intervals `[start, end)`, or null when
+ * they do not overlap.
  *
  * - Compares numeric Unix epoch values directly.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - The result is `[max(aStart, bStart), min(aEnd, bEnd))`, and it exists only when
+ *   `intervalsOverlapUnix` is true — the same rule as `intersectIntervals`.
+ * - Touching intervals (e.g. `aEnd === bStart`) share no instant, because each `end` is excluded,
+ *   and return `null`.
+ * - An empty interval (`start === end`) strictly inside the other returns itself; at either edge,
+ *   or against another empty interval, it returns `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 overlapping span, or null on invalid input / no overlap
  *
- * @example intervalIntersectionUnix(0, 1700000000, 1000000, 2000000) // { start: 1000000, end: 1700000000 }
- * @example intervalIntersectionUnix(0, 1000000, 1000000, 2000000) // { start: 1000000, end: 1000000 }
- * @example intervalIntersectionUnix(0, 1000000, 1000001, 2000000) // null
+ * @example intervalIntersectionUnix(0, 1700000000, 1000000, 2000000) // { start: 1000000, end: 2000000 }
+ * @example intervalIntersectionUnix(0, 1000000, 1000000, 2000000) // null (touching)
+ * @example intervalIntersectionUnix(0, 1000001, 1000000, 2000000) // { start: 1000000, end: 1000001 }
  * @example intervalIntersectionUnix(NaN, 1700000000, 1000000, 2000000) // null
- * @example intervalIntersectionUnix("0", "1700000000", "1000000", "2000000") // { start: 1000000, end: 1700000000 }
+ * @example intervalIntersectionUnix("0", "1700000000", "1000000", "2000000") // { start: 1000000, end: 2000000 }
  */
 export function intervalIntersectionUnix(aStart, aEnd, bStart, bEnd) {
-    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.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.max(a1, b1),
-        end: Math.min(a2, b2),
-    };
+    const pair = parseUnixEpochIntervalPair(aStart, aEnd, bStart, bEnd);
+    // Null unless `aStart < bEnd && bStart < aEnd` (so touching intervals, or an empty interval at
+    // an edge, give null); otherwise the latest start and earliest end bound the overlap.
+    return pair === null
+        ? null
+        : halfOpenIntersection(pair[0], pair[1], (left, right) => left - right);
 }

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

@@ -1,24 +1,36 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.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 declare function intervalLengthUnix(start: number | string, end: number | string, unit: string): number | null;
+export declare function intervalLengthUnix(start: number | string, end: number | string, unit: string, options?: {
+    epochUnit?: UnixUnit;
+    timeZone?: string;
+}): number | null;