@northguild/gmt 1.16.0 → 1.18.0

package/dist/unix/compare/isAfterUnix.js

@@ -10,7 +10,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value1 first unix epoch: a safe integer or a digit string
  * @param value2 second unix epoch, in the same unit
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional: how both epochs are read
  * @returns `true` if `value1` is after `value2`, otherwise `false`
  *
  * @example isAfterUnix(1706659200, 1704067200) // true

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

@@ -9,7 +9,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  *
  * @param value1 first unix epoch: a safe integer or a digit string
  * @param value2 second unix epoch, in the same unit
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional: how both epochs are read
  * @returns `true` if `value1` is before `value2`, otherwise `false`
  *
  * @example isBeforeUnix(1704067200, 1706659200) // true
@@ -20,5 +20,11 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example isBeforeUnix("-1", "0") // true (digit strings)
  */
 export declare function isBeforeUnix(value1: number | string, value2: number | string, options?: {
+    /**
+     * The unit the epoch values are counted in: `"seconds"` or `"milliseconds"`, singular or
+     * plural. Any other value returns `false`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
 }): boolean;

package/dist/unix/compare/isBeforeUnix.js

@@ -10,7 +10,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * @param value1 first unix epoch: a safe integer or a digit string
  * @param value2 second unix epoch, in the same unit
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional: how both epochs are read
  * @returns `true` if `value1` is before `value2`, otherwise `false`
  *
  * @example isBeforeUnix(1704067200, 1706659200) // true

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

@@ -2,15 +2,13 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a Unix timestamp to a plain date string in the format "YYYY-MM-DD".
  *
- * - Converts to PlainDate in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
- *   unknown zone returns "".
+ * - Converts to PlainDate 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 date string in "YYYY-MM-DD" format or "" on invalid input
  *
  * @example convertUnixToPlainDate(1709164800000, { timeZone: "UTC" }) // "2024-02-29"
@@ -22,6 +20,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToPlainDate(NaN) // ""
  */
 export declare function convertUnixToPlainDate(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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/convert/convertUnixToPlainDate.js

@@ -5,15 +5,13 @@ import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a Unix timestamp to a plain date string in the format "YYYY-MM-DD".
  *
- * - Converts to PlainDate in `timeZone`: omitted is UTC, `"local"` is the system zone, and an
- *   unknown zone returns "".
+ * - Converts to PlainDate 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 date string in "YYYY-MM-DD" format or "" on invalid input
  *
  * @example convertUnixToPlainDate(1709164800000, { timeZone: "UTC" }) // "2024-02-29"

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

@@ -2,15 +2,13 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
 /**
  * Convert a Unix timestamp to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
  *
- * - Converts to PlainDateTime 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"
@@ -20,6 +18,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToPlainDateTime(NaN) // ""
  */
 export declare function convertUnixToPlainDateTime(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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/convert/convertUnixToPlainDateTime.js

@@ -5,15 +5,13 @@ 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"

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"
@@ -20,6 +18,18 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example convertUnixToPlainTime(NaN) // ""
  */
 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, or `"local"` for
+     * the system time zone. An unknown zone returns `""`.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }): string;

package/dist/unix/convert/convertUnixToPlainTime.js

@@ -5,15 +5,13 @@ 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"

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,12 @@ 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 "".
  *
  * @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 UTC offset
+ * @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 +20,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,12 @@ 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 "".
  *
  * @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 UTC offset
+ * @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,56 @@ 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, 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.
  *
  * @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,21 @@ 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";
 /**
  * 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.
  *
  * @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
@@ -47,7 +46,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,63 @@
 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,
+     * or `"local"` for the system time zone. An unknown zone returns `""` whatever the unit, as
+     * ECMA-402 throws RangeError for it.
+     *
+     * @defaultValue `"UTC"`
+     */
     timeZone?: string;
 }
 /**
@@ -18,10 +69,8 @@ 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
@@ -29,7 +78,7 @@ export interface FormatRelativeUnixOptions {
  *
  * @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"

package/dist/unix/format/formatRelativeUnix.js

@@ -13,10 +13,8 @@ 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
@@ -24,7 +22,7 @@ import { durationTotal } from "../../internal/zonedWallClockDifference.js";
  *
  * @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"

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

@@ -1,19 +1,37 @@
 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, 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,
@@ -26,7 +44,7 @@ export interface FormatUnixOptions extends Intl.DateTimeFormatOptions {
  *
  * @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"

package/dist/unix/format/formatUnix.js

@@ -3,16 +3,14 @@ import { formatWallClockOrZoned } from "../../internal/instantFormatOptions.js";
 import { normalizeDateTime } from "../../internal/normalizeDateTime.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * 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,
@@ -25,7 +23,7 @@ import { resolveUnixEpochUnit, unixEpochToInstant, } from "../../internal/unixEp
  *
  * @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"
@@ -48,7 +46,10 @@ export function formatUnix(value, locale, options) {
         // ECMA-402 CoerceOptionsToObject: undefined is defaults; null is a TypeError.
         if (options === null)
             return "";
-        const { epochUnit, timeZone, includeTimeZoneName = false, ...intlOptions } = options ?? {};
+        // Each option is read once (GetOption), inherited ones included.
+        const epochUnit = options?.epochUnit;
+        const includeTimeZoneName = optionOrDefault(options?.includeTimeZoneName, false);
+        const { timeZone, ...intlOptions } = readDateTimeFormatOptions(options);
         const resolvedUnit = resolveUnixEpochUnit(epochUnit);
         if (resolvedUnit === null)
             return "";