@northguild/gmt 1.14.2 → 1.16.0

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 "";
     }
 }

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

@@ -1,17 +1,25 @@
-import { type UnixUnit } from "../validate/isValidUnixUnit.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a unix epoch value to a UTC Instant ISO string.
  *
  * - Converts to UTC Instant using Temporal.Instant.
- * - Validates value and epoch unit ("seconds" | "milliseconds").
- * - Returns "" for invalid input.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits; anything else, or an
+ *   instant outside the Temporal range, returns "".
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. An explicit `undefined` is the same as omitted; a non-object `options` (such
+ *   as a bare `"seconds"` string) returns "".
  *
- * @param value epoch value (number)
- * @param unit optional unit, "seconds" or "milliseconds"
+ * @param value epoch value: a safe integer or a digit string
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns UTC Instant string or "" on invalid
  *
  * @example convertUnixToUtc(1709164800000) // "2024-02-29T00:00:00Z"
- * @example convertUnixToUtc(1709164800, "seconds") // "2024-02-29T00:00:00Z"
+ * @example convertUnixToUtc(1709164800, { epochUnit: "seconds" }) // "2024-02-29T00:00:00Z"
+ * @example convertUnixToUtc("1709164800", { epochUnit: "second" }) // "2024-02-29T00:00:00Z"
  * @example convertUnixToUtc(-1) // "1969-12-31T23:59:59.999Z"
+ * @example convertUnixToUtc(1709164800, "seconds" as never) // "" (options must be an object)
+ * @example convertUnixToUtc(NaN) // ""
  */
-export declare function convertUnixToUtc(value: number, ...unitInput: [unit?: UnixUnit]): string;
+export declare function convertUnixToUtc(value: number | string, options?: {
+    epochUnit?: UnixUnit;
+}): string;

package/dist/unix/convert/convertUnixToUtc.js

