@northguild/gmt 1.15.0 → 1.16.0

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;

package/dist/unix/convert/convertUnixToPlainDateTime.js

@@ -1,38 +1,49 @@
-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 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 function convertUnixToPlainDateTime(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).toPlainDateTime().toString();
+        }
+        catch {
             return "";
         }
-        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? unix * 1000 : unix);
-        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-        return zonedDateTime.toPlainDateTime().toString();
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,19 +1,25 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a Unix timestamp to a plain time string in the format "HH:mm:ss".
  *
- * - Converts to PlainTime using the specified or system timezone.
- * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Converts to PlainTime 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 time string in "HH:mm:ss" format or "" on invalid input
  *
- * @example convertUnixToPlainTime(1706659200000) // "00:00:00"
- * @example convertUnixToPlainTime(1706659200, { epochUnit: "seconds" }) // "00:00:00"
- * @example convertUnixToPlainTime(-1) // "23:59:59.999"
+ * @example convertUnixToPlainTime(1706659200000, { timeZone: "UTC" }) // "00:00:00"
+ * @example convertUnixToPlainTime(1706659200, { epochUnit: "seconds", timeZone: "UTC" }) // "00:00:00"
+ * @example convertUnixToPlainTime(-1, { timeZone: "UTC" }) // "23:59:59.999"
+ * @example convertUnixToPlainTime("1706659200000", { timeZone: "local" }) // system-zone wall clock, e.g. "19:00:00" in America/New_York
+ * @example convertUnixToPlainTime(NaN) // ""
  */
-export declare function convertUnixToPlainTime(unix: number, options?: {
-    epochUnit?: "seconds" | "milliseconds";
+export declare function convertUnixToPlainTime(unix: number | string, options?: {
+    epochUnit?: UnixUnit;
     timeZone?: string;
 }): string;

package/dist/unix/convert/convertUnixToPlainTime.js

@@ -1,38 +1,49 @@
-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 time string in the format "HH:mm:ss".
  *
- * - Converts to PlainTime using the specified or system timezone.
- * - Validates epoch unit ("seconds" | "milliseconds").
+ * - Converts to PlainTime 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 time string in "HH:mm:ss" format or "" on invalid input
  *
- * @example convertUnixToPlainTime(1706659200000) // "00:00:00"
- * @example convertUnixToPlainTime(1706659200, { epochUnit: "seconds" }) // "00:00:00"
- * @example convertUnixToPlainTime(-1) // "23:59:59.999"
+ * @example convertUnixToPlainTime(1706659200000, { timeZone: "UTC" }) // "00:00:00"
+ * @example convertUnixToPlainTime(1706659200, { epochUnit: "seconds", timeZone: "UTC" }) // "00:00:00"
+ * @example convertUnixToPlainTime(-1, { timeZone: "UTC" }) // "23:59:59.999"
+ * @example convertUnixToPlainTime("1706659200000", { timeZone: "local" }) // system-zone wall clock, e.g. "19:00:00" in America/New_York
+ * @example convertUnixToPlainTime(NaN) // ""
  */
 export function convertUnixToPlainTime(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).toPlainTime().toString();
+        }
+        catch {
             return "";
         }
-        const instant = Temporal.Instant.fromEpochMilliseconds(epochUnit === "seconds" ? unix * 1000 : unix);
-        const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-        return zonedDateTime.toPlainTime().toString();
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }