@northguild/gmt 1.15.0 → 1.17.0

package/dist/unix/format/formatUnix.d.ts

@@ -1,5 +1,6 @@
+import type { UnixUnit } from "../validate/index.js";
 export interface FormatUnixOptions extends Intl.DateTimeFormatOptions {
-    epochUnit?: "milliseconds" | "seconds";
+    epochUnit?: UnixUnit;
     timeZone?: string;
     includeTimeZoneName?: boolean;
 }
@@ -8,11 +9,23 @@ export interface FormatUnixOptions extends Intl.DateTimeFormatOptions {
  *
  * - Returns `""` if the input is not a valid unix epoch value for the given `epochUnit`.
  * - `epochUnit` controls whether the input is interpreted as `"milliseconds"` or `"seconds"`; defaults to `"milliseconds"`.
- * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits (no whitespace, `+`,
+ *   decimal point or exponent); `epochUnit` also accepts `"second"` / `"millisecond"`.
+ * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`, `"local"` is the
+ *   system zone, and an unknown zone returns `""` (ECMA-402 throws RangeError for it).
  * - `includeTimeZoneName` appends the localized timezone name when true.
+ * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
+ *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
+ *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
+ *   and `era` alone still gets the date and time defaults.
+ * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
+ *   the japanese calendar and `month: "long"` gave `"R6/2"`), a `long`/`full` `timeStyle` replaced
+ *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
+ *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it.
  *
  * @param value unix epoch value to format (string or number, per `epochUnit`)
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { epochUnit, timeZone, includeTimeZoneName }
  * @returns the formatted date/time string, or "" on invalid input
  *
@@ -20,6 +33,15 @@ export interface FormatUnixOptions extends Intl.DateTimeFormatOptions {
  * @example formatUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
  * @example formatUnix("1710685845", "en-US", { epochUnit: "seconds" }) // "3/17/2024, 2:30:45 PM"
  * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds", includeTimeZoneName: true }) // "3/17/2024, 2:30:45 PM UTC"
+ * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
+ * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatUnix(0, "en-US", { timeZoneName: "short" }) // "1/1/1970, 12:00:00 AM"
+ * @example formatUnix(1710685845000, "en-US", { timeZone: "America/New_Yrok" }) // "" (unknown zone)
+ * @example formatUnix("1710685845000.0") // "" (not a digit string)
+ * @example formatUnix(0, "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
  * @example formatUnix("not-a-number") // ""
+ * @example formatUnix(1710685845000, ["fr-FR", "en-US"], { dateStyle: "long" }) // "17 mars 2024"
  */
-export declare function formatUnix(value: string | number, locale?: string, options?: FormatUnixOptions): string;
+export declare function formatUnix(value: string | number, locale?: string | string[], options?: FormatUnixOptions): string;

package/dist/unix/format/formatUnix.js

@@ -1,35 +1,30 @@
-import { Temporal } from "@js-temporal/polyfill";
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
+import { formatWallClockOrZoned } from "../../internal/instantFormatOptions.js";
 import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
-import { isValidUnixUnit } from "../validate/index.js";
-function parseEpochMs(value, epochUnit) {
-    let n;
-    if (typeof value === "number") {
-        n = value;
-    }
-    else if (typeof value === "string") {
-        const trimmed = value.trim();
-        if (!/^-?\d+$/.test(trimmed))
-            return null;
-        n = Number(trimmed);
-    }
-    else {
-        return null;
-    }
-    if (!Number.isFinite(n))
-        return null;
-    return epochUnit === "seconds" ? n * 1000 : n;
-}
+import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 /**
  * Format a unix epoch value (string or number) as a localized date/time string.
  *
  * - Returns `""` if the input is not a valid unix epoch value for the given `epochUnit`.
  * - `epochUnit` controls whether the input is interpreted as `"milliseconds"` or `"seconds"`; defaults to `"milliseconds"`.
- * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits (no whitespace, `+`,
+ *   decimal point or exponent); `epochUnit` also accepts `"second"` / `"millisecond"`.
+ * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`, `"local"` is the
+ *   system zone, and an unknown zone returns `""` (ECMA-402 throws RangeError for it).
  * - `includeTimeZoneName` appends the localized timezone name when true.
+ * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
+ *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
+ *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
+ *   and `era` alone still gets the date and time defaults.
+ * - **Compatibility:** before 1.16.0 some locales and calendars lost a requested width (ja-JP with
+ *   the japanese calendar and `month: "long"` gave `"R6/2"`), a `long`/`full` `timeStyle` replaced
+ *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
+ *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
+ * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it.
  *
  * @param value unix epoch value to format (string or number, per `epochUnit`)
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { epochUnit, timeZone, includeTimeZoneName }
  * @returns the formatted date/time string, or "" on invalid input
  *
@@ -37,24 +32,43 @@ function parseEpochMs(value, epochUnit) {
  * @example formatUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
  * @example formatUnix("1710685845", "en-US", { epochUnit: "seconds" }) // "3/17/2024, 2:30:45 PM"
  * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds", includeTimeZoneName: true }) // "3/17/2024, 2:30:45 PM UTC"
+ * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "long" }) // "令和6年2月"
+ * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
+ * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
+ * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatUnix(0, "en-US", { timeZoneName: "short" }) // "1/1/1970, 12:00:00 AM"
+ * @example formatUnix(1710685845000, "en-US", { timeZone: "America/New_Yrok" }) // "" (unknown zone)
+ * @example formatUnix("1710685845000.0") // "" (not a digit string)
+ * @example formatUnix(0, "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
  * @example formatUnix("not-a-number") // ""
+ * @example formatUnix(1710685845000, ["fr-FR", "en-US"], { dateStyle: "long" }) // "17 mars 2024"
  */
 export function formatUnix(value, locale, options) {
-    const { epochUnit = "milliseconds", timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
-    if (!isValidUnixUnit(epochUnit))
-        return "";
-    const ms = parseEpochMs(value, epochUnit);
-    if (ms === null)
-        return "";
-    const tz = normalizeTimeZone(timeZone);
     try {
-        const zdt = Temporal.Instant.fromEpochMilliseconds(ms).toZonedDateTimeISO(tz);
-        const out = includeTimeZoneName
-            ? zdt.toLocaleString(locale, intlOptions)
-            : zdt.toPlainDateTime().toLocaleString(locale, intlOptions);
-        return normalizeDateTime(out);
+        // ECMA-402 CoerceOptionsToObject: undefined is defaults; null is a TypeError.
+        if (options === null)
+            return "";
+        const { epochUnit, timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
+        const resolvedUnit = resolveUnixEpochUnit(epochUnit);
+        if (resolvedUnit === null)
+            return "";
+        const instant = unixEpochToInstant(value, resolvedUnit);
+        if (instant === null)
+            return "";
+        const tz = normalizeTimeZone(timeZone);
+        if (!tz)
+            return "";
+        try {
+            const zdt = instant.toZonedDateTimeISO(tz);
+            return normalizeDateTime(formatWallClockOrZoned(zdt, locale, intlOptions, includeTimeZoneName));
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/unix/get/getUnixNow.d.ts

@@ -1,15 +1,21 @@
-import { type UnixUnit } from "../validate/isValidUnixUnit.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Return the current Unix timestamp in either seconds or milliseconds.
  *
  * - Uses Temporal.Now.instant() to get current time.
- * - Defaults to "milliseconds" if no unit specified.
- * - Returns 0 on failure.
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. Seconds floor toward −∞, as POSIX `time_t` counts whole elapsed seconds.
+ * - An explicit `undefined` is the same as omitted. An unknown `epochUnit`, or a non-object
+ *   `options` (such as a bare `"seconds"` string), returns null.
  *
- * @param unit optional unit specifier: "seconds" | "milliseconds"
- * @returns number (unix timestamp)
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @returns the current unix timestamp, or null on invalid options
  *
  * @example getUnixNow() // 1700000000000
- * @example getUnixNow("seconds") // 1700000000
+ * @example getUnixNow({ epochUnit: "seconds" }) // 1700000000
+ * @example getUnixNow({ epochUnit: "minutes" as never }) // null
+ * @example getUnixNow("seconds" as never) // null (options must be an object)
  */
-export declare function getUnixNow(...unitInput: [unit?: UnixUnit]): number;
+export declare function getUnixNow(options?: {
+    epochUnit?: UnixUnit;
+}): number | null;

package/dist/unix/get/getUnixNow.js

@@ -1,28 +1,38 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidUnixUnit } from "../validate/isValidUnixUnit.js";
+import { resolveUnixEpochUnitOptions, toUnixEpoch, } from "../../internal/unixEpochValue.js";
 /**
  * Return the current Unix timestamp in either seconds or milliseconds.
  *
  * - Uses Temporal.Now.instant() to get current time.
- * - Defaults to "milliseconds" if no unit specified.
- * - Returns 0 on failure.
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. Seconds floor toward −∞, as POSIX `time_t` counts whole elapsed seconds.
+ * - An explicit `undefined` is the same as omitted. An unknown `epochUnit`, or a non-object
+ *   `options` (such as a bare `"seconds"` string), returns null.
  *
- * @param unit optional unit specifier: "seconds" | "milliseconds"
- * @returns number (unix timestamp)
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @returns the current unix timestamp, or null on invalid options
  *
  * @example getUnixNow() // 1700000000000
- * @example getUnixNow("seconds") // 1700000000
+ * @example getUnixNow({ epochUnit: "seconds" }) // 1700000000
+ * @example getUnixNow({ epochUnit: "minutes" as never }) // null
+ * @example getUnixNow("seconds" as never) // null (options must be an object)
  */
-export function getUnixNow(...unitInput) {
-    const rawUnit = unitInput.length === 0 ? undefined : unitInput[0];
-    const resolvedUnit = unitInput.length === 0
-        ? "milliseconds"
-        : isValidUnixUnit(String(rawUnit ?? ""))
-            ? rawUnit
-            : "milliseconds";
-    const instant = Temporal.Now.instant();
-    if (resolvedUnit === "seconds") {
-        return Math.floor(instant.epochMilliseconds / 1000);
+export function getUnixNow(options) {
+    try {
+        const epochUnit = resolveUnixEpochUnitOptions(options);
+        if (epochUnit === null) {
+            return null;
+        }
+        try {
+            return toUnixEpoch(Temporal.Now.instant(), epochUnit);
+        }
+        catch {
+            return null;
+        }
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
     }
-    return instant.epochMilliseconds;
 }

package/dist/unix/get/getUnixNowUnit.d.ts

@@ -1,9 +1,11 @@
+import { Temporal } from "@js-temporal/polyfill";
 import type { UnixNowUnit } from "../../types/index.js";
 export type { UnixNowUnit };
 /**
  * Return the requested unit value from the current Unix timestamp in UTC.
  *
- * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond". Temporal units may also be plural ("hours").
+ * - `microsecond` and `nanosecond` are Temporal's 0–999 fields, zero-padded to 3 digits.
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns "" on invalid unit or failure.
  *
@@ -12,6 +14,7 @@ export type { UnixNowUnit };
  *
  * @example getUnixNowUnit("year") // "2024"
  * @example getUnixNowUnit("month") // "02"
+ * @example getUnixNowUnit("months") // "02" (plural unit)
  * @example getUnixNowUnit("invalid") // ""
  */
-export declare function getUnixNowUnit(unit: UnixNowUnit): string;
+export declare function getUnixNowUnit(unit: UnixNowUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>): string;

package/dist/unix/get/getUnixNowUnit.js

@@ -1,12 +1,15 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isoWeekOfYear, zonedNowUnitValue, } from "../../internal/zonedNowUnitValue.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 import { isValidDateTimeUnit } from "../../plain/validate/index.js";
 function isValidUnixNowUnit(unit) {
-    return isValidDateTimeUnit(unit) || ["dayOfWeek"].includes(unit);
+    return isValidDateTimeUnit(unit) || unit === "dayOfWeek";
 }
 /**
  * Return the requested unit value from the current Unix timestamp in UTC.
  *
- * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond". Temporal units may also be plural ("hours").
+ * - `microsecond` and `nanosecond` are Temporal's 0–999 fields, zero-padded to 3 digits.
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns "" on invalid unit or failure.
  *
@@ -15,45 +18,16 @@ function isValidUnixNowUnit(unit) {
  *
  * @example getUnixNowUnit("year") // "2024"
  * @example getUnixNowUnit("month") // "02"
+ * @example getUnixNowUnit("months") // "02" (plural unit)
  * @example getUnixNowUnit("invalid") // ""
  */
 export function getUnixNowUnit(unit) {
-    if (!isValidUnixNowUnit(String(unit ?? "")))
+    const resolved = typeof unit === "string" ? resolveDateTimeUnit(unit) : "";
+    if (!isValidUnixNowUnit(resolved))
         return "";
     try {
         const now = Temporal.Now.instant().toZonedDateTimeISO("UTC");
-        const plainDateTime = now.toPlainDateTime();
-        const plainDate = Temporal.PlainDate.from({
-            year: plainDateTime.year,
-            month: plainDateTime.month,
-            day: plainDateTime.day,
-        });
-        switch (unit) {
-            case "year":
-                return plainDateTime.year.toString();
-            case "month":
-                return plainDateTime.month.toString().padStart(2, "0");
-            case "week":
-                return (plainDate.weekOfYear ?? 0).toString();
-            case "day":
-                return plainDateTime.day.toString().padStart(2, "0");
-            case "dayOfWeek":
-                return now.dayOfWeek.toString();
-            case "hour":
-                return plainDateTime.hour.toString().padStart(2, "0");
-            case "minute":
-                return plainDateTime.minute.toString().padStart(2, "0");
-            case "second":
-                return plainDateTime.second.toString().padStart(2, "0");
-            case "millisecond":
-                return plainDateTime.millisecond.toString().padStart(3, "0");
-            case "microsecond":
-                return (plainDateTime.microsecond ?? 0).toString().padStart(3, "0");
-            case "nanosecond":
-                return (plainDateTime.nanosecond ?? 0).toString().padStart(3, "0");
-            default:
-                return "";
-        }
+        return zonedNowUnitValue(now, resolved, isoWeekOfYear);
     }
     catch {
         return "";

package/dist/unix/index.d.ts

@@ -1,3 +1,4 @@
+export * from "@js-temporal/polyfill";
 export * from "./calculate/index.js";
 export * from "./compare/index.js";
 export * from "./convert/index.js";

package/dist/unix/index.js

@@ -1,3 +1,5 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
 export * from "./calculate/index.js";
 export * from "./compare/index.js";
 export * from "./convert/index.js";

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

@@ -1,22 +1,27 @@
 /**
- * Return true when two Unix intervals are exactly adjacent — one's end equals the other's
- * start minus 1 (no gap, no overlap).
+ * Return true when two half-open Unix intervals `[start, end)` are exactly adjacent — one ends
+ * where the other starts, so they share no value and leave no gap (Allen's "meets", either order).
  *
  * - Compares numeric Unix epoch values directly.
- * - Returns `true` when `aEnd + 1 === bStart` or `bEnd + 1 === aStart`.
- * - Returns `false` when intervals overlap, are disjoint with a gap, or are invalid.
- * - Returns `false` on invalid input (non-numeric types, non-finite values).
+ * - Returns `true` when `aEnd === bStart` or `bEnd === aStart` and neither interval is empty. No
+ *   value is stepped by an epoch unit.
+ * - Returns `false` when intervals overlap, are disjoint with a gap (even one epoch unit), or when
+ *   either is empty (`start === end`): an empty interval abuts nothing.
+ * - 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) — 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 true if intervals are exactly adjacent, or false on invalid input
  *
- * @example intervalAbutsUnix(0, 1500000000, 1500000001, 1700000000) // true
- * @example intervalAbutsUnix(1500000001, 1700000000, 0, 1500000000) // true
- * @example intervalAbutsUnix(0, 1500000000, 1500000002, 1700000000) // false (gap)
+ * @example intervalAbutsUnix(0, 1500000000, 1500000000, 1700000000) // true
+ * @example intervalAbutsUnix(1500000000, 1700000000, 0, 1500000000) // true
+ * @example intervalAbutsUnix(0, 1500000000, 1500000001, 1700000000) // false (one-unit gap)
+ * @example intervalAbutsUnix(0, 1500000000, 1500000000, 1500000000) // false (an empty interval abuts nothing)
  * @example intervalAbutsUnix(0, 1500000001, 1500000000, 1700000000) // false (overlap)
  * @example intervalAbutsUnix(NaN, 1500000000, 1500000001, 1700000000) // false
+ * @example intervalAbutsUnix(0, 1.5, 1.5, 3) // false (fractional epochs)
  */
 export declare function intervalAbutsUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): boolean;

package/dist/unix/interval/intervalAbutsUnix.js

@@ -1,54 +1,36 @@
+import { halfOpenAbuts, parseUnixEpochInterval } from "../../internal/index.js";
 /**
- * Return true when two Unix intervals are exactly adjacent — one's end equals the other's
- * start minus 1 (no gap, no overlap).
+ * Return true when two half-open Unix intervals `[start, end)` are exactly adjacent — one ends
+ * where the other starts, so they share no value and leave no gap (Allen's "meets", either order).
  *
  * - Compares numeric Unix epoch values directly.
- * - Returns `true` when `aEnd + 1 === bStart` or `bEnd + 1 === aStart`.
- * - Returns `false` when intervals overlap, are disjoint with a gap, or are invalid.
- * - Returns `false` on invalid input (non-numeric types, non-finite values).
+ * - Returns `true` when `aEnd === bStart` or `bEnd === aStart` and neither interval is empty. No
+ *   value is stepped by an epoch unit.
+ * - Returns `false` when intervals overlap, are disjoint with a gap (even one epoch unit), or when
+ *   either is empty (`start === end`): an empty interval abuts nothing.
+ * - 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) — 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 true if intervals are exactly adjacent, or false on invalid input
  *
- * @example intervalAbutsUnix(0, 1500000000, 1500000001, 1700000000) // true
- * @example intervalAbutsUnix(1500000001, 1700000000, 0, 1500000000) // true
- * @example intervalAbutsUnix(0, 1500000000, 1500000002, 1700000000) // false (gap)
+ * @example intervalAbutsUnix(0, 1500000000, 1500000000, 1700000000) // true
+ * @example intervalAbutsUnix(1500000000, 1700000000, 0, 1500000000) // true
+ * @example intervalAbutsUnix(0, 1500000000, 1500000001, 1700000000) // false (one-unit gap)
+ * @example intervalAbutsUnix(0, 1500000000, 1500000000, 1500000000) // false (an empty interval abuts nothing)
  * @example intervalAbutsUnix(0, 1500000001, 1500000000, 1700000000) // false (overlap)
  * @example intervalAbutsUnix(NaN, 1500000000, 1500000001, 1700000000) // false
+ * @example intervalAbutsUnix(0, 1.5, 1.5, 3) // false (fractional epochs)
  */
 export function intervalAbutsUnix(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")) {
+    const a = parseUnixEpochInterval(aStart, aEnd);
+    const b = parseUnixEpochInterval(bStart, bEnd);
+    if (a === null || b === null) {
         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;
-    }
-    // aEnd + 1 === bStart
-    if (n2 + 1 === n3) {
-        return true;
-    }
-    // bEnd + 1 === aStart
-    if (n4 + 1 === n1) {
-        return true;
-    }
-    return false;
+    // aEnd === bStart, or bEnd === aStart, between two non-empty intervals.
+    return halfOpenAbuts(a, b, (left, right) => left - right);
 }

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

@@ -1,25 +1,35 @@
 /**
- * Return true when `pointOrStart` falls within the interval `[intervalStart, intervalEnd]`
- * (3-arg), or when the inner interval `[innerStart, innerEnd]` is fully contained within
- * the outer interval `[intervalStart, intervalEnd]` (4-arg).
+ * Return true when `pointOrStart` falls within the half-open interval
+ * `[intervalStart, intervalEnd)` (3-arg), or when the inner interval `[innerStart, innerEnd)` lies
+ * within the outer interval `[intervalStart, intervalEnd)` (4-arg).
  *
  * - Compares numeric Unix epoch values directly.
- * - Always-inclusive boundaries: `start <= point <= end`.
+ * - Point mode: `start <= point < end`, the same rule as `intervalContains`. The `end` is
+ *   excluded, so a point at `end` returns `false`, and an empty interval (`start === end`)
+ *   contains no point.
+ * - Interval mode: the intervals overlap and `start <= innerStart` and `innerEnd <= end`. An inner
+ *   interval may share the outer `end`. An empty inner interval counts only strictly inside the
+ *   outer interval, the same edge rule as `clampInterval`, and an empty outer interval contains
+ *   nothing.
  * - Returns `false` if `intervalStart > intervalEnd` (invalid outer interval).
  * - Returns `false` if `innerStart > innerEnd` in 4-arg mode (invalid inner interval).
- * - 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 intervalStart Unix epoch value (seconds or milliseconds) — outer interval start
- * @param intervalEnd Unix epoch value (seconds or milliseconds) — outer interval end
+ * @param intervalStart Unix epoch value, in the one unit all epoch arguments share — outer interval start
+ * @param intervalEnd Unix epoch value, in the one unit all epoch arguments share — outer interval end
  * @param pointOrStart Unix epoch value for the point (3-arg) or inner start (4-arg)
  * @param pointEnd optional Unix epoch value for the inner interval end (4-arg mode)
  * @returns true if the point or inner interval is contained, or false on invalid input
  *
  * @example intervalContainsUnix(0, 1700000000, 170000000) // true
+ * @example intervalContainsUnix(0, 1700000000, 1700000000) // false (the end is excluded)
+ * @example intervalContainsUnix(0, 1700000000, 1500000000, 1700000000) // true (the inner interval shares the end)
  * @example intervalContainsUnix(0, 1700000000, 170000000, 1500000000) // true
  * @example intervalContainsUnix(1700000000, 0, 170000000) // false
  * @example intervalContainsUnix(0, 1700000000, 170000000, 15000000) // false
  * @example intervalContainsUnix(NaN, 1700000000, 170000000) // false
  * @example intervalContainsUnix("0", "1700000000", "170000000") // true
+ * @example intervalContainsUnix(0, 10, 0.5) // false (fractional epoch)
  */
 export declare function intervalContainsUnix(intervalStart: number | string, intervalEnd: number | string, pointOrStart: number | string, pointEnd?: number | string): boolean;

package/dist/unix/interval/intervalContainsUnix.js

@@ -1,60 +1,48 @@
+import { halfOpenContainsPoint, halfOpenContainsSpan, parseUnixEpochInterval, parseUnixEpochValue, } from "../../internal/index.js";
+const compareEpoch = (left, right) => left - right;
 /**
- * Return true when `pointOrStart` falls within the interval `[intervalStart, intervalEnd]`
- * (3-arg), or when the inner interval `[innerStart, innerEnd]` is fully contained within
- * the outer interval `[intervalStart, intervalEnd]` (4-arg).
+ * Return true when `pointOrStart` falls within the half-open interval
+ * `[intervalStart, intervalEnd)` (3-arg), or when the inner interval `[innerStart, innerEnd)` lies
+ * within the outer interval `[intervalStart, intervalEnd)` (4-arg).
  *
  * - Compares numeric Unix epoch values directly.
- * - Always-inclusive boundaries: `start <= point <= end`.
+ * - Point mode: `start <= point < end`, the same rule as `intervalContains`. The `end` is
+ *   excluded, so a point at `end` returns `false`, and an empty interval (`start === end`)
+ *   contains no point.
+ * - Interval mode: the intervals overlap and `start <= innerStart` and `innerEnd <= end`. An inner
+ *   interval may share the outer `end`. An empty inner interval counts only strictly inside the
+ *   outer interval, the same edge rule as `clampInterval`, and an empty outer interval contains
+ *   nothing.
  * - Returns `false` if `intervalStart > intervalEnd` (invalid outer interval).
  * - Returns `false` if `innerStart > innerEnd` in 4-arg mode (invalid inner interval).
- * - 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 intervalStart Unix epoch value (seconds or milliseconds) — outer interval start
- * @param intervalEnd Unix epoch value (seconds or milliseconds) — outer interval end
+ * @param intervalStart Unix epoch value, in the one unit all epoch arguments share — outer interval start
+ * @param intervalEnd Unix epoch value, in the one unit all epoch arguments share — outer interval end
  * @param pointOrStart Unix epoch value for the point (3-arg) or inner start (4-arg)
  * @param pointEnd optional Unix epoch value for the inner interval end (4-arg mode)
  * @returns true if the point or inner interval is contained, or false on invalid input
  *
  * @example intervalContainsUnix(0, 1700000000, 170000000) // true
+ * @example intervalContainsUnix(0, 1700000000, 1700000000) // false (the end is excluded)
+ * @example intervalContainsUnix(0, 1700000000, 1500000000, 1700000000) // true (the inner interval shares the end)
  * @example intervalContainsUnix(0, 1700000000, 170000000, 1500000000) // true
  * @example intervalContainsUnix(1700000000, 0, 170000000) // false
  * @example intervalContainsUnix(0, 1700000000, 170000000, 15000000) // false
  * @example intervalContainsUnix(NaN, 1700000000, 170000000) // false
  * @example intervalContainsUnix("0", "1700000000", "170000000") // true
+ * @example intervalContainsUnix(0, 10, 0.5) // false (fractional epoch)
  */
 export function intervalContainsUnix(intervalStart, intervalEnd, pointOrStart, pointEnd) {
-    if (typeof intervalStart !== "number" && typeof intervalStart !== "string") {
-        return false;
-    }
-    if (typeof intervalEnd !== "number" && typeof intervalEnd !== "string") {
-        return false;
-    }
-    if (typeof pointOrStart !== "number" && typeof pointOrStart !== "string") {
-        return false;
-    }
-    if (pointEnd !== undefined &&
-        typeof pointEnd !== "number" &&
-        typeof pointEnd !== "string") {
-        return false;
-    }
-    const n1 = typeof intervalStart === "number" ? intervalStart : Number(intervalStart);
-    const n2 = typeof intervalEnd === "number" ? intervalEnd : Number(intervalEnd);
-    const n3 = typeof pointOrStart === "number" ? pointOrStart : Number(pointOrStart);
-    if (!Number.isFinite(n1) || !Number.isFinite(n2) || !Number.isFinite(n3)) {
-        return false;
-    }
-    if (n1 > n2) {
+    const outer = parseUnixEpochInterval(intervalStart, intervalEnd);
+    if (outer === null) {
         return false;
     }
     if (pointEnd === undefined) {
-        return n1 <= n3 && n3 <= n2;
-    }
-    const n4 = typeof pointEnd === "number" ? pointEnd : Number(pointEnd);
-    if (!Number.isFinite(n4)) {
-        return false;
-    }
-    if (n3 > n4) {
-        return false;
+        const point = parseUnixEpochValue(pointOrStart);
+        return point !== null && halfOpenContainsPoint(outer, point, compareEpoch);
     }
-    return n1 <= n3 && n4 <= n2;
+    const inner = parseUnixEpochInterval(pointOrStart, pointEnd);
+    return inner !== null && halfOpenContainsSpan(outer, inner, compareEpoch);
 }