@northguild/gmt 1.16.0 → 1.18.0

package/dist/utc/calculate/startOfUtc.d.ts

@@ -5,12 +5,11 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * - Converts to ZonedDateTime, sets to start of unit, converts back to Instant.
  * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string
  * @param unit date or time unit, singular or plural, to specify the start
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param options Where a week starts, and the precision of the result
  * @returns UTC Instant string representing the start of the unit, or "" on invalid input
  *
  * @example startOfUtc("2024-03-15T14:30:45Z", "year") // "2024-01-01T00:00:00Z"
@@ -19,6 +18,20 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example startOfUtc("invalid", "year") // ""
  */
 export declare function startOfUtc(value: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. Fewer digits than `unit` names truncate, as Temporal's `toString` does.
+     *
+     * @defaultValue The digits `unit` names: `3` for `"millisecond"`, `6` for `"microsecond"`, `9`
+     * for `"nanosecond"` and `0` for any coarser unit.
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/utc/calculate/startOfUtc.js

@@ -5,12 +5,11 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *
  * - Converts to ZonedDateTime, sets to start of unit, converts back to Instant.
  * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string
  * @param unit date or time unit, singular or plural, to specify the start
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param options Where a week starts, and the precision of the result
  * @returns UTC Instant string representing the start of the unit, or "" on invalid input
  *
  * @example startOfUtc("2024-03-15T14:30:45Z", "year") // "2024-01-01T00:00:00Z"

package/dist/utc/calculate/subtractUtc.d.ts

@@ -6,12 +6,9 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * - Validates duration units and values.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
- * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string after subtraction, or "" on invalid input
  *
  * @example subtractUtc("2024-03-15T12:00:00Z", { days: 5 }) // "2024-03-10T12:00:00Z"
@@ -19,5 +16,11 @@ import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
  * @example subtractUtc("invalid", { days: 5 }) // ""
  */
 export declare function subtractUtc(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    /**
+     * What to do when the result is not a real date. `"constrain"` clamps it to the last valid day,
+     * so Mar 31 − 1 month is Feb 29/28 (TC39 Temporal); `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/utc/calculate/subtractUtc.js

@@ -11,12 +11,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Validates duration units and values.
  * - Returns "" for invalid input.
  *
- * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
- * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
- *
  * @param value ISO UTC datetime string (e.g. "2024-03-10T12:00:00Z")
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
- * @param options optional: overflow ("constrain" | "reject")
+ * @param options How an out-of-range result is handled
  * @returns UTC Instant string after subtraction, or "" on invalid input
  *
  * @example subtractUtc("2024-03-15T12:00:00Z", { days: 5 }) // "2024-03-10T12:00:00Z"

package/dist/utc/compare/areUtcEqualBy.d.ts

@@ -7,13 +7,12 @@ import { Temporal } from "@js-temporal/polyfill";
  *   unambiguous).
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
  * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  * - Takes no `fractionalSecondDigits`: equality compares full-precision `unit` boundaries, and output
  *   digits cannot change which bucket a value is in. That ignored option was removed in 1.16.0; to
  *   compare more coarsely, pass a coarser unit (0 digits is `"second"`, 3 is `"millisecond"`).
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areUtcEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUtcEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUtcEqualBy(a, b, "year")`
@@ -21,7 +20,7 @@ import { Temporal } from "@js-temporal/polyfill";
  * @param value1 first UTC ISO datetime string
  * @param value2 second UTC ISO datetime string
  * @param unit date or time unit, singular or plural, to compare by
- * @param options optional: weekStartsOn ("monday" | "sunday")
+ * @param options Where a week starts
  * @returns true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areUtcEqualBy("2024-03-15T02:00:00Z", "2024-03-15T22:00:00Z", "day") // true
@@ -31,5 +30,12 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example areUtcEqualBy("invalid", "2024-03-15T02:00:00Z", "day") // false
  */
 export declare function areUtcEqualBy(value1: string, value2: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, options?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * false, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): boolean;

package/dist/utc/compare/areUtcEqualBy.js

@@ -13,13 +13,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   unambiguous).
  * - `"month"` requires the same month AND year, matching `areDateTimesEqualBy`.
  * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  * - Takes no `fractionalSecondDigits`: equality compares full-precision `unit` boundaries, and output
  *   digits cannot change which bucket a value is in. That ignored option was removed in 1.16.0; to
  *   compare more coarsely, pass a coarser unit (0 digits is `"second"`, 3 is `"millisecond"`).
  *
- * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * Mapping from date-fns:
  * - `isSameDay(a, b)` → `areUtcEqualBy(a, b, "day")`
  * - `isSameMonth(a, b)` → `areUtcEqualBy(a, b, "month")`
  * - `isSameYear(a, b)` → `areUtcEqualBy(a, b, "year")`
@@ -27,7 +26,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value1 first UTC ISO datetime string
  * @param value2 second UTC ISO datetime string
  * @param unit date or time unit, singular or plural, to compare by
- * @param options optional: weekStartsOn ("monday" | "sunday")
+ * @param options Where a week starts
  * @returns true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input
  *
  * @example areUtcEqualBy("2024-03-15T02:00:00Z", "2024-03-15T22:00:00Z", "day") // true

package/dist/utc/convert/convertUtcToPlainDate.d.ts

@@ -1,12 +1,11 @@
 /**
  * Convert a UTC datetime string to a plain date string in the format "YYYY-MM-DD".
  *
- * - Converts to specified timezone before extracting date.
- * - Defaults to UTC if no timezone specified.
+ * - Converts to the `timeZone` option's zone before extracting the date.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
- * @param options optional: timeZone (IANA)
+ * @param options The time zone the value is read in
  * @returns plain date string in "YYYY-MM-DD" format or "" on invalid input
  *
  * @example convertUtcToPlainDate("2024-02-29T00:00:00Z") // "2024-02-29"
@@ -14,5 +13,11 @@
  * @example convertUtcToPlainDate("invalid") // ""
  */
 export declare function convertUtcToPlainDate(value: string, options?: {
+    /**
+     * 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/utc/convert/convertUtcToPlainDate.js

@@ -1,17 +1,16 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../../zoned/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain date string in the format "YYYY-MM-DD".
  *
- * - Converts to specified timezone before extracting date.
- * - Defaults to UTC if no timezone specified.
+ * - Converts to the `timeZone` option's zone before extracting the date.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
- * @param options optional: timeZone (IANA)
+ * @param options The time zone the value is read in
  * @returns plain date string in "YYYY-MM-DD" format or "" on invalid input
  *
  * @example convertUtcToPlainDate("2024-02-29T00:00:00Z") // "2024-02-29"
@@ -23,8 +22,8 @@ export function convertUtcToPlainDate(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const { timeZone = "UTC" } = options ?? {};
-        if (!isValidTimeZone(timeZone))
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (timeZone === "")
             return "";
         if (!isValidUtc(value))
             return "";

package/dist/utc/convert/convertUtcToPlainDateTime.d.ts

@@ -1,12 +1,11 @@
 /**
  * Convert a UTC datetime string to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
  *
- * - Converts to specified timezone before extracting datetime.
- * - Defaults to UTC if no timezone specified.
+ * - Converts to the `timeZone` option's zone before extracting the datetime.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
- * @param options optional: timeZone (IANA)
+ * @param options The time zone the value is read in
  * @returns plain datetime string in "YYYY-MM-DDTHH:mm:ss" format or "" on invalid input
  *
  * @example convertUtcToPlainDateTime("2024-02-29T00:00:00Z") // "2024-02-29T00:00:00"
@@ -14,5 +13,11 @@
  * @example convertUtcToPlainDateTime("invalid") // ""
  */
 export declare function convertUtcToPlainDateTime(value: string, options?: {
+    /**
+     * 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/utc/convert/convertUtcToPlainDateTime.js

@@ -1,17 +1,16 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../../zoned/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain datetime string in the format "YYYY-MM-DDTHH:mm:ss".
  *
- * - Converts to specified timezone before extracting datetime.
- * - Defaults to UTC if no timezone specified.
+ * - Converts to the `timeZone` option's zone before extracting the datetime.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
- * @param options optional: timeZone (IANA)
+ * @param options The time zone the value is read in
  * @returns plain datetime string in "YYYY-MM-DDTHH:mm:ss" format or "" on invalid input
  *
  * @example convertUtcToPlainDateTime("2024-02-29T00:00:00Z") // "2024-02-29T00:00:00"
@@ -23,8 +22,8 @@ export function convertUtcToPlainDateTime(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const { timeZone = "UTC" } = options ?? {};
-        if (!isValidTimeZone(timeZone))
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (timeZone === "")
             return "";
         if (!isValidUtc(value))
             return "";

package/dist/utc/convert/convertUtcToPlainTime.d.ts

@@ -1,12 +1,11 @@
 /**
  * Convert a UTC datetime string to a plain time string in the format "HH:mm:ss".
  *
- * - Converts to specified timezone before extracting time.
- * - Defaults to UTC if no timezone specified.
+ * - Converts to the `timeZone` option's zone before extracting the time.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
- * @param options optional: timeZone (IANA)
+ * @param options The time zone the value is read in
  * @returns plain time string in "HH:mm:ss" format or "" on invalid input
  *
  * @example convertUtcToPlainTime("2024-02-29T00:00:00Z") // "00:00:00"
@@ -14,5 +13,11 @@
  * @example convertUtcToPlainTime("invalid") // ""
  */
 export declare function convertUtcToPlainTime(value: string, options?: {
+    /**
+     * 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/utc/convert/convertUtcToPlainTime.js

@@ -1,17 +1,16 @@
 // fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../../zoned/index.js";
+import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { isValidUtc } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Convert a UTC datetime string to a plain time string in the format "HH:mm:ss".
  *
- * - Converts to specified timezone before extracting time.
- * - Defaults to UTC if no timezone specified.
+ * - Converts to the `timeZone` option's zone before extracting the time.
  * - Returns "" for invalid input.
  *
  * @param value UTC datetime string (e.g., "2024-02-29T00:00:00Z")
- * @param options optional: timeZone (IANA)
+ * @param options The time zone the value is read in
  * @returns plain time string in "HH:mm:ss" format or "" on invalid input
  *
  * @example convertUtcToPlainTime("2024-02-29T00:00:00Z") // "00:00:00"
@@ -23,8 +22,8 @@ export function convertUtcToPlainTime(value, options) {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const { timeZone = "UTC" } = options ?? {};
-        if (!isValidTimeZone(timeZone))
+        const timeZone = normalizeTimeZone(options?.timeZone);
+        if (timeZone === "")
             return "";
         if (!isValidUtc(value))
             return "";

package/dist/utc/convert/convertUtcToUnix.d.ts

@@ -4,13 +4,12 @@ import type { UnixUnit } from "../../unix/validate/isValidUnixUnit.js";
  *
  * - Uses Temporal.Instant.from to parse.
  * - Seconds floor toward −∞, so `"1969-12-31T23:59:59.5Z"` is second `-1` (POSIX `time_t`).
- * - `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 null.
+ * - `options` must be an object or omitted: a non-object value (such as a bare `"seconds"` string)
+ *   returns null.
  * - Returns null for invalid input.
  *
  * @param value UTC Instant string
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options The unit of the returned epoch value
  * @returns epoch number or null on invalid
  *
  * @example convertUtcToUnix("2024-02-29T00:00:00Z") // 1709164800000
@@ -20,5 +19,11 @@ import type { UnixUnit } from "../../unix/validate/isValidUnixUnit.js";
  * @example convertUtcToUnix("invalid") // null
  */
 export declare function convertUtcToUnix(value: string, options?: {
+    /**
+     * The unit the epoch value is returned in: `"seconds"` or `"milliseconds"`, singular or plural.
+     * An explicit `undefined` is the same as omitted; any other value returns `null`.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
 }): number | null;

package/dist/utc/convert/convertUtcToUnix.js

@@ -6,13 +6,12 @@ import { isValidUtc } from "../validate/index.js";
  *
  * - Uses Temporal.Instant.from to parse.
  * - Seconds floor toward −∞, so `"1969-12-31T23:59:59.5Z"` is second `-1` (POSIX `time_t`).
- * - `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 null.
+ * - `options` must be an object or omitted: a non-object value (such as a bare `"seconds"` string)
+ *   returns null.
  * - Returns null for invalid input.
  *
  * @param value UTC Instant string
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options The unit of the returned epoch value
  * @returns epoch number or null on invalid
  *
  * @example convertUtcToUnix("2024-02-29T00:00:00Z") // 1709164800000

package/dist/utc/convert/convertUtcToZoned.d.ts

@@ -6,7 +6,7 @@
  * - Returns "" for invalid input.
  *
  * @param value UTC Instant string
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset
  * @returns zoned ISO 8601 string or "" on invalid
  *
  * @example convertUtcToZoned("2024-02-29T00:00:00Z", "America/New_York") // "2024-02-28T19:00:00-05:00[America/New_York]"

package/dist/utc/convert/convertUtcToZoned.js

@@ -9,7 +9,7 @@ import { isValidUtc } from "../validate/index.js";
  * - Returns "" for invalid input.
  *
  * @param value UTC Instant string
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset
  * @returns zoned ISO 8601 string or "" on invalid
  *
  * @example convertUtcToZoned("2024-02-29T00:00:00Z", "America/New_York") // "2024-02-28T19:00:00-05:00[America/New_York]"

package/dist/utc/format/formatCalendarUtc.d.ts

@@ -1,27 +1,38 @@
 import type { CalendarOptions } from "../../types/index.js";
+/**
+ * Options for `formatCalendarUtc`: the instant the day label is measured from, the time zone the
+ * days and the clock time are read in, and the width of the time-of-day half.
+ */
 export interface FormatCalendarUtcOptions extends CalendarOptions {
     /**
-     * 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 UTC ISO string as a relative day label plus time-of-day, e.g.
  * "Tomorrow at 2:30 PM" — the UTC 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`.
  *
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
  *
  * @param value UTC ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { reference, timeZone (default "UTC"; "local" is the system zone; an unknown zone returns ""), timeStyle }
+ * @param options The reference instant, the time zone and the time style
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendarUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", reference: "2026-03-15T13:00:00Z" }) // "tomorrow at 2:30 PM"

package/dist/utc/format/formatCalendarUtc.js

@@ -3,19 +3,19 @@ import { formatCalendarInstants } from "../../internal/formatCalendarDays.js";
 import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
 import { toInstantFromUtc, toReferenceInstantFromUtc, } from "../../internal/toInstantFromUtc.js";
 import { isValidUtc } from "../validate/index.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Format a UTC ISO string as a relative day label plus time-of-day, e.g.
  * "Tomorrow at 2:30 PM" — the UTC 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`.
  *
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
  *
  * @param value UTC ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { reference, timeZone (default "UTC"; "local" is the system zone; an unknown zone returns ""), timeStyle }
+ * @param options The reference instant, the time zone and the time style
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendarUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", reference: "2026-03-15T13:00:00Z" }) // "tomorrow at 2:30 PM"
@@ -36,16 +36,18 @@ export function formatCalendarUtc(value, locale, options = {}) {
         const timeZone = normalizeTimeZone(options.timeZone);
         if (!timeZone)
             return "";
-        if (options.reference !== undefined && !isValidUtc(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (referenceOption !== undefined && !isValidUtc(referenceOption))
             return "";
         const target = toInstantFromUtc(value);
         if (target === null)
             return "";
-        const reference = toReferenceInstantFromUtc(options.reference);
+        const reference = toReferenceInstantFromUtc(referenceOption);
         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/utc/format/formatHttp.d.ts

@@ -5,7 +5,7 @@
  * - **Fixed grammar, not a display format.** RFC 9110 mandates English
  *   weekday/month abbreviations and a literal `GMT` suffix regardless of
  *   caller locale — there is no locale-appropriate alternative ordering to
- *   lose (see roadmap `issues/J.md` Decision 1 / J13).
+ *   lose.
  * - Always `GMT`; HTTP-date carries no offset variation to preserve.
  * - Fractional seconds in `value` are truncated — IMF-fixdate has no
  *   sub-second field.

package/dist/utc/format/formatHttp.js

@@ -8,7 +8,7 @@ import { isValidUtc } from "../validate/index.js";
  * - **Fixed grammar, not a display format.** RFC 9110 mandates English
  *   weekday/month abbreviations and a literal `GMT` suffix regardless of
  *   caller locale — there is no locale-appropriate alternative ordering to
- *   lose (see roadmap `issues/J.md` Decision 1 / J13).
+ *   lose.
  * - Always `GMT`; HTTP-date carries no offset variation to preserve.
  * - Fractional seconds in `value` are truncated — IMF-fixdate has no
  *   sub-second field.

package/dist/utc/format/formatRelativeUtc.d.ts

@@ -1,28 +1,48 @@
 import type { RelativeTimeFormatOptions, RelativeUnit } from "../../types/index.js";
+/**
+ * Options for `formatRelativeUtc`: the instant the distance is measured from, the unit it is shown
+ * in, how it rounds, and the wording `Intl.RelativeTimeFormat` uses.
+ */
 export interface FormatRelativeUtcOptions extends RelativeTimeFormatOptions {
-    largestUnit?: RelativeUnit;
+    /**
+     * 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 instant the distance is measured from, as a UTC ISO string. Any other value returns `""`.
+     *
+     * @defaultValue The current instant.
+     */
     reference?: string;
+    /**
+     * 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;
 }
 /**
  * Format the relative time between a UTC ISO string and a reference instant.
  *
- * - Auto-picks the display unit based on the distance, unless `largestUnit` forces one: second
- *   under a minute, minute under an hour, hour under a day, then `formatRelativeDate`'s thresholds —
- *   day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads
- *   "3 years ago".
+ * - Picks the display unit from the distance, using `formatRelativeDate`'s day thresholds past a
+ *   day, so a 3-year distance reads "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"`; pass `"local"` for the system time 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 `""`.
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
  *
  * @param value UTC ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference, timeZone }
+ * @param options The reference instant, the display unit, rounding, wording and time zone
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", { reference: "2026-04-15T14:30:45Z" }) // "3 months ago"

package/dist/utc/format/formatRelativeUtc.js

@@ -7,22 +7,18 @@ import { isValidUtc } from "../validate/index.js";
 /**
  * Format the relative time between a UTC ISO string and a reference instant.
  *
- * - Auto-picks the display unit based on the distance, unless `largestUnit` forces one: second
- *   under a minute, minute under an hour, hour under a day, then `formatRelativeDate`'s thresholds —
- *   day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads
- *   "3 years ago".
+ * - Picks the display unit from the distance, using `formatRelativeDate`'s day thresholds past a
+ *   day, so a 3-year distance reads "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"`; pass `"local"` for the system time 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 `""`.
  * - `options` must be an object or omitted: `null` returns `""`, as Temporal's GetOptionsObject
  *   rejects it.
  *
  * @param value UTC ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { style, numeric, largestUnit, roundingMethod, reference, timeZone }
+ * @param options The reference instant, the display unit, rounding, wording and time zone
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", { reference: "2026-04-15T14:30:45Z" }) // "3 months ago"
@@ -43,12 +39,14 @@ export function formatRelativeUtc(value, locale, options = {}) {
         const tz = normalizeTimeZone(options.timeZone);
         if (!tz)
             return "";
-        if (options.reference !== undefined && !isValidUtc(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (referenceOption !== undefined && !isValidUtc(referenceOption))
             return "";
         const target = toInstantFromUtc(value);
         if (target === null)
             return "";
-        const reference = toReferenceInstantFromUtc(options.reference);
+        const reference = toReferenceInstantFromUtc(referenceOption);
         if (reference === null)
             return "";
         try {