@northguild/gmt 1.14.2 → 1.16.0

package/dist/unix/calculate/subtractUnix.d.ts

@@ -1,25 +1,31 @@
 import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Subtract a temporal amount from a Unix epoch value and return the resulting epoch.
  *
  * - Converts to ZonedDateTime, subtracts the duration, then converts back to epoch.
  * - Validates duration units and values.
+ * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone.
  * - Returns null for invalid input.
  *
  * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
  * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in null).
  *
- * @param value Unix timestamp (number)
+ * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject")
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone returns null), overflow ("constrain" | "reject")
  * @returns Unix epoch number after subtraction, or null on invalid input
  *
  * @example subtractUnix(1706745600000, { days: 1 }) // 1706659200000
  * @example subtractUnix(1706745600, { days: 1 }, { epochUnit: "seconds" }) // 1706659200
  * @example subtractUnix(0, { days: 1 }) // -86400000 (Jan 1 1970 - 1 day = Dec 31 1969)
+ * @example subtractUnix(1.5, { days: 1 }) // null (not an integer epoch)
+ * @example subtractUnix("1706659200000", { days: 1 }) // 1706572800000 (digit string)
+ * @example subtractUnix(1706659200000, { days: 1 }, { timeZone: "Mars/Olympus" }) // null (unknown zone)
  */
-export declare function subtractUnix(value: number, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function subtractUnix(value: number | string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
     overflow?: Overflow;
 }): number | null;

package/dist/unix/calculate/subtractUnix.js

@@ -1,51 +1,64 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { subtractFromZoned, isValidAmount, resolveOverflow, } from "../../internal/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Subtract a temporal amount from a Unix epoch value and return the resulting epoch.
  *
  * - Converts to ZonedDateTime, subtracts the duration, then converts back to epoch.
  * - Validates duration units and values.
+ * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
+ * - An omitted `timeZone` is UTC; pass `"local"` for the system time zone.
  * - Returns null for invalid input.
  *
  * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
  * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in null).
  *
- * @param value Unix timestamp (number)
+ * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), overflow ("constrain" | "reject")
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"; an unknown zone returns null), overflow ("constrain" | "reject")
  * @returns Unix epoch number after subtraction, or null on invalid input
  *
  * @example subtractUnix(1706745600000, { days: 1 }) // 1706659200000
  * @example subtractUnix(1706745600, { days: 1 }, { epochUnit: "seconds" }) // 1706659200
  * @example subtractUnix(0, { days: 1 }) // -86400000 (Jan 1 1970 - 1 day = Dec 31 1969)
+ * @example subtractUnix(1.5, { days: 1 }) // null (not an integer epoch)
+ * @example subtractUnix("1706659200000", { days: 1 }) // 1706572800000 (digit string)
+ * @example subtractUnix(1706659200000, { days: 1 }, { timeZone: "Mars/Olympus" }) // null (unknown zone)
  */
 export function subtractUnix(value, units, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    const timeZone = options?.timeZone ?? getSystemTimeZone();
-    const overflow = resolveOverflow(options?.overflow);
-    if (!timeZone || !isValidTimeZone(timeZone))
-        return null;
-    const validUnits = Object.keys(units).every(isValidDateTimeDurationUnit);
-    const validAmounts = Object.values(units).every(isValidAmount);
-    if (!validUnits || !validAmounts) {
-        return null;
-    }
-    if (!Number.isFinite(value) || !Number.isInteger(value)) {
-        return null;
-    }
     try {
-        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value * 1000 : value);
-        const zdt = instant.toZonedDateTimeISO(timeZone);
-        const result = zdt.subtract(units, { overflow });
-        const epoch = epochUnit === "seconds"
-            ? Math.floor(result.epochMilliseconds / 1000)
-            : result.epochMilliseconds;
-        return epoch;
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        const overflow = resolveOverflow(options?.overflow);
+        if (!timeZone || epochUnit === null)
+            return null;
+        const validUnits = typeof units === "object" &&
+            units !== null &&
+            Object.keys(units).every(isValidDateTimeDurationUnit);
+        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
+        if (!validUnits || !validAmounts) {
+            return null;
+        }
+        const instant = unixEpochToInstant(value, epochUnit);
+        if (instant === null) {
+            return null;
+        }
+        try {
+            const zdt = instant.toZonedDateTimeISO(timeZone);
+            return toUnixEpoch(subtractFromZoned(zdt, units, { overflow }), epochUnit);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/unix/compare/areUnixEqual.d.ts

@@ -3,19 +3,23 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * Return whether `value1` and `value2` represent the same instant.
  *
  * - Uses Temporal.Instant.compare to check equality.
+ * - Each value is a safe integer or a string of optionally negative ASCII digits; anything else
+ *   is invalid.
  * - Returns false if either input is invalid.
  *
- * @param value1 first unix epoch value
- * @param value2 second unix epoch value
- * @param options epoch unit and options
+ * @param value1 first unix epoch: a safe integer or a digit string
+ * @param value2 second unix epoch, in the same unit
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns `true` if `value1` and `value2` are equal, otherwise `false`
  *
  * @example areUnixEqual(1706659200, 1706659200) // true
  * @example areUnixEqual(1706659200, 1704067200) // false
- * @example areUnixEqual(1706659200, 1706659200000, { epochUnit: "seconds" }) // true
+ * @example areUnixEqual(1706659200, 1706659200000, { epochUnit: "seconds" }) // false (epochUnit applies to both values)
  * @example areUnixEqual(1706659200, 1706659200000) // false
  * @example areUnixEqual(-86400000, 0) // false (1969-12-31 is not equal to 1970-01-01)
+ * @example areUnixEqual("1706659200", 1706659200, { epochUnit: "second" }) // true (a digit string is the same epoch)
+ * @example areUnixEqual("1706659200.0", 1706659200) // false (not a digit string)
  */
-export declare function areUnixEqual(value1: number, value2: number, options?: {
+export declare function areUnixEqual(value1: number | string, value2: number | string, options?: {
     epochUnit?: UnixUnit;
 }): boolean;

package/dist/unix/compare/areUnixEqual.js

@@ -1,33 +1,37 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount } from "../../internal/index.js";
+import { compareUnixEpochs } from "../../internal/compareUnixEpochs.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return whether `value1` and `value2` represent the same instant.
  *
  * - Uses Temporal.Instant.compare to check equality.
+ * - Each value is a safe integer or a string of optionally negative ASCII digits; anything else
+ *   is invalid.
  * - Returns false if either input is invalid.
  *
- * @param value1 first unix epoch value
- * @param value2 second unix epoch value
- * @param options epoch unit and options
+ * @param value1 first unix epoch: a safe integer or a digit string
+ * @param value2 second unix epoch, in the same unit
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns `true` if `value1` and `value2` are equal, otherwise `false`
  *
  * @example areUnixEqual(1706659200, 1706659200) // true
  * @example areUnixEqual(1706659200, 1704067200) // false
- * @example areUnixEqual(1706659200, 1706659200000, { epochUnit: "seconds" }) // true
+ * @example areUnixEqual(1706659200, 1706659200000, { epochUnit: "seconds" }) // false (epochUnit applies to both values)
  * @example areUnixEqual(1706659200, 1706659200000) // false
  * @example areUnixEqual(-86400000, 0) // false (1969-12-31 is not equal to 1970-01-01)
+ * @example areUnixEqual("1706659200", 1706659200, { epochUnit: "second" }) // true (a digit string is the same epoch)
+ * @example areUnixEqual("1706659200.0", 1706659200) // false (not a digit string)
  */
 export function areUnixEqual(value1, value2, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    if (!isValidAmount(value1) || !isValidAmount(value2)) {
-        return false;
-    }
     try {
-        const instant1 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value1 * 1000 : value1);
-        const instant2 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value2 * 1000 : value2);
-        return Temporal.Instant.compare(instant1, instant2) === 0;
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        const order = compareUnixEpochs(value1, value2, options);
+        return order !== null && order === 0;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/unix/compare/areUnixEqualBy.d.ts

@@ -1,30 +1,37 @@
-import type { DateTimeUnit } from "../../types/index.js";
+import type { Temporal } from "@js-temporal/polyfill";
 import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Compare two Unix epoch values for equality at a given unit.
  *
  * - Both values are resolved to the start of `unit` in `options.timeZone`
- *   (default: the system time zone) before comparison, so `"day"` compares
+ *   (default: `"UTC"`) before comparison, so `"day"` compares
  *   calendar days in that zone, not raw epoch buckets.
+ * - The start of `unit` is the real local bucket (see `startOfUnix`), so two epochs are equal
+ *   only when they fall in the same bucket — including one a zone transition shortened, like
+ *   `Pacific/Chatham`'s 15-minute 03:00 hour on its 2024 spring-forward.
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
- * - Returns false for an unsupported unit or invalid input.
+ * - Each value is a safe integer or a string of optionally negative ASCII digits; `unit` may be
+ *   singular or plural. An omitted `timeZone` is UTC; `"local"` is the system zone.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
+ * - Returns false for an unsupported unit (including `"quarter"`) or invalid input.
  *
  * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
  * - `isSameDay(a, b)` → `areUnixEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUnixEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUnixEqualBy(a, b, "year")`
  *
- * @param value1 first Unix epoch value
- * @param value2 second Unix epoch value
+ * @param value1 first Unix epoch: a safe integer or a digit string
+ * @param value2 second Unix epoch, in the same unit
  * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), weekStartsOn ("monday" | "sunday")
  * @returns true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areUnixEqualBy(1710498000000, 1710503000000, "day", { timeZone: "UTC" }) // true (both fall on 2024-03-15 in UTC)
  * @example areUnixEqualBy(1704067200000, 1735689600000, "year", { timeZone: "UTC" }) // false (2024-01-01 vs 2025-01-01)
+ * @example areUnixEqualBy("1710498000000", 1710503000000, "days") // true (digit string, plural unit, UTC by default)
  * @example areUnixEqualBy(Number.NaN, 1710498000000, "day") // false
  */
-export declare function areUnixEqualBy(value1: number, value2: number, unit: DateTimeUnit, options?: {
+export declare function areUnixEqualBy(value1: number | string, value2: number | string, unit: Temporal.DateTimeUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
     epochUnit?: UnixUnit;
     timeZone?: string;
     weekStartsOn?: "monday" | "sunday";

package/dist/unix/compare/areUnixEqualBy.js

@@ -1,31 +1,38 @@
-import { isValidAmount } from "../../internal/index.js";
 import { startOfUnix } from "../calculate/startOfUnix.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Compare two Unix epoch values for equality at a given unit.
  *
  * - Both values are resolved to the start of `unit` in `options.timeZone`
- *   (default: the system time zone) before comparison, so `"day"` compares
+ *   (default: `"UTC"`) before comparison, so `"day"` compares
  *   calendar days in that zone, not raw epoch buckets.
+ * - The start of `unit` is the real local bucket (see `startOfUnix`), so two epochs are equal
+ *   only when they fall in the same bucket — including one a zone transition shortened, like
+ *   `Pacific/Chatham`'s 15-minute 03:00 hour on its 2024 spring-forward.
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
- * - Returns false for an unsupported unit or invalid input.
+ * - Each value is a safe integer or a string of optionally negative ASCII digits; `unit` may be
+ *   singular or plural. An omitted `timeZone` is UTC; `"local"` is the system zone.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
+ * - Returns false for an unsupported unit (including `"quarter"`) or invalid input.
  *
  * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
  * - `isSameDay(a, b)` → `areUnixEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUnixEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUnixEqualBy(a, b, "year")`
  *
- * @param value1 first Unix epoch value
- * @param value2 second Unix epoch value
+ * @param value1 first Unix epoch: a safe integer or a digit string
+ * @param value2 second Unix epoch, in the same unit
  * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA), weekStartsOn ("monday" | "sunday")
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC"), weekStartsOn ("monday" | "sunday")
  * @returns true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areUnixEqualBy(1710498000000, 1710503000000, "day", { timeZone: "UTC" }) // true (both fall on 2024-03-15 in UTC)
  * @example areUnixEqualBy(1704067200000, 1735689600000, "year", { timeZone: "UTC" }) // false (2024-01-01 vs 2025-01-01)
+ * @example areUnixEqualBy("1710498000000", 1710503000000, "days") // true (digit string, plural unit, UTC by default)
  * @example areUnixEqualBy(Number.NaN, 1710498000000, "day") // false
  */
 export function areUnixEqualBy(value1, value2, unit, options) {
-    if (!isValidAmount(value1) || !isValidAmount(value2)) {
+    if (!isOptionsArgument(options)) {
         return false;
     }
     try {

package/dist/unix/compare/isAfterUnix.d.ts

@@ -3,17 +3,21 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * Return whether `value1` represents an instant strictly after `value2`.
  *
  * - Uses Temporal.Instant.compare to check ordering.
+ * - Each value is a safe integer or a string of optionally negative ASCII digits; anything else
+ *   is invalid.
  * - Returns false if either input is invalid.
  *
- * @param value1 first unix epoch value
- * @param value2 second unix epoch value
- * @param options optional: epochUnit ("seconds" | "milliseconds")
+ * @param value1 first unix epoch: a safe integer or a digit string
+ * @param value2 second unix epoch, in the same unit
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns `true` if `value1` is after `value2`, otherwise `false`
  *
  * @example isAfterUnix(1706659200, 1704067200) // true
  * @example isAfterUnix(1706659200, 1706659200) // false
  * @example isAfterUnix(-1, 0) // false
+ * @example isAfterUnix("1706659200", "1704067200") // true (digit strings)
+ * @example isAfterUnix(" 1706659200", 1704067200) // false (a padded string is not an epoch)
  */
-export declare function isAfterUnix(value1: number, value2: number, options?: {
+export declare function isAfterUnix(value1: number | string, value2: number | string, options?: {
     epochUnit?: UnixUnit;
 }): boolean;

package/dist/unix/compare/isAfterUnix.js

@@ -1,31 +1,35 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount } from "../../internal/index.js";
+import { compareUnixEpochs } from "../../internal/compareUnixEpochs.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return whether `value1` represents an instant strictly after `value2`.
  *
  * - Uses Temporal.Instant.compare to check ordering.
+ * - Each value is a safe integer or a string of optionally negative ASCII digits; anything else
+ *   is invalid.
  * - Returns false if either input is invalid.
  *
- * @param value1 first unix epoch value
- * @param value2 second unix epoch value
- * @param options optional: epochUnit ("seconds" | "milliseconds")
+ * @param value1 first unix epoch: a safe integer or a digit string
+ * @param value2 second unix epoch, in the same unit
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns `true` if `value1` is after `value2`, otherwise `false`
  *
  * @example isAfterUnix(1706659200, 1704067200) // true
  * @example isAfterUnix(1706659200, 1706659200) // false
  * @example isAfterUnix(-1, 0) // false
+ * @example isAfterUnix("1706659200", "1704067200") // true (digit strings)
+ * @example isAfterUnix(" 1706659200", 1704067200) // false (a padded string is not an epoch)
  */
 export function isAfterUnix(value1, value2, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    if (!isValidAmount(value1) || !isValidAmount(value2)) {
-        return false;
-    }
     try {
-        const instant1 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value1 * 1000 : value1);
-        const instant2 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value2 * 1000 : value2);
-        return Temporal.Instant.compare(instant1, instant2) === 1;
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        const order = compareUnixEpochs(value1, value2, options);
+        return order !== null && order === 1;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/unix/compare/isBeforeUnix.d.ts

@@ -3,11 +3,13 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * Return whether `value1` represents an instant strictly before `value2`.
  *
  * - Uses Temporal.Instant.compare to check ordering.
+ * - Each value is a safe integer or a string of optionally negative ASCII digits; anything else
+ *   is invalid.
  * - Returns false if either input is invalid.
  *
- * @param value1 first unix epoch value
- * @param value2 second unix epoch value
- * @param options optional: epochUnit ("seconds" | "milliseconds")
+ * @param value1 first unix epoch: a safe integer or a digit string
+ * @param value2 second unix epoch, in the same unit
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns `true` if `value1` is before `value2`, otherwise `false`
  *
  * @example isBeforeUnix(1704067200, 1706659200) // true
@@ -15,7 +17,8 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example isBeforeUnix(-1, 0) // true (1969-12-31T23:59:59.999Z is before 1970-01-01T00:00:00Z)
  * @example isBeforeUnix('invalid', 1704067200000) // false
  * @example isBeforeUnix(1704067200000, 'invalid') // false
+ * @example isBeforeUnix("-1", "0") // true (digit strings)
  */
-export declare function isBeforeUnix(value1: number, value2: number, options?: {
+export declare function isBeforeUnix(value1: number | string, value2: number | string, options?: {
     epochUnit?: UnixUnit;
 }): boolean;

package/dist/unix/compare/isBeforeUnix.js

@@ -1,14 +1,16 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount } from "../../internal/index.js";
+import { compareUnixEpochs } from "../../internal/compareUnixEpochs.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return whether `value1` represents an instant strictly before `value2`.
  *
  * - Uses Temporal.Instant.compare to check ordering.
+ * - Each value is a safe integer or a string of optionally negative ASCII digits; anything else
+ *   is invalid.
  * - Returns false if either input is invalid.
  *
- * @param value1 first unix epoch value
- * @param value2 second unix epoch value
- * @param options optional: epochUnit ("seconds" | "milliseconds")
+ * @param value1 first unix epoch: a safe integer or a digit string
+ * @param value2 second unix epoch, in the same unit
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns `true` if `value1` is before `value2`, otherwise `false`
  *
  * @example isBeforeUnix(1704067200, 1706659200) // true
@@ -16,18 +18,19 @@ import { isValidAmount } from "../../internal/index.js";
  * @example isBeforeUnix(-1, 0) // true (1969-12-31T23:59:59.999Z is before 1970-01-01T00:00:00Z)
  * @example isBeforeUnix('invalid', 1704067200000) // false
  * @example isBeforeUnix(1704067200000, 'invalid') // false
+ * @example isBeforeUnix("-1", "0") // true (digit strings)
  */
 export function isBeforeUnix(value1, value2, options) {
-    const epochUnit = options?.epochUnit ?? "milliseconds";
-    if (!isValidAmount(value1) || !isValidAmount(value2)) {
-        return false;
-    }
     try {
-        const instant1 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value1 * 1000 : value1);
-        const instant2 = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? value2 * 1000 : value2);
-        return Temporal.Instant.compare(instant1, instant2) === -1;
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        const order = compareUnixEpochs(value1, value2, options);
+        return order !== null && order === -1;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/unix/convert/convertUnixToPlainDate.d.ts

@@ -1,19 +1,27 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a Unix timestamp to a plain date string in the format "YYYY-MM-DD".
  *
- * - Converts to PlainDate using the specified or system timezone.
- * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Converts to PlainDate in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
+ *   unknown zone returns "".
+ * - `unix` is a safe integer or a string of optionally negative ASCII digits; anything else returns
+ *   "".
+ * - Validates epoch unit ("seconds" | "milliseconds", singular accepted).
  * - Returns "" for invalid input.
  *
- * @param unix Unix timestamp (number)
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @param unix Unix epoch: a safe integer or a digit string
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
  * @returns plain date string in "YYYY-MM-DD" format or "" on invalid input
  *
- * @example convertUnixToPlainDate(1709164800000) // "2024-02-29"
- * @example convertUnixToPlainDate(1709164800, { epochUnit: "seconds" }) // "2024-02-29"
- * @example convertUnixToPlainDate(-1) // "1969-12-31"
+ * @example convertUnixToPlainDate(1709164800000, { timeZone: "UTC" }) // "2024-02-29"
+ * @example convertUnixToPlainDate(1709164800, { epochUnit: "seconds", timeZone: "UTC" }) // "2024-02-29"
+ * @example convertUnixToPlainDate(-1, { timeZone: "UTC" }) // "1969-12-31"
+ * @example convertUnixToPlainDate(1709164800000) // "2024-02-29" (UTC by default)
+ * @example convertUnixToPlainDate("1709164800", { epochUnit: "second", timeZone: "Asia/Tokyo" }) // "2024-02-29"
+ * @example convertUnixToPlainDate(1709164800000, { timeZone: "Asia/Tokio" }) // "" (unknown zone)
+ * @example convertUnixToPlainDate(NaN) // ""
  */
-export declare function convertUnixToPlainDate(unix: number, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function convertUnixToPlainDate(unix: number | string, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
 }): string;

package/dist/unix/convert/convertUnixToPlainDate.js

@@ -1,38 +1,51 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../../zoned/index.js";
-import { getSystemTimeZone } from "../../zoned/get/index.js";
-import { isValidUnixMilliseconds, isValidUnixSeconds, isValidUnixUnit, } from "../validate/index.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a Unix timestamp to a plain date string in the format "YYYY-MM-DD".
  *
- * - Converts to PlainDate using the specified or system timezone.
- * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Converts to PlainDate in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
+ *   unknown zone returns "".
+ * - `unix` is a safe integer or a string of optionally negative ASCII digits; anything else returns
+ *   "".
+ * - Validates epoch unit ("seconds" | "milliseconds", singular accepted).
  * - Returns "" for invalid input.
  *
- * @param unix Unix timestamp (number)
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @param unix Unix epoch: a safe integer or a digit string
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
  * @returns plain date string in "YYYY-MM-DD" format or "" on invalid input
  *
- * @example convertUnixToPlainDate(1709164800000) // "2024-02-29"
- * @example convertUnixToPlainDate(1709164800, { epochUnit: "seconds" }) // "2024-02-29"
- * @example convertUnixToPlainDate(-1) // "1969-12-31"
+ * @example convertUnixToPlainDate(1709164800000, { timeZone: "UTC" }) // "2024-02-29"
+ * @example convertUnixToPlainDate(1709164800, { epochUnit: "seconds", timeZone: "UTC" }) // "2024-02-29"
+ * @example convertUnixToPlainDate(-1, { timeZone: "UTC" }) // "1969-12-31"
+ * @example convertUnixToPlainDate(1709164800000) // "2024-02-29" (UTC by default)
+ * @example convertUnixToPlainDate("1709164800", { epochUnit: "second", timeZone: "Asia/Tokyo" }) // "2024-02-29"
+ * @example convertUnixToPlainDate(1709164800000, { timeZone: "Asia/Tokio" }) // "" (unknown zone)
+ * @example convertUnixToPlainDate(NaN) // ""
  */
 export function convertUnixToPlainDate(unix, options) {
-    const { epochUnit = "milliseconds", timeZone = getSystemTimeZone() } = options ?? {};
-    if (!isValidUnixUnit(epochUnit))
-        return "";
-    if (!isValidTimeZone(timeZone))
-        return "";
     try {
-        if ((epochUnit === "milliseconds" && !isValidUnixMilliseconds(unix)) ||
-            (epochUnit === "seconds" && !isValidUnixSeconds(unix))) {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (epochUnit === null || !timeZone)
+            return "";
+        const instant = unixEpochToInstant(unix, epochUnit);
+        if (instant === null)
+            return "";
+        try {
+            return instant.toZonedDateTimeISO(timeZone).toPlainDate().toString();
+        }
+        catch {
             return "";
         }
-        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? unix * 1000 : unix);
-        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-        return zonedDateTime.toPlainDate().toString();
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/unix/convert/convertUnixToPlainDateTime.d.ts

@@ -1,19 +1,25 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a Unix timestamp to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
  *
- * - Converts to PlainDateTime using the specified or system timezone.
- * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Converts to PlainDateTime in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
+ *   unknown zone returns "".
+ * - `unix` is a safe integer or a string of optionally negative ASCII digits; anything else returns
+ *   "".
+ * - Validates epoch unit ("seconds" | "milliseconds", singular accepted).
  * - Returns "" for invalid input.
  *
- * @param unix Unix timestamp (number)
- * @param options optional: epochUnit ("seconds" | "milliseconds"), timeZone (IANA)
+ * @param unix Unix epoch: a safe integer or a digit string
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds"), timeZone (IANA, or "local" for the system zone; default "UTC")
  * @returns plain datetime string in "YYYY-MM-DDTHH:mm:ss" format or "" on invalid input
  *
- * @example convertUnixToPlainDateTime(1709164800000) // "2024-02-29T00:00:00"
- * @example convertUnixToPlainDateTime(1709164800, { epochUnit: "seconds" }) // "2024-02-29T00:00:00"
- * @example convertUnixToPlainDateTime(-1) // "1969-12-31T23:59:59.999"
+ * @example convertUnixToPlainDateTime(1709164800000, { timeZone: "UTC" }) // "2024-02-29T00:00:00"
+ * @example convertUnixToPlainDateTime(1709164800, { epochUnit: "seconds", timeZone: "UTC" }) // "2024-02-29T00:00:00"
+ * @example convertUnixToPlainDateTime(-1, { timeZone: "UTC" }) // "1969-12-31T23:59:59.999"
+ * @example convertUnixToPlainDateTime("1709164800000", { timeZone: "Asia/Tokyo" }) // "2024-02-29T09:00:00"
+ * @example convertUnixToPlainDateTime(NaN) // ""
  */
-export declare function convertUnixToPlainDateTime(unix: number, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function convertUnixToPlainDateTime(unix: number | string, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
 }): string;