@northguild/gmt 1.14.2

package/dist/unix/get/getUnixMonth.js

@@ -0,0 +1,24 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return the current month from the Unix timestamp in UTC as a zero-padded string.
+ *
+ * - Uses Temporal.Now.instant() converted to UTC zoned date time.
+ * - Returns zero-padded string to 2 digits.
+ * - Returns "" on failure.
+ *
+ * @returns current month string (zero-padded to 2 digits) or "" on failure
+ *
+ * @example getUnixMonth() // "02"
+ * @example getUnixMonth() // "" (on failure)
+ */
+export function getUnixMonth() {
+    try {
+        return Temporal.Now.instant()
+            .toZonedDateTimeISO("UTC")
+            .month.toString()
+            .padStart(2, "0");
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the current nanosecond from the Unix timestamp in UTC as a zero-padded string.
+ *
+ * - Uses Temporal.Now.instant() converted to UTC zoned date time.
+ * - Returns zero-padded string to 3 digits.
+ * - Returns "" on failure.
+ *
+ * @returns current nanosecond string (zero-padded to 3 digits) or "" on failure
+ *
+ * @example getUnixNanosecond() // "789"
+ * @example getUnixNanosecond() // "" (on failure)
+ */
+export declare function getUnixNanosecond(): string;

package/dist/unix/get/getUnixNanosecond.js

@@ -0,0 +1,23 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return the current nanosecond from the Unix timestamp in UTC as a zero-padded string.
+ *
+ * - Uses Temporal.Now.instant() converted to UTC zoned date time.
+ * - Returns zero-padded string to 3 digits.
+ * - Returns "" on failure.
+ *
+ * @returns current nanosecond string (zero-padded to 3 digits) or "" on failure
+ *
+ * @example getUnixNanosecond() // "789"
+ * @example getUnixNanosecond() // "" (on failure)
+ */
+export function getUnixNanosecond() {
+    try {
+        return (Temporal.Now.instant().toZonedDateTimeISO("UTC").nanosecond ?? 0)
+            .toString()
+            .padStart(3, "0");
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,15 @@
+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.
+ *
+ * @param unit optional unit specifier: "seconds" | "milliseconds"
+ * @returns number (unix timestamp)
+ *
+ * @example getUnixNow() // 1700000000000
+ * @example getUnixNow("seconds") // 1700000000
+ */
+export declare function getUnixNow(...unitInput: [unit?: UnixUnit]): number;

package/dist/unix/get/getUnixNow.js

@@ -0,0 +1,28 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUnixUnit } 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.
+ *
+ * @param unit optional unit specifier: "seconds" | "milliseconds"
+ * @returns number (unix timestamp)
+ *
+ * @example getUnixNow() // 1700000000000
+ * @example getUnixNow("seconds") // 1700000000
+ */
+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);
+    }
+    return instant.epochMilliseconds;
+}

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

@@ -0,0 +1,18 @@
+import type { DateTimeUnit } from "../../types/index.js";
+type UnixNowUnit = DateTimeUnit | "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".
+ * - Uses Temporal.Now.instant() converted to UTC zoned date time.
+ * - Returns "" on invalid unit or failure.
+ *
+ * @param unit unit to extract from current unix timestamp
+ * @returns string representation of the requested unit or "" on invalid
+ *
+ * @example getUnixNowUnit("year") // "2024"
+ * @example getUnixNowUnit("month") // "02"
+ * @example getUnixNowUnit("invalid") // ""
+ */
+export declare function getUnixNowUnit(unit: UnixNowUnit): string;
+export {};

package/dist/unix/get/getUnixNowUnit.js

@@ -0,0 +1,61 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTimeUnit } from "../../plain/validate/index.js";
+function isValidUnixNowUnit(unit) {
+    return isValidDateTimeUnit(unit) || ["dayOfWeek"].includes(unit);
+}
+/**
+ * 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".
+ * - Uses Temporal.Now.instant() converted to UTC zoned date time.
+ * - Returns "" on invalid unit or failure.
+ *
+ * @param unit unit to extract from current unix timestamp
+ * @returns string representation of the requested unit or "" on invalid
+ *
+ * @example getUnixNowUnit("year") // "2024"
+ * @example getUnixNowUnit("month") // "02"
+ * @example getUnixNowUnit("invalid") // ""
+ */
+export function getUnixNowUnit(unit) {
+    if (!isValidUnixNowUnit(String(unit ?? "")))
+        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 "";
+        }
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the current second from the Unix timestamp in UTC as a zero-padded string.
+ *
+ * - Uses Temporal.Now.instant() converted to UTC zoned date time.
+ * - Returns zero-padded string to 2 digits.
+ * - Returns "" on failure.
+ *
+ * @returns current second string (zero-padded to 2 digits) or "" on failure
+ *
+ * @example getUnixSecond() // "45"
+ * @example getUnixSecond() // "" (on failure)
+ */
+export declare function getUnixSecond(): string;

package/dist/unix/get/getUnixSecond.js

@@ -0,0 +1,24 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return the current second from the Unix timestamp in UTC as a zero-padded string.
+ *
+ * - Uses Temporal.Now.instant() converted to UTC zoned date time.
+ * - Returns zero-padded string to 2 digits.
+ * - Returns "" on failure.
+ *
+ * @returns current second string (zero-padded to 2 digits) or "" on failure
+ *
+ * @example getUnixSecond() // "45"
+ * @example getUnixSecond() // "" (on failure)
+ */
+export function getUnixSecond() {
+    try {
+        return Temporal.Now.instant()
+            .toZonedDateTimeISO("UTC")
+            .second.toString()
+            .padStart(2, "0");
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the current year from the Unix timestamp in UTC as a zero-padded string.
+ *
+ * - Uses Temporal.Now.instant() converted to UTC zoned date time.
+ * - Returns zero-padded string to 4 digits.
+ * - Returns "" on failure.
+ *
+ * @returns current year string (zero-padded to 4 digits) or "" on failure
+ *
+ * @example getUnixYear() // "2024"
+ * @example getUnixYear() // "" (on failure)
+ */
+export declare function getUnixYear(): string;

package/dist/unix/get/getUnixYear.js

@@ -0,0 +1,24 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Return the current year from the Unix timestamp in UTC as a zero-padded string.
+ *
+ * - Uses Temporal.Now.instant() converted to UTC zoned date time.
+ * - Returns zero-padded string to 4 digits.
+ * - Returns "" on failure.
+ *
+ * @returns current year string (zero-padded to 4 digits) or "" on failure
+ *
+ * @example getUnixYear() // "2024"
+ * @example getUnixYear() // "" (on failure)
+ */
+export function getUnixYear() {
+    try {
+        return Temporal.Now.instant()
+            .toZonedDateTimeISO("UTC")
+            .year.toString()
+            .padStart(4, "0");
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,11 @@
+export * from "./getUnixDay.js";
+export * from "./getUnixHour.js";
+export * from "./getUnixMicrosecond.js";
+export * from "./getUnixMillisecond.js";
+export * from "./getUnixMinute.js";
+export * from "./getUnixMonth.js";
+export * from "./getUnixNanosecond.js";
+export * from "./getUnixNow.js";
+export * from "./getUnixNowUnit.js";
+export * from "./getUnixSecond.js";
+export * from "./getUnixYear.js";

package/dist/unix/get/index.js

@@ -0,0 +1,11 @@
+export * from "./getUnixDay.js";
+export * from "./getUnixHour.js";
+export * from "./getUnixMicrosecond.js";
+export * from "./getUnixMillisecond.js";
+export * from "./getUnixMinute.js";
+export * from "./getUnixMonth.js";
+export * from "./getUnixNanosecond.js";
+export * from "./getUnixNow.js";
+export * from "./getUnixNowUnit.js";
+export * from "./getUnixSecond.js";
+export * from "./getUnixYear.js";

package/dist/unix/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./calculate/index.js";
+export * from "./compare/index.js";
+export * from "./convert/index.js";
+export * from "./format/index.js";
+export * from "./get/index.js";
+export * from "./interval/index.js";
+export * from "./parse/index.js";
+export * from "./validate/index.js";

package/dist/unix/index.js

@@ -0,0 +1,8 @@
+export * from "./calculate/index.js";
+export * from "./compare/index.js";
+export * from "./convert/index.js";
+export * from "./format/index.js";
+export * from "./get/index.js";
+export * from "./interval/index.js";
+export * from "./parse/index.js";
+export * from "./validate/index.js";

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

@@ -0,0 +1,18 @@
+export * from "./intervalAbutsUnix.js";
+export * from "./intervalContainsUnix.js";
+export * from "./intervalCountUnix.js";
+export * from "./intervalDifferenceUnix.js";
+export * from "./intervalDivideEquallyUnix.js";
+export * from "./intervalEngulfsUnix.js";
+export * from "./intervalFromDurationUnix.js";
+export * from "./intervalIntersectionUnix.js";
+export * from "./intervalLengthUnix.js";
+export * from "./intervalOverlappingDaysUnix.js";
+export * from "./intervalsOverlapUnix.js";
+export * from "./intervalSplitAtUnix.js";
+export * from "./intervalUnionUnix.js";
+export * from "./intervalXorAllUnix.js";
+export * from "./intervalXorUnix.js";
+export * from "./mergeIntervalsUnix.js";
+export * from "./splitIntervalByUnitUnix.js";
+export * from "./validate/index.js";

package/dist/unix/interval/index.js

@@ -0,0 +1,18 @@
+export * from "./intervalAbutsUnix.js";
+export * from "./intervalContainsUnix.js";
+export * from "./intervalCountUnix.js";
+export * from "./intervalDifferenceUnix.js";
+export * from "./intervalDivideEquallyUnix.js";
+export * from "./intervalEngulfsUnix.js";
+export * from "./intervalFromDurationUnix.js";
+export * from "./intervalIntersectionUnix.js";
+export * from "./intervalLengthUnix.js";
+export * from "./intervalOverlappingDaysUnix.js";
+export * from "./intervalsOverlapUnix.js";
+export * from "./intervalSplitAtUnix.js";
+export * from "./intervalUnionUnix.js";
+export * from "./intervalXorAllUnix.js";
+export * from "./intervalXorUnix.js";
+export * from "./mergeIntervalsUnix.js";
+export * from "./splitIntervalByUnitUnix.js";
+export * from "./validate/index.js";

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

@@ -0,0 +1,22 @@
+/**
+ * Return true when two Unix intervals are exactly adjacent — one's end equals the other's
+ * start minus 1 (no gap, no overlap).
+ *
+ * - 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).
+ *
+ * @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 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, 1500000001, 1500000000, 1700000000) // false (overlap)
+ * @example intervalAbutsUnix(NaN, 1500000000, 1500000001, 1700000000) // false
+ */
+export declare function intervalAbutsUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): boolean;

package/dist/unix/interval/intervalAbutsUnix.js

@@ -0,0 +1,54 @@
+/**
+ * Return true when two Unix intervals are exactly adjacent — one's end equals the other's
+ * start minus 1 (no gap, no overlap).
+ *
+ * - 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).
+ *
+ * @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 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, 1500000001, 1500000000, 1700000000) // false (overlap)
+ * @example intervalAbutsUnix(NaN, 1500000000, 1500000001, 1700000000) // false
+ */
+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")) {
+        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;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * 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).
+ *
+ * - Compares numeric Unix epoch values directly.
+ * - Always-inclusive boundaries: `start <= point <= end`.
+ * - 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).
+ *
+ * @param intervalStart Unix epoch value (seconds or milliseconds) — outer interval start
+ * @param intervalEnd Unix epoch value (seconds or milliseconds) — 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, 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
+ */
+export declare function intervalContainsUnix(intervalStart: number | string, intervalEnd: number | string, pointOrStart: number | string, pointEnd?: number | string): boolean;

package/dist/unix/interval/intervalContainsUnix.js

@@ -0,0 +1,60 @@
+/**
+ * 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).
+ *
+ * - Compares numeric Unix epoch values directly.
+ * - Always-inclusive boundaries: `start <= point <= end`.
+ * - 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).
+ *
+ * @param intervalStart Unix epoch value (seconds or milliseconds) — outer interval start
+ * @param intervalEnd Unix epoch value (seconds or milliseconds) — 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, 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
+ */
+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) {
+        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;
+    }
+    return n1 <= n3 && n4 <= n2;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Count how many `unit` boundaries a Unix epoch interval crosses.
+ *
+ * - Counts local calendar boundaries touched by the half-open interval `[start, end)` —
+ *   distinct from `diffUnix`, which measures exact elapsed duration.
+ * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
+ * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
+ *   unit boundary.
+ * - Uses the system timeZone for calendar-unit boundaries (consistent with `addUnix` and
+ *   `splitIntervalByUnitUnix`), so day/week/month/year counts are host-dependent.
+ * - Weeks start on Monday (ISO 8601).
+ * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
+ * - 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 number of unit boundaries touched, or null on invalid input
+ *
+ * @example intervalCountUnix(0, 86400000, "hour") // 24
+ * @example intervalCountUnix(1704153540000, 1704153660000, "day") // 2 (23:59 to 00:01 UTC)
+ * @example intervalCountUnix(0, 0, "hour") // 0 (zero-length, on the boundary)
+ * @example intervalCountUnix(1800000, 1800000, "hour") // 1 (zero-length, mid-hour)
+ * @example intervalCountUnix(86400000, 0, "hour") // null
+ * @example intervalCountUnix(NaN, 86400000, "hour") // null
+ */
+export declare function intervalCountUnix(start: number | string, end: number | string, unit: string): number | null;

