@northguild/gmt 1.18.0 → 1.20.0

package/dist/unix/convert/convertUnixToPlainTime.js

@@ -1,5 +1,5 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
@@ -17,8 +17,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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("1706659200000", { timeZone: "local" }) // system-zone wall clock, e.g. "09:00:00" in Asia/Tokyo
  * @example convertUnixToPlainTime(NaN) // ""
+ * @example convertUnixToPlainTime(45870000, { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export function convertUnixToPlainTime(unix, options) {
     try {
@@ -26,14 +27,14 @@ export function convertUnixToPlainTime(unix, options) {
             return "";
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
-        if (epochUnit === null || !timeZone)
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (epochUnit === null || frame === null)
             return "";
         const instant = unixEpochToInstant(unix, epochUnit);
         if (instant === null)
             return "";
         try {
-            return instant.toZonedDateTimeISO(timeZone).toPlainTime().toString();
+            return frameWallClock(instant, frame).toPlainTime().toString();
         }
         catch {
             return "";

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

@@ -7,13 +7,17 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *   instant outside the Temporal range, returns "".
  * - An explicit `undefined` `options` is the same as omitted; a non-object `options` (such as a
  *   bare `"seconds"` string) returns "".
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param value epoch value: a safe integer or a digit string
- * @param timeZone IANA name or UTC offset
+ * @param timeZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @param options optional: how `value` is read
  * @returns zoned ISO 8601 string or "" on invalid
  *
- * @example convertUnixToZoned(1709164800000, "America/New_York") // "2024-02-28T19:00:00-05:00[America/New_York]"
+ * @example convertUnixToZoned(1709164800000, "Asia/Kolkata") // "2024-02-29T05:30:00+05:30[Asia/Kolkata]"
  * @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)

package/dist/unix/convert/convertUnixToZoned.js

@@ -8,13 +8,17 @@ import { isValidTimeZone } from "../../zoned/validate/index.js";
  *   instant outside the Temporal range, returns "".
  * - An explicit `undefined` `options` is the same as omitted; a non-object `options` (such as a
  *   bare `"seconds"` string) returns "".
+ * - An offset with seconds (`-00:44:30`) returns `""`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param value epoch value: a safe integer or a digit string
- * @param timeZone IANA name or UTC offset
+ * @param timeZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @param options optional: how `value` is read
  * @returns zoned ISO 8601 string or "" on invalid
  *
- * @example convertUnixToZoned(1709164800000, "America/New_York") // "2024-02-28T19:00:00-05:00[America/New_York]"
+ * @example convertUnixToZoned(1709164800000, "Asia/Kolkata") // "2024-02-29T05:30:00+05:30[Asia/Kolkata]"
  * @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)

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

@@ -5,7 +5,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *
  * @example
  * import { FormatCalendarUnixOptions } from "@northguild/gmt/unix";
- * const opts: FormatCalendarUnixOptions = { timeZone: "America/New_York" };
+ * const opts: FormatCalendarUnixOptions = { timeZone: "Asia/Tokyo" };
  */
 export interface FormatCalendarUnixOptions {
     /**
@@ -24,16 +24,17 @@ export interface FormatCalendarUnixOptions {
     epochUnit?: UnixUnit;
     /**
      * The time zone used for both the calendar-day comparison and the rendered clock time: an IANA
-     * name, a UTC offset, or `"local"` for the system time zone. An unknown zone returns `""`, as
-     * ECMA-402 throws RangeError for it.
+     * name, a UTC offset to the minute (what `isValidTimeZone` accepts), or `"local"` for the system
+     * time zone. An unknown zone returns `""`, as ECMA-402 throws RangeError for it.
      *
      * @defaultValue `"UTC"`
      */
     timeZone?: string;
     /**
      * The length of the time-of-day part, as the `timeStyle` of `Intl.DateTimeFormat`. `"short"`
-     * writes hours and minutes, `"medium"` adds seconds, `"long"` adds the short time zone name
-     * ("EDT") and `"full"` the long one ("Eastern Daylight Time"). Any other value returns `""`.
+     * writes hours and minutes, `"medium"` adds seconds, `"long"` adds the locale's short zone
+     * name ("BST" in en-GB, "GMT+1" in en-US) and `"full"` the long one ("British Summer Time" in
+     * English). Any other value returns `""`.
      *
      * @defaultValue `"short"`
      */
@@ -41,7 +42,7 @@ export interface FormatCalendarUnixOptions {
 }
 /**
  * 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
+ * "tomorrow at 14:30" — the unix counterpart of `formatCalendar`. See
  * that function's JSDoc for the day-label/threshold/connector design; this
  * variant compares calendar days and renders the clock time in `timeZone`.
  *
@@ -49,17 +50,21 @@ export interface FormatCalendarUnixOptions {
  *   digits; anything else returns `""`.
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
+ * - An offset with seconds (`-00:44:30`) returns `""`. `Intl.DateTimeFormat` takes a time zone
+ *   identifier only: constructing one with an offset that has seconds throws (ECMA-402, the
+ *   `DateTimeFormat` construction step "If parseResult contains more than one MinuteSecond Parse
+ *   Node, throw a RangeError exception"). Pass the IANA name.
  *
  * @param value unix epoch (string or number, per `epochUnit`) to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: the reference instant, how epochs are read, the zone and the width of the time
  * @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(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(1710685845000, "ja-JP", { epochUnit: "milliseconds", timeZone: "Asia/Tokyo" }) // day label + time relative to "now", or the absolute fallback beyond the ±6-day threshold
+ * @example formatCalendarUnix(1710772200000, "en-GB", { reference: 1710685000000, timeZone: "UTC" }) // "tomorrow at 14:30"
+ * @example formatCalendarUnix("1710772200", "de-DE", { reference: "1710685000", epochUnit: "second" }) // "morgen um 14:30"
+ * @example formatCalendarUnix(1710772200000, "fr-FR", { reference: 1710685000000, timeZone: "Australia/Sidney" }) // "" (unknown zone)
+ * @example formatCalendarUnix(1710772200000, "hi-IN", null as never) // ""
  * @example formatCalendarUnix("not-a-number") // ""
  * @example formatCalendarUnix(1710613800000, ["fr-FR", "en-US"], { reference: 1710507600000 }) // "demain à 18:30"
  */

package/dist/unix/format/formatCalendarUnix.js

@@ -3,9 +3,10 @@ import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { resolveUnixFormatReference } from "../../internal/unixFormatReference.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
+import { isObject } from "../../internal/isObject.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
+ * "tomorrow at 14:30" — the unix counterpart of `formatCalendar`. See
  * that function's JSDoc for the day-label/threshold/connector design; this
  * variant compares calendar days and renders the clock time in `timeZone`.
  *
@@ -13,17 +14,21 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  *   digits; anything else returns `""`.
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
+ * - An offset with seconds (`-00:44:30`) returns `""`. `Intl.DateTimeFormat` takes a time zone
+ *   identifier only: constructing one with an offset that has seconds throws (ECMA-402, the
+ *   `DateTimeFormat` construction step "If parseResult contains more than one MinuteSecond Parse
+ *   Node, throw a RangeError exception"). Pass the IANA name.
  *
  * @param value unix epoch (string or number, per `epochUnit`) to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: the reference instant, how epochs are read, the zone and the width of the time
  * @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(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(1710685845000, "ja-JP", { epochUnit: "milliseconds", timeZone: "Asia/Tokyo" }) // day label + time relative to "now", or the absolute fallback beyond the ±6-day threshold
+ * @example formatCalendarUnix(1710772200000, "en-GB", { reference: 1710685000000, timeZone: "UTC" }) // "tomorrow at 14:30"
+ * @example formatCalendarUnix("1710772200", "de-DE", { reference: "1710685000", epochUnit: "second" }) // "morgen um 14:30"
+ * @example formatCalendarUnix(1710772200000, "fr-FR", { reference: 1710685000000, timeZone: "Australia/Sidney" }) // "" (unknown zone)
+ * @example formatCalendarUnix(1710772200000, "hi-IN", null as never) // ""
  * @example formatCalendarUnix("not-a-number") // ""
  * @example formatCalendarUnix(1710613800000, ["fr-FR", "en-US"], { reference: 1710507600000 }) // "demain à 18:30"
  */
@@ -31,7 +36,7 @@ export function formatCalendarUnix(value, locale, options = {}) {
     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")
+        if (!isObject(options))
             return "";
         const epochUnit = resolveUnixEpochUnit(options.epochUnit);
         if (epochUnit === null)

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

@@ -52,9 +52,10 @@ export interface FormatRelativeUnixOptions {
      */
     reference?: string | number;
     /**
-     * The time zone that anchors a calendar unit (week, month or year): an IANA name, a UTC offset,
-     * or `"local"` for the system time zone. An unknown zone returns `""` whatever the unit, as
-     * ECMA-402 throws RangeError for it.
+     * The time zone that anchors a calendar unit (week, month or year): an IANA name, a UTC offset (a
+     * time zone identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `""` whatever the unit.
      *
      * @defaultValue `"UTC"`
      */
@@ -75,19 +76,26 @@ export interface FormatRelativeUnixOptions {
  *   digits; `largestUnit` and `epochUnit` accept singular or plural names.
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
+ * - **Limit at an offset with seconds.** A month or a year is measured from `reference`, placed in
+ *   the offset's whole-minute zone and moved by its seconds, and the moved instant must be inside
+ *   Temporal's range. So when one is measured and `reference` is within the offset's seconds (under
+ *   a minute) of the last instant Temporal supports (`+275760-09-13T00:00:00Z`) for an offset east
+ *   of UTC, or of the first (`-271821-04-20T00:00:00Z`) for one west, this returns `""`. An offset
+ *   to the minute has no such limit.
  *
  * @param value unix epoch (string or number, per `epochUnit`) to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: the wording, the unit and rounding of the distance, and what it is measured from
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds", reference: 1805358645000 }) // "3 years ago"
- * @example formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds", reference: 1805358645000, largestUnit: "day" }) // "1,096 days ago"
- * @example formatRelativeUnix(0, "en-US", { reference: 37800000, roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
- * @example formatRelativeUnix("0", "en-US", { reference: "1800", epochUnit: "second", largestUnit: "minutes" }) // "30 minutes ago"
- * @example formatRelativeUnix(0, "en-US", { reference: 1800000, timeZone: "Invalid/Zone" }) // ""
- * @example formatRelativeUnix(0, "en-US", null as never) // ""
+ * @example formatRelativeUnix(1710685845000, "en-GB", { epochUnit: "milliseconds", reference: 1805358645000 }) // "3 years ago"
+ * @example formatRelativeUnix(1710685845000, "de-DE", { epochUnit: "milliseconds", reference: 1805358645000, largestUnit: "day" }) // "vor 1.096 Tagen"
+ * @example formatRelativeUnix(0, "en-GB", { reference: 37800000, roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeUnix("0", "ja-JP", { reference: "1800", epochUnit: "second", largestUnit: "minutes" }) // "30 分前"
+ * @example formatRelativeUnix(0, "zh-CN", { reference: 1800000, timeZone: "Invalid/Zone" }) // ""
+ * @example formatRelativeUnix(0, "pt-BR", null as never) // ""
  * @example formatRelativeUnix("not-a-number") // ""
  * @example formatRelativeUnix(1709163000000, ["fr-FR", "en-US"], { reference: 1709164800000 }) // "il y a 30 minutes"
+ * @example formatRelativeUnix(218670000, "en-GB", { reference: 45870000, timeZone: "-00:44:30" }) // "in 2 days" (a stored offset with seconds)
  */
 export declare function formatRelativeUnix(value: string | number, locale?: string | string[], options?: FormatRelativeUnixOptions): string;

package/dist/unix/format/formatRelativeUnix.js

@@ -1,9 +1,10 @@
 // fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { formatRelativeDuration } from "../../internal/formatRelativeDuration.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { frameZoned, normalizeZoneFrame } from "../../internal/zoneFrame.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { resolveUnixFormatReference } from "../../internal/unixFormatReference.js";
 import { durationTotal } from "../../internal/zonedWallClockDifference.js";
+import { isObject } from "../../internal/isObject.js";
 /**
  * Format the relative time between a unix epoch value and a reference instant.
  *
@@ -19,32 +20,39 @@ import { durationTotal } from "../../internal/zonedWallClockDifference.js";
  *   digits; `largestUnit` and `epochUnit` accept singular or plural names.
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
+ * - **Limit at an offset with seconds.** A month or a year is measured from `reference`, placed in
+ *   the offset's whole-minute zone and moved by its seconds, and the moved instant must be inside
+ *   Temporal's range. So when one is measured and `reference` is within the offset's seconds (under
+ *   a minute) of the last instant Temporal supports (`+275760-09-13T00:00:00Z`) for an offset east
+ *   of UTC, or of the first (`-271821-04-20T00:00:00Z`) for one west, this returns `""`. An offset
+ *   to the minute has no such limit.
  *
  * @param value unix epoch (string or number, per `epochUnit`) to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: the wording, the unit and rounding of the distance, and what it is measured from
  * @returns the formatted relative-time string, or "" on invalid input
  *
- * @example formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds", reference: 1805358645000 }) // "3 years ago"
- * @example formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds", reference: 1805358645000, largestUnit: "day" }) // "1,096 days ago"
- * @example formatRelativeUnix(0, "en-US", { reference: 37800000, roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
- * @example formatRelativeUnix("0", "en-US", { reference: "1800", epochUnit: "second", largestUnit: "minutes" }) // "30 minutes ago"
- * @example formatRelativeUnix(0, "en-US", { reference: 1800000, timeZone: "Invalid/Zone" }) // ""
- * @example formatRelativeUnix(0, "en-US", null as never) // ""
+ * @example formatRelativeUnix(1710685845000, "en-GB", { epochUnit: "milliseconds", reference: 1805358645000 }) // "3 years ago"
+ * @example formatRelativeUnix(1710685845000, "de-DE", { epochUnit: "milliseconds", reference: 1805358645000, largestUnit: "day" }) // "vor 1.096 Tagen"
+ * @example formatRelativeUnix(0, "en-GB", { reference: 37800000, roundingMethod: "floor" }) // "11 hours ago" (−10.5 hours floors to −11; the default rounds to 10)
+ * @example formatRelativeUnix("0", "ja-JP", { reference: "1800", epochUnit: "second", largestUnit: "minutes" }) // "30 分前"
+ * @example formatRelativeUnix(0, "zh-CN", { reference: 1800000, timeZone: "Invalid/Zone" }) // ""
+ * @example formatRelativeUnix(0, "pt-BR", null as never) // ""
  * @example formatRelativeUnix("not-a-number") // ""
  * @example formatRelativeUnix(1709163000000, ["fr-FR", "en-US"], { reference: 1709164800000 }) // "il y a 30 minutes"
+ * @example formatRelativeUnix(218670000, "en-GB", { reference: 45870000, timeZone: "-00:44:30" }) // "in 2 days" (a stored offset with seconds)
  */
 export function formatRelativeUnix(value, locale, options = {}) {
     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")
+        if (!isObject(options))
             return "";
         const epochUnit = resolveUnixEpochUnit(options.epochUnit);
         if (epochUnit === null)
             return "";
-        const tz = normalizeTimeZone(options.timeZone);
-        if (!tz)
+        const frame = normalizeZoneFrame(options.timeZone);
+        if (frame === null)
             return "";
         const target = unixEpochToInstant(value, epochUnit);
         if (target === null)
@@ -55,7 +63,7 @@ export function formatRelativeUnix(value, locale, options = {}) {
         try {
             const diff = target.since(reference);
             // month/year are calendrical and need a relativeTo anchor.
-            return formatRelativeDuration(diff, locale, options, (unit) => durationTotal(diff, unit, reference.toZonedDateTimeISO(tz)));
+            return formatRelativeDuration(diff, locale, options, (unit) => durationTotal(diff, unit, frameZoned(reference, frame)));
         }
         catch {
             return "";

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

@@ -12,8 +12,9 @@ export interface FormatUnixOptions extends Intl.DateTimeFormatOptions {
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the value is rendered in: an IANA name, a UTC offset, or `"local"` for the system
-     * time zone. An unknown zone returns `""`, as ECMA-402 throws RangeError for it.
+     * The time zone the value is rendered in: an IANA name, a UTC offset to the minute (what
+     * `isValidTimeZone` accepts), or `"local"` for the system time zone. An unknown zone returns
+     * `""`, as ECMA-402 throws RangeError for it.
      *
      * @defaultValue `"UTC"`
      */
@@ -41,24 +42,28 @@ export interface FormatUnixOptions extends Intl.DateTimeFormatOptions {
  *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
  *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
  * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it.
+ * - An offset with seconds (`-00:44:30`) returns `""`. `Intl.DateTimeFormat` takes a time zone
+ *   identifier only: constructing one with an offset that has seconds throws (ECMA-402, the
+ *   `DateTimeFormat` construction step "If parseResult contains more than one MinuteSecond Parse
+ *   Node, throw a RangeError exception"). Pass the IANA name.
  *
  * @param value unix epoch value to format (string or number, per `epochUnit`)
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: `Intl.DateTimeFormatOptions` fields, plus how `value` is read, the zone and whether its name is shown
  * @returns the formatted date/time string, or "" on invalid input
  *
- * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
- * @example formatUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
- * @example formatUnix("1710685845", "en-US", { epochUnit: "seconds" }) // "3/17/2024, 2:30:45 PM"
- * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds", includeTimeZoneName: true }) // "3/17/2024, 2:30:45 PM UTC"
+ * @example formatUnix("1710685845000", "en-GB", { epochUnit: "milliseconds" }) // "17/03/2024, 14:30:45"
+ * @example formatUnix(1710685845000, "ja-JP", { epochUnit: "milliseconds" }) // "2024/3/17 14:30:45"
+ * @example formatUnix("1710685845", "de-DE", { epochUnit: "seconds" }) // "17.3.2024, 14:30:45"
+ * @example formatUnix("1710685845000", "en-GB", { epochUnit: "milliseconds", includeTimeZoneName: true }) // "17/03/2024, 14:30:45 UTC"
  * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "long" }) // "令和6年2月"
  * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
- * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
- * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
- * @example formatUnix(0, "en-US", { timeZoneName: "short" }) // "1/1/1970, 12:00:00 AM"
- * @example formatUnix(1710685845000, "en-US", { timeZone: "America/New_Yrok" }) // "" (unknown zone)
+ * @example formatUnix(1706970645, "en-GB", { epochUnit: "seconds", era: "long" }) // "03/02/2024 Anno Domini, 14:30:45"
+ * @example formatUnix(1706970645, "en-GB", { epochUnit: "seconds", era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "03/02/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatUnix(0, "fr-FR", { timeZoneName: "short" }) // "01/01/1970 00:00:00"
+ * @example formatUnix(1710685845000, "zh-CN", { timeZone: "Asia/Tokio" }) // "" (unknown zone)
  * @example formatUnix("1710685845000.0") // "" (not a digit string)
- * @example formatUnix(0, "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
+ * @example formatUnix(0, "pt-BR", null as never) // "" (null options, as ECMA-402 rejects them)
  * @example formatUnix("not-a-number") // ""
  * @example formatUnix(1710685845000, ["fr-FR", "en-US"], { dateStyle: "long" }) // "17 mars 2024"
  */

package/dist/unix/format/formatUnix.js

@@ -20,24 +20,28 @@ import { optionOrDefault } from "../../internal/optionOrDefault.js";
  *   the `dateStyle` width, `era` alone dropped the time, and `timeZoneName` alone without
  *   `includeTimeZoneName` returned `""`. Pass the fields the old text showed to keep it.
  * - `options` null returns `""`, as ECMA-402's CoerceOptionsToObject rejects it.
+ * - An offset with seconds (`-00:44:30`) returns `""`. `Intl.DateTimeFormat` takes a time zone
+ *   identifier only: constructing one with an offset that has seconds throws (ECMA-402, the
+ *   `DateTimeFormat` construction step "If parseResult contains more than one MinuteSecond Parse
+ *   Node, throw a RangeError exception"). Pass the IANA name.
  *
  * @param value unix epoch value to format (string or number, per `epochUnit`)
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
  * @param options optional: `Intl.DateTimeFormatOptions` fields, plus how `value` is read, the zone and whether its name is shown
  * @returns the formatted date/time string, or "" on invalid input
  *
- * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
- * @example formatUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3/17/2024, 2:30:45 PM"
- * @example formatUnix("1710685845", "en-US", { epochUnit: "seconds" }) // "3/17/2024, 2:30:45 PM"
- * @example formatUnix("1710685845000", "en-US", { epochUnit: "milliseconds", includeTimeZoneName: true }) // "3/17/2024, 2:30:45 PM UTC"
+ * @example formatUnix("1710685845000", "en-GB", { epochUnit: "milliseconds" }) // "17/03/2024, 14:30:45"
+ * @example formatUnix(1710685845000, "ja-JP", { epochUnit: "milliseconds" }) // "2024/3/17 14:30:45"
+ * @example formatUnix("1710685845", "de-DE", { epochUnit: "seconds" }) // "17.3.2024, 14:30:45"
+ * @example formatUnix("1710685845000", "en-GB", { epochUnit: "milliseconds", includeTimeZoneName: true }) // "17/03/2024, 14:30:45 UTC"
  * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "long" }) // "令和6年2月"
  * @example formatUnix(1706970645, "ja-JP-u-ca-japanese", { epochUnit: "seconds", year: "numeric", month: "numeric" }) // "R6/2" — the pre-1.16.0 text
- * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long" }) // "2/3/2024 Anno Domini, 2:30:45 PM"
- * @example formatUnix(1706970645, "en-US", { epochUnit: "seconds", era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "2/3/2024 Anno Domini" — the pre-1.16.0 text
- * @example formatUnix(0, "en-US", { timeZoneName: "short" }) // "1/1/1970, 12:00:00 AM"
- * @example formatUnix(1710685845000, "en-US", { timeZone: "America/New_Yrok" }) // "" (unknown zone)
+ * @example formatUnix(1706970645, "en-GB", { epochUnit: "seconds", era: "long" }) // "03/02/2024 Anno Domini, 14:30:45"
+ * @example formatUnix(1706970645, "en-GB", { epochUnit: "seconds", era: "long", year: "numeric", month: "numeric", day: "numeric" }) // "03/02/2024 Anno Domini" — the pre-1.16.0 text
+ * @example formatUnix(0, "fr-FR", { timeZoneName: "short" }) // "01/01/1970 00:00:00"
+ * @example formatUnix(1710685845000, "zh-CN", { timeZone: "Asia/Tokio" }) // "" (unknown zone)
  * @example formatUnix("1710685845000.0") // "" (not a digit string)
- * @example formatUnix(0, "en-US", null as never) // "" (null options, as ECMA-402 rejects them)
+ * @example formatUnix(0, "pt-BR", null as never) // "" (null options, as ECMA-402 rejects them)
  * @example formatUnix("not-a-number") // ""
  * @example formatUnix(1710685845000, ["fr-FR", "en-US"], { dateStyle: "long" }) // "17 mars 2024"
  */

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current day string (zero-padded to 2 digits) or "" on failure
+ * @returns current day string (zero-padded to 2 digits)
  *
  * @example getUnixDay() // "29"
- * @example getUnixDay() // "" (on failure)
  */
 export declare function getUnixDay(): string;

package/dist/unix/get/getUnixDay.js

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

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current hour string (zero-padded to 2 digits) or "" on failure
+ * @returns current hour string (zero-padded to 2 digits)
  *
  * @example getUnixHour() // "00"
- * @example getUnixHour() // "" (on failure)
  */
 export declare function getUnixHour(): string;

package/dist/unix/get/getUnixHour.js

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

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current microsecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current microsecond string (zero-padded to 3 digits)
  *
  * @example getUnixMicrosecond() // "456"
- * @example getUnixMicrosecond() // "" (on failure)
  */
 export declare function getUnixMicrosecond(): string;

package/dist/unix/get/getUnixMicrosecond.js

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

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 3 digits.
- * - Returns "" on failure.
  *
- * @returns current millisecond string (zero-padded to 3 digits) or "" on failure
+ * @returns current millisecond string (zero-padded to 3 digits)
  *
  * @example getUnixMillisecond() // "123"
- * @example getUnixMillisecond() // "" (on failure)
  */
 export declare function getUnixMillisecond(): string;

package/dist/unix/get/getUnixMillisecond.js

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

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

@@ -3,11 +3,9 @@
  *
  * - Uses Temporal.Now.instant() converted to UTC zoned date time.
  * - Returns zero-padded string to 2 digits.
- * - Returns "" on failure.
  *
- * @returns current minute string (zero-padded to 2 digits) or "" on failure
+ * @returns current minute string (zero-padded to 2 digits)
  *
  * @example getUnixMinute() // "30"
- * @example getUnixMinute() // "" (on failure)
  */
 export declare function getUnixMinute(): string;