@northguild/gmt 1.17.0 → 1.19.0

package/dist/unix/convert/convertUnixToPlainDateTime.js

@@ -1,19 +1,17 @@
 // 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";
 /**
  * Convert a Unix timestamp to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
  *
- * - Converts to PlainDateTime in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
- *   unknown zone returns "".
+ * - Converts to PlainDateTime in `timeZone`.
  * - `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 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")
+ * @param options optional: how `unix` is read and the zone its wall clock is read in
  * @returns plain datetime string in "YYYY-MM-DDTHH:mm:ss" format or "" on invalid input
  *
  * @example convertUnixToPlainDateTime(1709164800000, { timeZone: "UTC" }) // "2024-02-29T00:00:00"
@@ -21,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 {
@@ -28,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

@@ -2,15 +2,13 @@ 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 in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
- *   unknown zone returns "".
+ * - Converts to PlainTime in `timeZone`.
  * - `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 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")
+ * @param options optional: how `unix` is read and the zone its wall clock is read in
  * @returns plain time string in "HH:mm:ss" format or "" on invalid input
  *
  * @example convertUnixToPlainTime(1706659200000, { timeZone: "UTC" }) // "00:00:00"
@@ -18,8 +16,23 @@ 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?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * 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"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/convert/convertUnixToPlainTime.js

@@ -1,19 +1,17 @@
 // 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";
 /**
  * Convert a Unix timestamp to a plain time string in the format "HH:mm:ss".
  *
- * - Converts to PlainTime in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
- *   unknown zone returns "".
+ * - Converts to PlainTime in `timeZone`.
  * - `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 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")
+ * @param options optional: how `unix` is read and the zone its wall clock is read in
  * @returns plain time string in "HH:mm:ss" format or "" on invalid input
  *
  * @example convertUnixToPlainTime(1706659200000, { timeZone: "UTC" }) // "00:00:00"
@@ -21,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 {
@@ -28,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/convertUnixToUtc.d.ts

@@ -5,12 +5,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - Converts to UTC Instant using Temporal.Instant.
  * - `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 "".
+ * - An explicit `undefined` `options` is the same as omitted; a non-object `options` (such as a
+ *   bare `"seconds"` string) returns "".
  *
  * @param value epoch value: a safe integer or a digit string
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional: how `value` is read
  * @returns UTC Instant string or "" on invalid
  *
  * @example convertUnixToUtc(1709164800000) // "2024-02-29T00:00:00Z"
@@ -21,5 +20,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToUtc(NaN) // ""
  */
 export declare function convertUnixToUtc(value: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
 }): string;

package/dist/unix/convert/convertUnixToUtc.js

@@ -5,12 +5,11 @@ import { resolveUnixEpochUnitOptions, unixEpochToInstant, } from "../../internal
  * - Converts to UTC Instant using Temporal.Instant.
  * - `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 "".
+ * - An explicit `undefined` `options` is the same as omitted; a non-object `options` (such as a
+ *   bare `"seconds"` string) returns "".
  *
  * @param value epoch value: a safe integer or a digit string
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional: how `value` is read
  * @returns UTC Instant string or "" on invalid
  *
  * @example convertUnixToUtc(1709164800000) // "2024-02-29T00:00:00Z"

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

@@ -5,13 +5,16 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - 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 "".
+ * - 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 timeZone identifier
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @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]"
@@ -21,5 +24,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToZoned(NaN, "UTC") // ""
  */
 export declare function convertUnixToZoned(value: number | string, timeZone: string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
 }): string;

package/dist/unix/convert/convertUnixToZoned.js

@@ -6,13 +6,16 @@ import { isValidTimeZone } from "../../zoned/validate/index.js";
  * - 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 "".
+ * - 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 timeZone identifier
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @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]"

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

@@ -3,48 +3,60 @@ 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 {
-    /** Anchor point for the relative day comparison. Accepts UTC ISO strings or epochs (a safe integer or a digit string). */
+    /**
+     * The instant the day label is measured from, as a UTC ISO string, or an epoch in `epochUnit`
+     * given as a safe integer or a digit string. Any other value returns `""`.
+     *
+     * @defaultValue The current instant.
+     */
     reference?: string | number;
+    /**
+     * The unit `value` and a numeric `reference` are counted in: `"seconds"` or `"milliseconds"`,
+     * singular or plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
     /**
-     * IANA timezone used for both the calendar-day comparison and the
-     * rendered clock time. Omitted is `"UTC"`, `"local"` is the system zone,
-     * and an unknown zone makes the result `""` (ECMA-402 throws RangeError).
+     * The time zone used for both the calendar-day comparison and the rendered clock time: 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"`
      */
     timeZone?: string;
-    /** `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half. */
-    timeStyle?: "short" | "medium" | "full";
+    /**
+     * 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 `""`.
+     *
+     * @defaultValue `"short"`
+     */
+    timeStyle?: "short" | "medium" | "long" | "full";
 }
 /**
  * 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
  * that function's JSDoc for the day-label/threshold/connector design; this
- * variant compares calendar days and renders the clock time in `timeZone`
- * (default `"UTC"`).
+ * variant compares calendar days and renders the clock time in `timeZone`.
  *
  * - `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.
+ * - 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: { epochUnit, reference, timeZone, timeStyle }
+ * @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

package/dist/unix/format/formatCalendarUnix.js

@@ -2,22 +2,26 @@ import { formatCalendarInstants } from "../../internal/formatCalendarDays.js";
 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
  * that function's JSDoc for the day-label/threshold/connector design; this
- * variant compares calendar days and renders the clock time in `timeZone`
- * (default `"UTC"`).
+ * variant compares calendar days and renders the clock time in `timeZone`.
  *
  * - `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.
+ * - 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: { epochUnit, reference, timeZone, timeStyle }
+ * @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
@@ -32,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)
@@ -47,7 +51,7 @@ export function formatCalendarUnix(value, locale, options = {}) {
         if (reference === null)
             return "";
         try {
-            return formatCalendarInstants(target, reference, timeZone, locale, options.timeStyle === undefined ? "short" : options.timeStyle);
+            return formatCalendarInstants(target, reference, timeZone, locale, optionOrDefault(options.timeStyle, "short"));
         }
         catch {
             return "";

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

@@ -1,12 +1,64 @@
 import type { RelativeRoundingMethod, RelativeUnit } from "../../types/index.js";
 import type { UnixUnit } from "../validate/isValidUnixUnit.js";
+/**
+ * Options for `formatRelativeUnix`: the wording of the phrase, the unit and rounding of the
+ * distance, and the reference instant, epoch unit and time zone the distance is measured with.
+ */
 export interface FormatRelativeUnixOptions {
+    /**
+     * The length of the unit name, as the `style` of `Intl.RelativeTimeFormat`: `"long"` ("in 3
+     * months"), `"short"` ("in 3 mo.") or `"narrow"` (the locale's most compact form).
+     *
+     * @defaultValue `"long"`
+     */
     style?: "long" | "short" | "narrow";
+    /**
+     * Whether a distance may be written as a word instead of a number, as the `numeric` option of
+     * `Intl.RelativeTimeFormat`. `"auto"` uses the locale's word where it has one ("yesterday", "next
+     * year"); `"always"` writes the number every time ("1 day ago").
+     *
+     * @defaultValue `"auto"`
+     */
     numeric?: "always" | "auto";
+    /**
+     * The unit the distance is written in, whatever its size: `"second"`, `"minute"`, `"hour"`,
+     * `"day"`, `"week"`, `"month"` or `"year"`, singular or plural. Any other value returns `""`.
+     * Omitted, the unit is picked from the distance: second under a minute, minute under an hour,
+     * hour under a day, day under 7 days, week under 28, month under 365 and year beyond.
+     *
+     * @defaultValue None. The unit is picked from the distance.
+     */
     largestUnit?: RelativeUnit | `${RelativeUnit}s`;
+    /**
+     * The way a fractional distance becomes the whole number displayed: `"round"` goes to the nearest
+     * whole number, `"floor"` down and `"ceil"` up. It applies to the signed value, where a past
+     * distance is negative, so `"floor"` turns −1.5 hours into "2 hours ago".
+     *
+     * @defaultValue `"round"`
+     */
     roundingMethod?: RelativeRoundingMethod;
+    /**
+     * The unit `value` and a numeric `reference` are counted in: `"seconds"` or `"milliseconds"`,
+     * singular or plural. Any other value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * The instant the distance is measured from, as a UTC ISO string, or an epoch in `epochUnit`
+     * given as a safe integer or a digit string. Any other value returns `""`.
+     *
+     * @defaultValue The current instant.
+     */
     reference?: string | number;
+    /**
+     * 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"`
+     */
     timeZone?: string;
 }
 /**
@@ -18,18 +70,22 @@ export interface FormatRelativeUnixOptions {
  *   "3 years ago".
  * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
  *   Pass `largestUnit: "day"` to keep a day count.
- * - `roundingMethod` controls how the distance rounds to the display unit.
- * - `timeZone` anchors a calendar unit (week, month or year, auto-picked or forced). Omitted, it is
- *   `"UTC"`, as in every `unix/` function; `"local"` is the system zone; an unknown zone returns
- *   `""` whatever the unit (ECMA-402 throws RangeError for it).
+ * - `largestUnit` is one of the seven units from `"second"` to `"year"`, singular or plural. Any
+ *   other value returns `""`.
  * - `value` and a numeric `reference` are safe integers or strings of optionally negative ASCII
  *   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: { style, numeric, largestUnit, roundingMethod, epochUnit, reference, timeZone }
+ * @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"
@@ -40,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.
  *
@@ -13,18 +14,22 @@ import { durationTotal } from "../../internal/zonedWallClockDifference.js";
  *   "3 years ago".
  * - **Compatibility:** before 1.16.0 week, month and year were never auto-picked ("1,096 days ago").
  *   Pass `largestUnit: "day"` to keep a day count.
- * - `roundingMethod` controls how the distance rounds to the display unit.
- * - `timeZone` anchors a calendar unit (week, month or year, auto-picked or forced). Omitted, it is
- *   `"UTC"`, as in every `unix/` function; `"local"` is the system zone; an unknown zone returns
- *   `""` whatever the unit (ECMA-402 throws RangeError for it).
+ * - `largestUnit` is one of the seven units from `"second"` to `"year"`, singular or plural. Any
+ *   other value returns `""`.
  * - `value` and a numeric `reference` are safe integers or strings of optionally negative ASCII
  *   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: { style, numeric, largestUnit, roundingMethod, epochUnit, reference, timeZone }
+ * @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"
@@ -35,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)
@@ -57,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

@@ -1,19 +1,38 @@
 import type { UnixUnit } from "../validate/index.js";
+/**
+ * Options for `formatUnix`: every `Intl.DateTimeFormatOptions` field, plus the epoch unit, the
+ * time zone the value is rendered in and whether the zone name is shown.
+ */
 export interface FormatUnixOptions extends Intl.DateTimeFormatOptions {
+    /**
+     * The unit `value` is counted in: `"seconds"` or `"milliseconds"`, singular or plural. Any other
+     * value returns `""`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
+    /**
+     * 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"`
+     */
     timeZone?: string;
+    /**
+     * Whether the value is formatted as a zoned date-time, which adds the localized time zone name.
+     * When `false` the wall clock is formatted on its own and `timeZoneName` is ignored.
+     *
+     * @defaultValue `false`
+     */
     includeTimeZoneName?: boolean;
 }
 /**
  * Format a unix epoch value (string or number) as a localized date/time string.
  *
  * - Returns `""` if the input is not a valid unix epoch value for the given `epochUnit`.
- * - `epochUnit` controls whether the input is interpreted as `"milliseconds"` or `"seconds"`; defaults to `"milliseconds"`.
  * - `value` is a safe integer or a string of optionally negative ASCII digits (no whitespace, `+`,
- *   decimal point or exponent); `epochUnit` also accepts `"second"` / `"millisecond"`.
- * - `timeZone` controls the IANA zone used for rendering; defaults to `"UTC"`, `"local"` is the
- *   system zone, and an unknown zone returns `""` (ECMA-402 throws RangeError for it).
- * - `includeTimeZoneName` appends the localized timezone name when true.
+ *   decimal point or exponent).
  * - Without `includeTimeZoneName` the wall clock is formatted as Temporal's ECMA-402 PlainDateTime
  *   format does (`timeZoneName` is ignored); with it, as the ZonedDateTime format does (a short
  *   zone name is added to the defaults). Either way the requested fields and style widths are kept,
@@ -23,10 +42,14 @@ 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: { epochUnit, timeZone, includeTimeZoneName }
+ * @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"