@@ -1,31 +1,36 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount } from "../../internal/index.js";
-import { isValidUnixUnit } from "../validate/isValidUnixUnit.js";
+import { resolveUnixEpochUnitOptions, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 /**
  * Convert a unix epoch value to a UTC Instant ISO string.
  *
  * - Converts to UTC Instant using Temporal.Instant.
- * - Validates value and epoch unit ("seconds" | "milliseconds").
- * - Returns "" for invalid input.
+ * - `value` is a safe integer or a string of optionally negative ASCII digits; anything else, or an
+ *   instant outside the Temporal range, returns "".
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. An explicit `undefined` is the same as omitted; a non-object `options` (such
+ *   as a bare `"seconds"` string) returns "".
  *
- * @param value epoch value (number)
- * @param unit optional unit, "seconds" or "milliseconds"
+ * @param value epoch value: a safe integer or a digit string
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns UTC Instant string or "" on invalid
  *
  * @example convertUnixToUtc(1709164800000) // "2024-02-29T00:00:00Z"
- * @example convertUnixToUtc(1709164800, "seconds") // "2024-02-29T00:00:00Z"
+ * @example convertUnixToUtc(1709164800, { epochUnit: "seconds" }) // "2024-02-29T00:00:00Z"
+ * @example convertUnixToUtc("1709164800", { epochUnit: "second" }) // "2024-02-29T00:00:00Z"
  * @example convertUnixToUtc(-1) // "1969-12-31T23:59:59.999Z"
+ * @example convertUnixToUtc(1709164800, "seconds" as never) // "" (options must be an object)
+ * @example convertUnixToUtc(NaN) // ""
  */
-export function convertUnixToUtc(value, ...unitInput) {
-    const resolvedUnit = unitInput.length === 0 ? "milliseconds" : unitInput[0];
-    if (!isValidAmount(value) || !isValidUnixUnit(resolvedUnit ?? "")) {
-        return "";
-    }
+export function convertUnixToUtc(value, options) {
     try {
-        const instant = Temporal.Instant.fromEpochMilliseconds(resolvedUnit === "seconds" ? value * 1000 : value);
-        return instant.toString();
+        const epochUnit = resolveUnixEpochUnitOptions(options);
+        if (epochUnit === null) {
+            return "";
+        }
+        return unixEpochToInstant(value, epochUnit)?.toString() ?? "";
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,18 +1,25 @@
-import { type UnixUnit } from "../../unix/validate/isValidUnixUnit.js";
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a unix epoch value to a zoned ISO 8601 datetime string.
  *
- * - Converts to ZonedDateTime using the specified timezone.
- * - Validates value, timezone, and epoch unit.
- * - Returns "" for invalid input.
+ * - Converts to ZonedDateTime using the specified timezone (required; an unknown zone returns "").
+ * - `value` is a safe integer or a string of optionally negative ASCII digits; anything else, or an
+ *   instant outside the Temporal range, returns "".
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. An explicit `undefined` is the same as omitted; a non-object `options` (such
+ *   as a bare `"seconds"` string) returns "".
  *
- * @param value epoch value (number)
+ * @param value epoch value: a safe integer or a digit string
  * @param timeZone IANA timeZone identifier
- * @param unit optional unit, "seconds" or "milliseconds"
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns zoned ISO 8601 string or "" on invalid
  *
- * @example convertUnixToZoned(1709164800000, "America/New_York") // "2024-02-29T00:00:00-05:00[America/New_York]"
- * @example convertUnixToZoned(1709164800, "UTC", "seconds") // "2024-02-29T00:00:00+00:00[UTC]"
- * @example convertUnixToZoned(-1, "UTC") // "1969-12-31T23:59:59.999Z[UTC]"
+ * @example convertUnixToZoned(1709164800000, "America/New_York") // "2024-02-28T19:00:00-05:00[America/New_York]"
+ * @example convertUnixToZoned(1709164800, "UTC", { epochUnit: "seconds" }) // "2024-02-29T00:00:00+00:00[UTC]"
+ * @example convertUnixToZoned("-1", "UTC") // "1969-12-31T23:59:59.999+00:00[UTC]"
+ * @example convertUnixToZoned(1709164800, "UTC", "seconds" as never) // "" (options must be an object)
+ * @example convertUnixToZoned(NaN, "UTC") // ""
  */
-export declare function convertUnixToZoned(value: number, timeZone: string, ...unitInput: [unit?: UnixUnit]): string;
+export declare function convertUnixToZoned(value: number | string, timeZone: string, options?: {
+    epochUnit?: UnixUnit;
+}): string;

package/dist/unix/convert/convertUnixToZoned.js

@@ -1,35 +1,46 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount } from "../../internal/index.js";
-import { isValidUnixUnit, } from "../../unix/validate/isValidUnixUnit.js";
+import { resolveUnixEpochUnitOptions, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isValidTimeZone } from "../../zoned/validate/index.js";
 /**
  * Convert a unix epoch value to a zoned ISO 8601 datetime string.
  *
- * - Converts to ZonedDateTime using the specified timezone.
- * - Validates value, timezone, and epoch unit.
- * - Returns "" for invalid input.
+ * - Converts to ZonedDateTime using the specified timezone (required; an unknown zone returns "").
+ * - `value` is a safe integer or a string of optionally negative ASCII digits; anything else, or an
+ *   instant outside the Temporal range, returns "".
+ * - `options.epochUnit` is `"seconds"` or `"milliseconds"` (singular accepted), default
+ *   `"milliseconds"`. An explicit `undefined` is the same as omitted; a non-object `options` (such
+ *   as a bare `"seconds"` string) returns "".
  *
- * @param value epoch value (number)
+ * @param value epoch value: a safe integer or a digit string
  * @param timeZone IANA timeZone identifier
- * @param unit optional unit, "seconds" or "milliseconds"
+ * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
  * @returns zoned ISO 8601 string or "" on invalid
  *
- * @example convertUnixToZoned(1709164800000, "America/New_York") // "2024-02-29T00:00:00-05:00[America/New_York]"
- * @example convertUnixToZoned(1709164800, "UTC", "seconds") // "2024-02-29T00:00:00+00:00[UTC]"
- * @example convertUnixToZoned(-1, "UTC") // "1969-12-31T23:59:59.999Z[UTC]"
+ * @example convertUnixToZoned(1709164800000, "America/New_York") // "2024-02-28T19:00:00-05:00[America/New_York]"
+ * @example convertUnixToZoned(1709164800, "UTC", { epochUnit: "seconds" }) // "2024-02-29T00:00:00+00:00[UTC]"
+ * @example convertUnixToZoned("-1", "UTC") // "1969-12-31T23:59:59.999+00:00[UTC]"
+ * @example convertUnixToZoned(1709164800, "UTC", "seconds" as never) // "" (options must be an object)
+ * @example convertUnixToZoned(NaN, "UTC") // ""
  */
-export function convertUnixToZoned(value, timeZone, ...unitInput) {
-    const resolvedUnit = unitInput.length === 0 ? "milliseconds" : unitInput[0];
-    if (!isValidAmount(value) ||
-        !isValidTimeZone(timeZone) ||
-        !isValidUnixUnit(resolvedUnit ?? "")) {
-        return "";
-    }
+export function convertUnixToZoned(value, timeZone, options) {
     try {
-        const instant = Temporal.Instant.fromEpochMilliseconds(resolvedUnit === "seconds" ? value * 1000 : value);
-        return instant.toZonedDateTimeISO(timeZone).toString();
+        const epochUnit = resolveUnixEpochUnitOptions(options);
+        if (epochUnit === null || !isValidTimeZone(timeZone)) {
+            return "";
+        }
+        const instant = unixEpochToInstant(value, epochUnit);
+        if (instant === null) {
+            return "";
+        }
+        try {
+            return instant.toZonedDateTimeISO(timeZone).toString();
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,10 +1,29 @@
+import type { UnixUnit } from "../validate/isValidUnixUnit.js";
+/**
+ * Options for `formatCalendarUnix`. Like `formatCalendar`, it takes a `reference` and a `timeStyle`
+ * (here also `"full"`); it adds `epochUnit` and `timeZone` for the unix domain.
+ *
+ * @remarks Members:
+ *
+ * | Member | Type | Default | Description |
+ * | --- | --- | --- | --- |
+ * | `reference` | `string\|number` | now (UTC) | Anchor epoch/ISO for the "today/tomorrow" comparison. |
+ * | `epochUnit` | `"milliseconds"\|"seconds"` | `"milliseconds"` | Interpretation of epoch `value`/`reference`; singular names are accepted. |
+ * | `timeZone` | `string` | `"UTC"` | IANA zone for both day-comparison and clock-time rendering; `"local"` is the system zone; an unknown zone returns `""`. |
+ * | `timeStyle` | `"short"\|"medium"\|"full"` | `"short"` | `Intl` `timeStyle` for the time-of-day portion. |
+ *
+ * @example
+ * import { FormatCalendarUnixOptions } from "@northguild/gmt/unix";
+ * const opts: FormatCalendarUnixOptions = { timeZone: "America/New_York" };
+ */
 export interface FormatCalendarUnixOptions {
-    epochUnit?: "milliseconds" | "seconds";
+    /** Anchor point for the relative day comparison. Accepts UTC ISO strings or epochs (a safe integer or a digit string). */
     reference?: string | number;
+    epochUnit?: UnixUnit;
     /**
      * IANA timezone used for both the calendar-day comparison and the
-     * rendered clock time. Resolved via `normalizeTimeZone` — `"local"` for
-     * the system zone, an invalid/omitted value falls back to `"UTC"`.
+     * rendered clock time. Omitted is `"UTC"`, `"local"` is the system zone,
+     * and an unknown zone makes the result `""` (ECMA-402 throws RangeError).
      */
     timeZone?: string;
     /** `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half. */
@@ -17,13 +36,23 @@ export interface FormatCalendarUnixOptions {
  * variant compares calendar days and renders the clock time in `timeZone`
  * (default `"UTC"`).
  *
+ * - `value` and a numeric `reference` are safe integers or strings of optionally negative ASCII
+ *   digits; anything else returns `""`.
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
+ * - An unknown `timeZone` returns `""`; `"local"` is the system zone.
+ *
  * @param value unix epoch (string or number, per `epochUnit`) to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { epochUnit, reference, timeZone, timeStyle }
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendarUnix(1710685845000, "en-US", { epochUnit: "milliseconds", timeZone: "America/New_York" }) // day label + time relative to "now", or the absolute fallback beyond the ±6-day threshold
- * @example formatCalendarUnix(value, "en-US", { reference: 1710685000000 }) // e.g. "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix(1710772200000, "en-US", { reference: 1710685000000, timeZone: "UTC" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix("1710772200", "en-US", { reference: "1710685000", epochUnit: "second" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix(1710772200000, "en-US", { reference: 1710685000000, timeZone: "America/New_Yrok" }) // "" (unknown zone)
+ * @example formatCalendarUnix(1710772200000, "en-US", null as never) // ""
  * @example formatCalendarUnix("not-a-number") // ""
+ * @example formatCalendarUnix(1710613800000, ["fr-FR", "en-US"], { reference: 1710507600000 }) // "demain à 18:30"
  */
-export declare function formatCalendarUnix(value: string | number, locale?: string, options?: FormatCalendarUnixOptions): string;
+export declare function formatCalendarUnix(value: string | number, locale?: string | string[], options?: FormatCalendarUnixOptions): string;

package/dist/unix/format/formatCalendarUnix.js

@@ -1,34 +1,7 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { joinDateTimeConnector, normalizeDateTime } from "../../internal/index.js";
+import { formatCalendarInstants } from "../../internal/formatCalendarDays.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
-import { isValidUtc } from "../../utc/validate/index.js";
-const ABS_DAY_THRESHOLD = 6;
-function toInstant(raw, epochUnit) {
-    let n;
-    if (typeof raw === "number") {
-        n = raw;
-    }
-    else if (typeof raw === "string") {
-        const trimmed = raw.trim();
-        // Mirror formatUnix.parseEpochMs: only accept integer-looking strings,
-        // so "" / "not-a-date" / "12.5" don't silently coerce to 0/12.
-        if (!/^-?\d+$/.test(trimmed))
-            return null;
-        n = Number(trimmed);
-    }
-    else {
-        return null;
-    }
-    if (!Number.isFinite(n))
-        return null;
-    try {
-        const ms = epochUnit === "seconds" ? n * 1000 : n;
-        return Temporal.Instant.fromEpochMilliseconds(ms);
-    }
-    catch {
-        return null;
-    }
-}
+import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+import { resolveUnixFormatReference } from "../../internal/unixFormatReference.js";
 /**
  * Format a unix epoch value as a relative day label plus time-of-day, e.g.
  * "Tomorrow at 2:30 PM" — the unix counterpart of `formatCalendar`. See
@@ -36,72 +9,53 @@ function toInstant(raw, epochUnit) {
  * variant compares calendar days and renders the clock time in `timeZone`
  * (default `"UTC"`).
  *
+ * - `value` and a numeric `reference` are safe integers or strings of optionally negative ASCII
+ *   digits; anything else returns `""`.
+ * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
+ *   rejects it.
+ * - An unknown `timeZone` returns `""`; `"local"` is the system zone.
+ *
  * @param value unix epoch (string or number, per `epochUnit`) to format
- * @param locale optional: BCP 47 locale tag
+ * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: { epochUnit, reference, timeZone, timeStyle }
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendarUnix(1710685845000, "en-US", { epochUnit: "milliseconds", timeZone: "America/New_York" }) // day label + time relative to "now", or the absolute fallback beyond the ±6-day threshold
- * @example formatCalendarUnix(value, "en-US", { reference: 1710685000000 }) // e.g. "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix(1710772200000, "en-US", { reference: 1710685000000, timeZone: "UTC" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix("1710772200", "en-US", { reference: "1710685000", epochUnit: "second" }) // "tomorrow at 2:30 PM"
+ * @example formatCalendarUnix(1710772200000, "en-US", { reference: 1710685000000, timeZone: "America/New_Yrok" }) // "" (unknown zone)
+ * @example formatCalendarUnix(1710772200000, "en-US", null as never) // ""
  * @example formatCalendarUnix("not-a-number") // ""
+ * @example formatCalendarUnix(1710613800000, ["fr-FR", "en-US"], { reference: 1710507600000 }) // "demain à 18:30"
  */
 export function formatCalendarUnix(value, locale, options = {}) {
-    const epochUnit = options.epochUnit ?? "milliseconds";
-    const target = toInstant(value, epochUnit);
-    if (target === null)
-        return "";
-    let reference;
-    if (options.reference === undefined) {
-        try {
-            reference = Temporal.Now.instant();
-        }
-        catch {
+    try {
+        // Temporal GetOptionsObject: undefined is defaults (the parameter default); anything else that is
+        // not an object, including null, is a TypeError.
+        if (options === null || typeof options !== "object")
             return "";
-        }
-    }
-    else if (typeof options.reference === "string") {
-        const numericRef = toInstant(options.reference, epochUnit);
-        if (numericRef !== null) {
-            reference = numericRef;
-        }
-        else if (isValidUtc(options.reference)) {
-            try {
-                reference = Temporal.Instant.from(options.reference);
-            }
-            catch {
-                return "";
-            }
-        }
-        else {
+        const epochUnit = resolveUnixEpochUnit(options.epochUnit);
+        if (epochUnit === null)
+            return "";
+        const timeZone = normalizeTimeZone(options.timeZone);
+        if (!timeZone)
+            return "";
+        const target = unixEpochToInstant(value, epochUnit);
+        if (target === null)
             return "";
+        const reference = resolveUnixFormatReference(options.reference, epochUnit);
+        if (reference === null)
+            return "";
+        try {
+            return formatCalendarInstants(target, reference, timeZone, locale, options.timeStyle === undefined ? "short" : options.timeStyle);
         }
-    }
-    else {
-        const ref = toInstant(options.reference, epochUnit);
-        if (ref === null)
+        catch {
             return "";
-        reference = ref;
-    }
-    try {
-        const timeZone = normalizeTimeZone(options.timeZone);
-        const timeStyle = options.timeStyle ?? "short";
-        const targetDate = target.toZonedDateTimeISO(timeZone).toPlainDate();
-        const referenceDate = reference.toZonedDateTimeISO(timeZone).toPlainDate();
-        const diffDays = targetDate.since(referenceDate).days;
-        const epochMilliseconds = Number(target.epochMilliseconds);
-        if (Math.abs(diffDays) > ABS_DAY_THRESHOLD) {
-            return normalizeDateTime(new Intl.DateTimeFormat(locale, {
-                dateStyle: "long",
-                timeStyle,
-                timeZone,
-            }).format(epochMilliseconds));
         }
-        const dayLabel = new Intl.RelativeTimeFormat(locale, {
-            numeric: "auto",
-        }).format(diffDays, "day");
-        return normalizeDateTime(joinDateTimeConnector(epochMilliseconds, timeZone, locale, dayLabel, timeStyle));
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }