@northguild/gmt 1.14.2

package/dist/unix/interval/intervalDifferenceUnix.js

@@ -0,0 +1,57 @@
+/**
+ * Return the portion(s) of interval A not covered by interval B.
+ *
+ * - Compares numeric Unix epoch values directly.
+ * - Returns `[]` when B fully covers A.
+ * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns `[]` if either interval is invalid (`start > end`).
+ * - Returns `[]` on invalid input (non-numeric types, non-finite values).
+ *
+ * @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
+ * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
+ *
+ * @example intervalDifferenceUnix(0, 1700000000, 1500000000, 1600000000) // [{ start: 0, end: 1499999999 }]
+ * @example intervalDifferenceUnix(0, 1700000000, 0, 1700000000) // []
+ * @example intervalDifferenceUnix(NaN, 1700000000, 1500000000, 1600000000) // []
+ */
+export function intervalDifferenceUnix(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 [];
+    }
+    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 [];
+    }
+    if (n1 > n2) {
+        return [];
+    }
+    if (n3 > n4) {
+        return [];
+    }
+    const result = [];
+    // Left piece: A before B starts
+    if (n1 < n3) {
+        const leftEnd = n2 < n3 ? n2 : n3 - 1;
+        if (leftEnd >= n1) {
+            result.push({ start: n1, end: leftEnd });
+        }
+    }
+    // Right piece: A after B ends
+    if (n2 > n4) {
+        result.push({ start: n4 + 1, end: n2 });
+    }
+    return result;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * 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`.
+ * - `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`).
+ *
+ * @param start Unix epoch value (seconds or milliseconds) — interval start
+ * @param end Unix epoch value (seconds or milliseconds) — interval end
+ * @param n number of equal sub-intervals to produce (positive integer)
+ * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalDivideEquallyUnix(0, 90000000, 3) // [{ start: 0, end: 30000000 }, { start: 30000000, end: 60000000 }, { start: 60000000, end: 90000000 }]
+ * @example intervalDivideEquallyUnix(0, 100000000, 3) // [{ start: 0, end: 33333333 }, { start: 33333333, end: 66666667 }, { start: 66666667, end: 100000000 }]
+ * @example intervalDivideEquallyUnix(0, 90000000, 1) // [{ start: 0, end: 90000000 }]
+ * @example intervalDivideEquallyUnix(0, 90000000, 0) // []
+ * @example intervalDivideEquallyUnix(NaN, 90000000, 3) // []
+ */
+export declare function intervalDivideEquallyUnix(start: number | string, end: number | string, n: number): Array<{
+    start: number;
+    end: number;
+}>;

package/dist/unix/interval/intervalDivideEquallyUnix.js

@@ -0,0 +1,54 @@
+import { isValidUnixEpochPair } from "../../internal/resolveUnixTimeZone.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`.
+ * - `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`).
+ *
+ * @param start Unix epoch value (seconds or milliseconds) — interval start
+ * @param end Unix epoch value (seconds or milliseconds) — interval end
+ * @param n number of equal sub-intervals to produce (positive integer)
+ * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalDivideEquallyUnix(0, 90000000, 3) // [{ start: 0, end: 30000000 }, { start: 30000000, end: 60000000 }, { start: 60000000, end: 90000000 }]
+ * @example intervalDivideEquallyUnix(0, 100000000, 3) // [{ start: 0, end: 33333333 }, { start: 33333333, end: 66666667 }, { start: 66666667, end: 100000000 }]
+ * @example intervalDivideEquallyUnix(0, 90000000, 1) // [{ start: 0, end: 90000000 }]
+ * @example intervalDivideEquallyUnix(0, 90000000, 0) // []
+ * @example intervalDivideEquallyUnix(NaN, 90000000, 3) // []
+ */
+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 [];
+    }
+    const startMs = typeof start === "number" ? start : Number(start);
+    const endMs = typeof end === "number" ? end : Number(end);
+    if (!isValidUnixEpochPair(startMs, endMs) || startMs > endMs) {
+        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

@@ -0,0 +1,22 @@
+/**
+ * Return true when interval B is fully contained within interval A — every instant of B
+ * falls within A.
+ *
+ * - Compares numeric Unix epoch values directly.
+ * - 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).
+ *
+ * @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
+ * @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(1500000000, 1600000000, 0, 1700000000) // false
+ * @example intervalEngulfsUnix(NaN, 1700000000, 1500000000, 1600000000) // false
+ */
+export declare function intervalEngulfsUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): boolean;

