@northguild/gmt 1.17.0 → 1.19.0

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,18 +1,29 @@
 /**
  * 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.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it, so the result is always a string `isValidDate` accepts.
  * - 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"
  * @example convertUtcToPlainDate("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "2024-02-28"
  * @example convertUtcToPlainDate("invalid") // ""
+ * @example convertUtcToPlainDate("+010000-01-01T00:00:00Z") // "+010000-01-01" (a year past 9999 has a sign and six digits)
+ * @example convertUtcToPlainDate("1970-01-01T00:30:00Z", { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export declare function convertUtcToPlainDate(value: string, options?: {
+    /**
+     * 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/utc/convert/convertUtcToPlainDate.js

@@ -1,39 +1,41 @@
 // 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 { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.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.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it, so the result is always a string `isValidDate` accepts.
  * - 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"
  * @example convertUtcToPlainDate("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "2024-02-28"
  * @example convertUtcToPlainDate("invalid") // ""
+ * @example convertUtcToPlainDate("+010000-01-01T00:00:00Z") // "+010000-01-01" (a year past 9999 has a sign and six digits)
+ * @example convertUtcToPlainDate("1970-01-01T00:30:00Z", { timeZone: "-00:44:30" }) // "1969-12-31" (a stored offset with seconds)
  */
 export function convertUtcToPlainDate(value, options) {
     try {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const { timeZone = "UTC" } = options ?? {};
-        if (!isValidTimeZone(timeZone))
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null)
             return "";
         if (!isValidUtc(value))
             return "";
         try {
             const instant = Temporal.Instant.from(value);
-            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-            return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
-                .toString()
-                .padStart(2, "0")}-${zonedDateTime.day.toString().padStart(2, "0")}`;
+            const wallClock = frameWallClock(instant, frame);
+            // Temporal writes the date, so a year outside 0000 to 9999 gets its sign and six digits.
+            return wallClock.toPlainDate().toString();
         }
         catch {
             return "";

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

@@ -1,18 +1,30 @@
 /**
  * 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.
+ * - The time is cut to the second: a fraction of a second in `value` is dropped.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it, so the result is always a string `isValidDateTime` accepts.
  * - 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"
  * @example convertUtcToPlainDateTime("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "2024-02-28T19:00:00"
  * @example convertUtcToPlainDateTime("invalid") // ""
+ * @example convertUtcToPlainDateTime("+010000-01-01T00:00:00Z") // "+010000-01-01T00:00:00" (a year past 9999 has a sign and six digits)
+ * @example convertUtcToPlainDateTime("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" }) // "1970-01-01T12:00:00" (a stored offset with seconds)
  */
 export declare function convertUtcToPlainDateTime(value: string, options?: {
+    /**
+     * 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/utc/convert/convertUtcToPlainDateTime.js

@@ -1,45 +1,43 @@
 // 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 { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.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.
+ * - The time is cut to the second: a fraction of a second in `value` is dropped.
+ * - A year outside 0000–9999 is written with a sign and six digits (`+010000`, `-000005`), as
+ *   Temporal writes it, so the result is always a string `isValidDateTime` accepts.
  * - 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"
  * @example convertUtcToPlainDateTime("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "2024-02-28T19:00:00"
  * @example convertUtcToPlainDateTime("invalid") // ""
+ * @example convertUtcToPlainDateTime("+010000-01-01T00:00:00Z") // "+010000-01-01T00:00:00" (a year past 9999 has a sign and six digits)
+ * @example convertUtcToPlainDateTime("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" }) // "1970-01-01T12:00:00" (a stored offset with seconds)
  */
 export function convertUtcToPlainDateTime(value, options) {
     try {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const { timeZone = "UTC" } = options ?? {};
-        if (!isValidTimeZone(timeZone))
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null)
             return "";
         if (!isValidUtc(value))
             return "";
         try {
             const instant = Temporal.Instant.from(value);
-            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-            return `${zonedDateTime.year.toString().padStart(4, "0")}-${zonedDateTime.month
-                .toString()
-                .padStart(2, "0")}-${zonedDateTime.day
-                .toString()
-                .padStart(2, "0")}T${zonedDateTime.hour
-                .toString()
-                .padStart(2, "0")}:${zonedDateTime.minute
-                .toString()
-                .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+            const wallClock = frameWallClock(instant, frame);
+            // Temporal writes the date-time, so a year outside 0000 to 9999 gets its sign and six
+            // digits. `smallestUnit: "second"` always prints the seconds and cuts off any fraction.
+            return wallClock.toString({ smallestUnit: "second" });
         }
         catch {
             return "";

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

@@ -1,18 +1,26 @@
 /**
  * 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"
  * @example convertUtcToPlainTime("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "19:00:00"
  * @example convertUtcToPlainTime("invalid") // ""
+ * @example convertUtcToPlainTime("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export declare function convertUtcToPlainTime(value: string, options?: {
+    /**
+     * 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/utc/convert/convertUtcToPlainTime.js

@@ -1,39 +1,39 @@
 // 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 { frameWallClock, normalizeZoneFrame } from "../../internal/zoneFrame.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"
  * @example convertUtcToPlainTime("2024-02-29T00:00:00Z", { timeZone: "America/New_York" }) // "19:00:00"
  * @example convertUtcToPlainTime("invalid") // ""
+ * @example convertUtcToPlainTime("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" }) // "12:00:00" (a stored offset with seconds)
  */
 export function convertUtcToPlainTime(value, options) {
     try {
         if (!isOptionsArgument(options)) {
             return "";
         }
-        const { timeZone = "UTC" } = options ?? {};
-        if (!isValidTimeZone(timeZone))
+        const frame = normalizeZoneFrame(options?.timeZone);
+        if (frame === null)
             return "";
         if (!isValidUtc(value))
             return "";
         try {
             const instant = Temporal.Instant.from(value);
-            const zonedDateTime = instant.toZonedDateTimeISO(timeZone);
-            return `${zonedDateTime.hour.toString().padStart(2, "0")}:${zonedDateTime.minute
+            const wallClock = frameWallClock(instant, frame);
+            return `${wallClock.hour.toString().padStart(2, "0")}:${wallClock.minute
                 .toString()
-                .padStart(2, "0")}:${zonedDateTime.second.toString().padStart(2, "0")}`;
+                .padStart(2, "0")}:${wallClock.second.toString().padStart(2, "0")}`;
         }
         catch {
             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

@@ -4,9 +4,13 @@
  * - Uses Temporal.Instant.from to parse, converts to specified timezone.
  * - Validates both UTC input and timezone.
  * - Returns "" for invalid input.
+ * - 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 UTC Instant string
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @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

@@ -7,9 +7,13 @@ import { isValidUtc } from "../validate/index.js";
  * - Uses Temporal.Instant.from to parse, converts to specified timezone.
  * - Validates both UTC input and timezone.
  * - Returns "" for invalid input.
+ * - 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 UTC Instant string
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts)
  * @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,42 @@
 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 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 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.
+ * - 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 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,24 @@ 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";
+import { isObject } from "../../internal/isObject.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.
+ * - 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 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"
@@ -28,7 +33,7 @@ export function formatCalendarUtc(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 "";
         if (!isValidUtc(value))
             return "";
@@ -36,16 +41,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 → formatHttpDate.d.ts}

@@ -1,11 +1,11 @@
 /**
- * Format a UTC ISO 8601 datetime string as an RFC 9110 IMF-fixdate — the
- * fixed grammar HTTP headers like `Last-Modified`/`Date`/`Expires` require.
+ * Format a UTC ISO 8601 datetime string as an HTTP header date — the RFC 9110
+ * IMF-fixdate that headers like `Last-Modified`/`Date`/`Expires` require.
  *
  * - **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.
@@ -19,10 +19,10 @@
  * @param value UTC ISO 8601 datetime string (e.g. "2024-03-15T14:30:00Z")
  * @returns RFC 9110 IMF-fixdate string, or "" on invalid input or a year outside 0000–9999
  *
- * @example formatHttp("2024-03-15T14:30:00Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
- * @example formatHttp("2024-03-15T14:30:00.500Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
- * @example formatHttp("-000001-06-15T12:00:00Z") // ""
+ * @example formatHttpDate("2024-03-15T14:30:00Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
+ * @example formatHttpDate("2024-03-15T14:30:00.500Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
+ * @example formatHttpDate("-000001-06-15T12:00:00Z") // ""
  * @example Temporal.Instant.from("-000001-06-15T12:00:00Z").toString() // "-000001-06-15T12:00:00Z"
- * @example formatHttp("invalid") // ""
+ * @example formatHttpDate("invalid") // ""
  */
-export declare function formatHttp(value: string): string;
+export declare function formatHttpDate(value: string): string;

package/dist/utc/format/{formatHttp.js → formatHttpDate.js}

@@ -2,13 +2,13 @@ import { Temporal } from "@js-temporal/polyfill";
 import { englishDateTimeStem } from "../../internal/englishCalendarNames.js";
 import { isValidUtc } from "../validate/index.js";
 /**
- * Format a UTC ISO 8601 datetime string as an RFC 9110 IMF-fixdate — the
- * fixed grammar HTTP headers like `Last-Modified`/`Date`/`Expires` require.
+ * Format a UTC ISO 8601 datetime string as an HTTP header date — the RFC 9110
+ * IMF-fixdate that headers like `Last-Modified`/`Date`/`Expires` require.
  *
  * - **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.
@@ -22,13 +22,13 @@ import { isValidUtc } from "../validate/index.js";
  * @param value UTC ISO 8601 datetime string (e.g. "2024-03-15T14:30:00Z")
  * @returns RFC 9110 IMF-fixdate string, or "" on invalid input or a year outside 0000–9999
  *
- * @example formatHttp("2024-03-15T14:30:00Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
- * @example formatHttp("2024-03-15T14:30:00.500Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
- * @example formatHttp("-000001-06-15T12:00:00Z") // ""
+ * @example formatHttpDate("2024-03-15T14:30:00Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
+ * @example formatHttpDate("2024-03-15T14:30:00.500Z") // "Fri, 15 Mar 2024 14:30:00 GMT"
+ * @example formatHttpDate("-000001-06-15T12:00:00Z") // ""
  * @example Temporal.Instant.from("-000001-06-15T12:00:00Z").toString() // "-000001-06-15T12:00:00Z"
- * @example formatHttp("invalid") // ""
+ * @example formatHttpDate("invalid") // ""
  */
-export function formatHttp(value) {
+export function formatHttpDate(value) {
     if (!isValidUtc(value))
         return "";
     try {

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

@@ -1,28 +1,55 @@
 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 (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;
 }
 /**
  * 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.
+ * - **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 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"
@@ -31,5 +58,6 @@ export interface FormatRelativeUtcOptions extends RelativeTimeFormatOptions {
  * @example formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", null as never) // ""
  * @example formatRelativeUtc("not-a-date") // ""
  * @example formatRelativeUtc("2024-03-15T11:30:00Z", ["fr-FR", "en-US"], { reference: "2024-03-15T12:00:00Z" }) // "il y a 30 minutes"
+ * @example formatRelativeUtc("1970-01-03T12:00:00Z", "en-US", { reference: "1970-01-01T12:00:00Z", timeZone: "-00:44:30" }) // "in 2 days" (a stored offset with seconds)
  */
 export declare function formatRelativeUtc(value: string, locale?: string | string[], options?: FormatRelativeUtcOptions): string;