package/dist/unix/interval/intervalCountUnix.js

@@ -0,0 +1,44 @@
+import { getStartOfZonedUnit, getUnitSpan } from "../../internal/index.js";
+import { resolveUnixIntervalPair } from "./resolveUnixIntervalPair.js";
+/**
+ * Count how many `unit` boundaries a Unix epoch interval crosses.
+ *
+ * - Counts local calendar boundaries touched by the half-open interval `[start, end)` —
+ *   distinct from `diffUnix`, which measures exact elapsed duration.
+ * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
+ * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
+ *   unit boundary.
+ * - Uses the system timeZone for calendar-unit boundaries (consistent with `addUnix` and
+ *   `splitIntervalByUnitUnix`), so day/week/month/year counts are host-dependent.
+ * - Weeks start on Monday (ISO 8601).
+ * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
+ * - 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 number of unit boundaries touched, or null on invalid input
+ *
+ * @example intervalCountUnix(0, 86400000, "hour") // 24
+ * @example intervalCountUnix(1704153540000, 1704153660000, "day") // 2 (23:59 to 00:01 UTC)
+ * @example intervalCountUnix(0, 0, "hour") // 0 (zero-length, on the boundary)
+ * @example intervalCountUnix(1800000, 1800000, "hour") // 1 (zero-length, mid-hour)
+ * @example intervalCountUnix(86400000, 0, "hour") // null
+ * @example intervalCountUnix(NaN, 86400000, "hour") // null
+ */
+export function intervalCountUnix(start, end, unit) {
+    const resolved = resolveUnixIntervalPair(start, end, unit);
+    if (!resolved)
+        return null;
+    try {
+        const { startVal, endVal, resolvedUnit } = resolved;
+        const startOfStart = getStartOfZonedUnit(startVal, resolvedUnit);
+        const startOfEnd = getStartOfZonedUnit(endVal, resolvedUnit);
+        const spanned = getUnitSpan(startOfStart.until(startOfEnd, { largestUnit: resolvedUnit }), resolvedUnit);
+        return spanned + (startOfEnd.equals(endVal) ? 0 : 1);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * 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 declare function intervalDifferenceUnix(aStart: number | string, aEnd: number | string, bStart: number | string, bEnd: number | string): Array<{
+    start: number;
+    end: number;
+}>;