package/dist/unix/interval/intervalEngulfsUnix.js

@@ -0,0 +1,46 @@
+/**
+ * Return true when interval B is fully contained within interval A — every instant of B
+ * falls within A.
+ *
+ * - Compares numeric Unix epoch values directly.
+ * - 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).
+ *
+ * @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
+ * @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(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;
+}

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

@@ -0,0 +1,37 @@
+import type { Overflow } from "../../types/index.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
+ *   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.
+ * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
+ *   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).
+ *
+ * @param value Unix epoch value (seconds or milliseconds)
+ * @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")
+ * @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(NaN, "P1D", "start") // null
+ */
+export declare function intervalFromDurationUnix(value: number | string, duration: string, anchor: "start" | "end", options?: {
+    epochUnit?: "seconds" | "milliseconds";
+    timeZone?: string;
+    overflow?: Overflow;
+}): {
+    start: number;
+    end: number;
+} | null;

package/dist/unix/interval/intervalFromDurationUnix.js

@@ -0,0 +1,73 @@
+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";
+/**
+ * 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
+ *   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.
+ * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
+ *   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).
+ *
+ * @param value Unix epoch value (seconds or milliseconds)
+ * @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")
+ * @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(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) {
+            return null;
+        }
+        const toEpoch = (zdt) => epochUnit === "seconds"
+            ? Math.floor(zdt.epochMilliseconds / 1000)
+            : zdt.epochMilliseconds;
+        return { start: toEpoch(start), end: toEpoch(end) };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Return the overlapping span of two Unix epoch intervals, 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.
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (non-numeric types, non-finite values).
+ *
+ * @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
+ * @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(NaN, 1700000000, 1000000, 2000000) // null
+ * @example intervalIntersectionUnix("0", "1700000000", "1000000", "2000000") // { start: 1000000, end: 1700000000 }
+ */
+export declare function intervalIntersectionUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): {
+    start: number;
+    end: number;
+} | null;

package/dist/unix/interval/intervalIntersectionUnix.js

@@ -0,0 +1,57 @@
+/**
+ * Return the overlapping span of two Unix epoch intervals, 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.
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (non-numeric types, non-finite values).
+ *
+ * @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
+ * @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(NaN, 1700000000, 1000000, 2000000) // null
+ * @example intervalIntersectionUnix("0", "1700000000", "1000000", "2000000") // { start: 1000000, end: 1700000000 }
+ */
+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),
+    };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ * - 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).
+ *
+ * @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`
+ * @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(NaN, 86400000, "hour") // null
+ */
+export declare function intervalLengthUnix(start: number | string, end: number | string, unit: string): number | null;

package/dist/unix/interval/intervalLengthUnix.js

@@ -0,0 +1,39 @@
+import { resolveUnixIntervalPair } from "./resolveUnixIntervalPair.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.
+ * - 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).
+ *
+ * @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`
+ * @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(NaN, 86400000, "hour") // null
+ */
+export function intervalLengthUnix(start, end, unit) {
+    const resolved = resolveUnixIntervalPair(start, end, unit);
+    if (!resolved)
+        return null;
+    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 });
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * 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).
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (non-finite/non-integer epoch values, 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`:
+ *   `const span = intervalIntersectionUnix(aStart, aEnd, bStart, bEnd); span ? intervalCountUnix(span.start, span.end, "day") : 0;`
+ *
+ * @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 options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA, default: system timeZone)
+ * @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, 86400000, 172800000, 259200000, { timeZone: "UTC" }) // 0 (disjoint)
+ * @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";
+    timeZone?: string;
+}): number | null;

package/dist/unix/interval/intervalOverlappingDaysUnix.js

@@ -0,0 +1,89 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveUnixTimeZone } from "../../internal/resolveUnixTimeZone.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).
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (non-finite/non-integer epoch values, 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`:
+ *   `const span = intervalIntersectionUnix(aStart, aEnd, bStart, bEnd); span ? intervalCountUnix(span.start, span.end, "day") : 0;`
+ *
+ * @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 options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA, default: system timeZone)
+ * @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, 86400000, 172800000, 259200000, { timeZone: "UTC" }) // 0 (disjoint)
+ * @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;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * 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 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 `[{ 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`).
+ *
+ * @param start Unix epoch value (seconds or milliseconds) — interval start
+ * @param end Unix epoch value (seconds or milliseconds) — 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]) // []
+ */
+export declare function intervalSplitAtUnix(start: number | string, end: number | string, points: Array<number | string>): Array<{
+    start: number;
+    end: number;
+}>;