@northguild/gmt 1.18.0 → 1.19.0

package/dist/unix/calculate/subtractUnix.js

@@ -1,5 +1,4 @@
-import { subtractFromZoned, isValidAmount, resolveOverflow, } from "../../internal/index.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { frameInstant, frameZoned, normalizeZoneFrame, readDurationUnits, resolveOverflow, subtractFromZoned, } from "../../internal/index.js";
 import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -10,6 +9,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Validates duration units and values.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
  * - Returns null for invalid input.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So 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 `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
@@ -29,15 +34,12 @@ export function subtractUnix(value, units, options) {
             return null;
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
+        const frame = normalizeZoneFrame(options?.timeZone);
         const overflow = resolveOverflow(options?.overflow);
-        if (!timeZone || epochUnit === null)
+        if (frame === null || epochUnit === null)
             return null;
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (amounts === null) {
             return null;
         }
         const instant = unixEpochToInstant(value, epochUnit);
@@ -45,8 +47,8 @@ export function subtractUnix(value, units, options) {
             return null;
         }
         try {
-            const zdt = instant.toZonedDateTimeISO(timeZone);
-            return toUnixEpoch(subtractFromZoned(zdt, units, { overflow }), epochUnit);
+            const zdt = frameZoned(instant, frame);
+            return toUnixEpoch(frameInstant(subtractFromZoned(zdt, amounts, { overflow }), frame), epochUnit);
         }
         catch {
             return null;

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

@@ -17,6 +17,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - `isSameDay(a, b)` → `areUnixEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUnixEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUnixEqualBy(a, b, "year")`
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So 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 `false`. There `false` is the sentinel,
+ *   not a comparison. An offset to the minute has no such limit.
  *
  * @param value1 first Unix epoch: a safe integer or a digit string
  * @param value2 second Unix epoch, in the same unit
@@ -28,6 +34,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @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
+ * @example areUnixEqualBy(2669999, 2670000, "day", { timeZone: "-00:44:30" }) // false (the local day turns at 00:44:30Z)
  */
 export declare function areUnixEqualBy(value1: number | string, value2: number | string, unit: Temporal.DateTimeUnit | Temporal.PluralUnit<Temporal.DateTimeUnit>, options?: {
     /**
@@ -38,8 +45,10 @@ export declare function areUnixEqualBy(value1: number | string, value2: number |
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the unit boundaries are found in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `false`.
+     * The time zone the unit boundaries are found in: 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
+     * `false`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/compare/areUnixEqualBy.js

@@ -17,6 +17,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - `isSameDay(a, b)` → `areUnixEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUnixEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUnixEqualBy(a, b, "year")`
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So 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 `false`. There `false` is the sentinel,
+ *   not a comparison. An offset to the minute has no such limit.
  *
  * @param value1 first Unix epoch: a safe integer or a digit string
  * @param value2 second Unix epoch, in the same unit
@@ -28,6 +34,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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
+ * @example areUnixEqualBy(2669999, 2670000, "day", { timeZone: "-00:44:30" }) // false (the local day turns at 00:44:30Z)
  */
 export function areUnixEqualBy(value1, value2, unit, options) {
     if (!isOptionsArgument(options)) {

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

@@ -18,6 +18,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToPlainDate("1709164800", { epochUnit: "second", timeZone: "Asia/Tokyo" }) // "2024-02-29"
  * @example convertUnixToPlainDate(1709164800000, { timeZone: "Asia/Tokio" }) // "" (unknown zone)
  * @example convertUnixToPlainDate(NaN) // ""
+ * @example convertUnixToPlainDate(1800000, { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export declare function convertUnixToPlainDate(unix: number | string, options?: {
     /**
@@ -28,8 +29,10 @@ export declare function convertUnixToPlainDate(unix: number | string, options?:
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/convert/convertUnixToPlainDate.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";
 /**
@@ -21,6 +21,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example convertUnixToPlainDate("1709164800", { epochUnit: "second", timeZone: "Asia/Tokyo" }) // "2024-02-29"
  * @example convertUnixToPlainDate(1709164800000, { timeZone: "Asia/Tokio" }) // "" (unknown zone)
  * @example convertUnixToPlainDate(NaN) // ""
+ * @example convertUnixToPlainDate(1800000, { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export function convertUnixToPlainDate(unix, options) {
     try {
@@ -28,14 +29,14 @@ export function convertUnixToPlainDate(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).toPlainDate().toString();
+            return frameWallClock(instant, frame).toPlainDate().toString();
         }
         catch {
             return "";

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

@@ -16,6 +16,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @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) // ""
+ * @example convertUnixToPlainDateTime(45870000, { timeZone: "-00:44:30" }) // "1970-01-01T12:00:00" (a stored offset with seconds)
  */
 export declare function convertUnixToPlainDateTime(unix: number | string, options?: {
     /**
@@ -26,8 +27,10 @@ export declare function convertUnixToPlainDateTime(unix: number | string, option
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/convert/convertUnixToPlainDateTime.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";
 /**
@@ -19,6 +19,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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) // ""
+ * @example convertUnixToPlainDateTime(45870000, { timeZone: "-00:44:30" }) // "1970-01-01T12:00:00" (a stored offset with seconds)
  */
 export function convertUnixToPlainDateTime(unix, options) {
     try {
@@ -26,14 +27,14 @@ export function convertUnixToPlainDateTime(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).toPlainDateTime().toString();
+            return frameWallClock(instant, frame).toString();
         }
         catch {
             return "";

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

@@ -16,6 +16,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @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) // ""
+ * @example convertUnixToPlainTime(45870000, { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export declare function convertUnixToPlainTime(unix: number | string, options?: {
     /**
@@ -26,8 +27,10 @@ export declare function convertUnixToPlainTime(unix: number | string, options?:
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the wall-clock fields are read in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `""`.
+     * The time zone the wall-clock fields are read in: 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
+     * `""`.
      *
      * @defaultValue `"UTC"`
      */

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";
 /**
@@ -19,6 +19,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @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) // ""
+ * @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,9 +7,13 @@ 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
  *

package/dist/unix/convert/convertUnixToZoned.js

@@ -8,9 +8,13 @@ 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
  *

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

@@ -24,8 +24,8 @@ 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"`
      */
@@ -49,6 +49,10 @@ 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)

package/dist/unix/format/formatCalendarUnix.js

@@ -3,6 +3,7 @@ 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
@@ -13,6 +14,10 @@ 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)
@@ -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,6 +76,12 @@ 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)
@@ -89,5 +96,6 @@ export interface FormatRelativeUnixOptions {
  * @example formatRelativeUnix(0, "en-US", 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-US", { 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,6 +20,12 @@ 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)
@@ -33,18 +40,19 @@ import { durationTotal } from "../../internal/zonedWallClockDifference.js";
  * @example formatRelativeUnix(0, "en-US", 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-US", { 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,6 +42,10 @@ 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)

package/dist/unix/format/formatUnix.js

@@ -20,6 +20,10 @@ 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)

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

@@ -4,21 +4,14 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - 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

@@ -4,21 +4,14 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - 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

@@ -4,20 +4,13 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * - 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;