@northguild/gmt 1.17.0 → 1.18.0

package/dist/zoned/compare/isInDaylightSaving.js

@@ -1,19 +1,40 @@
 import { isValidZonedDateTime } from "../validate/index.js";
-import { zonedDateTimeFrom } from "../../internal/index.js";
+import { isInDaylightTime, zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Check whether a zoned value's instant falls within daylight saving time.
  *
- * - The third DST-related function in the roadmap, and distinct from the
- *   other two — see docs/dst-disambiguation.md for the full four-way split:
- *   `hasDaylightSaving(timeZone)` asks whether a zone observes DST *at all*
- *   (zone-level, no instant); `listDstTransitions(timeZone, year)` asks
- *   *where* a zone's transitions fall (enumerates instants);
- *   `isInDaylightSaving(value)` asks whether *this particular instant* is
- *   currently in DST. `disambiguation`/`offset` (Group C) are a fourth,
- *   orthogonal concern: what to do when construction lands on an ambiguous
- *   or nonexistent instant.
- * - Returns false for invalid input, and false for a zone that doesn't
- *   observe DST at all.
+ * - The rule is GMT's own definition, not the tz database's daylight flag. No JavaScript API
+ *   exposes that flag, and it cannot be worked out from offsets.
+ * - The rule: daylight time runs from a forward change of the zone's clocks to the backward
+ *   change that undoes it. A backward change undoes the most recent forward change of the same
+ *   size not yet undone, if it comes less than 365 days after it. The instant is in daylight
+ *   time when it is at or after such a forward change and before its backward change.
+ * - Read from the zone's offset changes in the runtime's time zone data
+ *   (`getTimeZoneTransition`); GMT holds no zone data. The answer changes only at a clock
+ *   change, and the answer for a past instant can change when the runtime's data learns that a
+ *   zone stopped changing its clocks.
+ * - A forward change never undone, or undone 365 days or more later, is a change of standard
+ *   time: `Europe/Istanbul` is on standard time from its last advance in March 2016.
+ * - The higher of two alternating offsets is the daylight one, as in the tz database's rearguard
+ *   form. Its main form reverses `Europe/Dublin` (winter is its daylight time, a negative save)
+ *   and `Africa/Casablanca` (the Ramadan weeks are); here Dublin's summer and Casablanca's
+ *   months at `+01:00` are daylight time.
+ * - Read as standard time, because the offsets do not show otherwise:
+ *   - the last summer before a zone kept its daylight offset for good (the tz database dates
+ *     Istanbul's switch 2016-09-07, with no clock change);
+ *   - a daylight period held 365 days or longer (`America/Santiago` 2014 to 2016);
+ *   - a daylight period that began, ended or was interrupted by a move of standard time, so the
+ *     clocks went back by another amount or not at all (`America/Kentucky/Monticello` 2000), or
+ *     the offset changed part-way through and the rest, or all, of the period is not paired
+ *     (`Asia/Tomsk` 2002, `Asia/Jerusalem` 1948);
+ *   - a daylight period whose end is past the last instant Temporal can represent.
+ * - Read as daylight time: a move of standard time reversed by the same amount less than 365
+ *   days later (`America/Metlakatla` 2018 to 2019).
+ * - The other DST functions answer other questions: `hasDaylightSaving(timeZone, { at })` whether
+ *   a zone observes DST at an instant, `getDstTransitions(timeZone, year)` where its offset
+ *   changes fall, and `classifyLocal` whether a wall time is ambiguous. See
+ *   docs/dst-disambiguation.md.
+ * - Returns false for invalid input, and for a zone with a fixed offset.
  *
  * @param value zoned ISO 8601 datetime string
  * @returns true if the instant is in daylight saving time, false otherwise or on invalid input
@@ -22,6 +43,12 @@ import { zonedDateTimeFrom } from "../../internal/index.js";
  * @example isInDaylightSaving("2024-01-15T12:00:00-05:00[America/New_York]") // false
  * @example isInDaylightSaving("2024-01-15T12:00:00+11:00[Australia/Sydney]") // true (southern-hemisphere summer)
  * @example isInDaylightSaving("2024-07-15T12:00:00+09:00[Asia/Tokyo]") // false (Asia/Tokyo has no DST)
+ * @example isInDaylightSaving("2015-07-01T12:00:00+03:00[Europe/Istanbul]") // true (undone 2015-11-08)
+ * @example isInDaylightSaving("2016-07-01T12:00:00+03:00[Europe/Istanbul]") // false (the March 2016 advance was never undone)
+ * @example isInDaylightSaving("2016-12-01T12:00:00+03:00[Europe/Istanbul]") // false (permanent +03:00)
+ * @example isInDaylightSaving("2019-07-15T12:00:00+01:00[Europe/Dublin]") // true
+ * @example isInDaylightSaving("2019-12-01T12:00:00+01:00[Africa/Casablanca]") // true (put back 2020-04-19)
+ * @example isInDaylightSaving("2019-07-15T12:00:00+00:00[UTC]") // false
  * @example isInDaylightSaving("invalid") // false
  */
 export function isInDaylightSaving(value) {
@@ -29,38 +56,7 @@ export function isInDaylightSaving(value) {
         return false;
     }
     try {
-        const zonedDateTime = zonedDateTimeFrom(value);
-        const { timeZoneId: timeZone, year } = zonedDateTime;
-        // Sample the zone's offset 6 months apart, within the same calendar year
-        // as `value` (a zone's DST rules can change between years). DST always
-        // shifts a zone's clocks forward relative to its own standard time, in
-        // every hemisphere, so whichever of these two offsets is smaller is
-        // "standard" — regardless of whether the zone's DST season falls in the
-        // Jan or Jul half of the year. This mirrors `hasDaylightSaving`'s
-        // Jan/Jul sampling, but anchored to `value`'s own year rather than a
-        // fixed reference year, and doesn't attempt to detect a zone whose
-        // standard offset itself changed permanently mid-year (rare, and H3
-        // shares the same limitation).
-        const januaryOffsetNanoseconds = zonedDateTimeFrom({
-            year,
-            month: 1,
-            day: 15,
-            hour: 12,
-            minute: 0,
-            second: 0,
-            timeZone,
-        }).offsetNanoseconds;
-        const julyOffsetNanoseconds = zonedDateTimeFrom({
-            year,
-            month: 7,
-            day: 15,
-            hour: 12,
-            minute: 0,
-            second: 0,
-            timeZone,
-        }).offsetNanoseconds;
-        const standardOffsetNanoseconds = Math.min(januaryOffsetNanoseconds, julyOffsetNanoseconds);
-        return zonedDateTime.offsetNanoseconds > standardOffsetNanoseconds;
+        return isInDaylightTime(zonedDateTimeFrom(value));
     }
     catch {
         return false;

package/dist/zoned/convert/convertPlainDateTimeToZoned.d.ts

@@ -4,17 +4,15 @@ import type { Disambiguation } from "../../types/index.js";
  * Attach the specified `timeZone` to a plain datetime string and return a zoned ISO 8601 datetime string.
  *
  * - Combines plain datetime with timezone to create ZonedDateTime.
- * - `disambiguation` controls DST gap/overlap resolution: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
  * - There is no `offset` option (removed in 1.16.0): Temporal `PlainDateTime#toZonedDateTime` reads
  *   only `disambiguation`, and a plain datetime has no UTC offset for `offset` to act on.
- * - **Output is cut to milliseconds by default.** `smallestUnit` defaults to `"milliseconds"`
- *   (Temporal `toString` rounding mode `"trunc"`), so microseconds and nanoseconds in `value` are
+ * - **Output is cut to milliseconds by default**, so microseconds and nanoseconds in `value` are
  *   dropped. Pass `{ smallestUnit: "nanoseconds" }` to keep every digit.
  * - Returns "" for invalid input.
  *
  * @param value plain datetime string (e.g. "2024-02-29T14:30:45")
- * @param timeZone IANA timeZone identifier
- * @param optionsArg optional: smallestUnit, disambiguation ("compatible" | "earlier" | "later" | "reject")
+ * @param timeZone IANA name or UTC offset
+ * @param optionsArg optional settings for the precision of the output string and for resolving a DST gap or overlap
  * @returns zoned ISO 8601 datetime string or "" when invalid
  *
  * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45", "America/New_York") // "2024-02-29T14:30:45.000-05:00[America/New_York]"
@@ -26,6 +24,21 @@ import type { Disambiguation } from "../../types/index.js";
  * @example convertPlainDateTimeToZoned("2024-03-10T02:30:00", "America/New_York", { disambiguation: "reject" }) // ""
  */
 export declare function convertPlainDateTimeToZoned(value: string, timeZone: string, optionsArg?: {
+    /**
+     * The smallest unit written in the output string, from `"minute"` to `"nanosecond"`, singular
+     * or plural. Anything smaller is truncated, as Temporal's `toString` does with its `"trunc"`
+     * rounding mode.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     smallestUnit?: Temporal.ZonedDateTimeToStringOptions["smallestUnit"];
+    /**
+     * How `value` resolves when its wall-clock time falls in a DST gap or overlap in `timeZone`. In
+     * a fall-back overlap `"compatible"` and `"earlier"` take the earlier instant and `"later"` the
+     * later one; in a spring-forward gap `"compatible"` and `"later"` move the wall clock forward
+     * by the gap length and `"earlier"` back by it. `"reject"` returns `""` for both.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
     disambiguation?: Disambiguation;
 }): string;

package/dist/zoned/convert/convertPlainDateTimeToZoned.js

@@ -3,21 +3,20 @@ import { isValidDateTime } from "../../plain/validate/index.js";
 import { isValidTimeZone } from "../validate/index.js";
 import { isoStringBody, zonedDateTimeFrom } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Attach the specified `timeZone` to a plain datetime string and return a zoned ISO 8601 datetime string.
  *
  * - Combines plain datetime with timezone to create ZonedDateTime.
- * - `disambiguation` controls DST gap/overlap resolution: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
  * - There is no `offset` option (removed in 1.16.0): Temporal `PlainDateTime#toZonedDateTime` reads
  *   only `disambiguation`, and a plain datetime has no UTC offset for `offset` to act on.
- * - **Output is cut to milliseconds by default.** `smallestUnit` defaults to `"milliseconds"`
- *   (Temporal `toString` rounding mode `"trunc"`), so microseconds and nanoseconds in `value` are
+ * - **Output is cut to milliseconds by default**, so microseconds and nanoseconds in `value` are
  *   dropped. Pass `{ smallestUnit: "nanoseconds" }` to keep every digit.
  * - Returns "" for invalid input.
  *
  * @param value plain datetime string (e.g. "2024-02-29T14:30:45")
- * @param timeZone IANA timeZone identifier
- * @param optionsArg optional: smallestUnit, disambiguation ("compatible" | "earlier" | "later" | "reject")
+ * @param timeZone IANA name or UTC offset
+ * @param optionsArg optional settings for the precision of the output string and for resolving a DST gap or overlap
  * @returns zoned ISO 8601 datetime string or "" when invalid
  *
  * @example convertPlainDateTimeToZoned("2024-02-29T14:30:45", "America/New_York") // "2024-02-29T14:30:45.000-05:00[America/New_York]"
@@ -36,13 +35,9 @@ export function convertPlainDateTimeToZoned(value, timeZone, optionsArg) {
         if (!isValidDateTime(value) || !isValidTimeZone(timeZone)) {
             return "";
         }
-        const disambiguation = optionsArg?.disambiguation === undefined
-            ? "compatible"
-            : optionsArg.disambiguation;
+        const disambiguation = optionOrDefault(optionsArg?.disambiguation, "compatible");
         const options = {
-            smallestUnit: optionsArg?.smallestUnit === undefined
-                ? "milliseconds"
-                : optionsArg.smallestUnit,
+            smallestUnit: optionOrDefault(optionsArg?.smallestUnit, "milliseconds"),
         };
         try {
             const zonedDateTime = zonedDateTimeFrom(`${isoStringBody(value)}[${timeZone}]`, { disambiguation });

package/dist/zoned/convert/convertZonedToUnix.d.ts

@@ -4,13 +4,11 @@ import type { UnixUnit } from "../../unix/validate/isValidUnixUnit.js";
  *
  * - Uses Temporal.ZonedDateTime.toInstant to convert.
  * - Seconds floor toward −∞, as POSIX `time_t` counts whole elapsed seconds.
- * - `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.
+ * - A non-object `options` (such as a bare `"seconds"` string) returns null.
  * - Returns null for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional setting for the unit of the returned epoch value
  * @returns epoch number or null on invalid
  *
  * @example convertZonedToUnix("2024-02-29T12:34:56.789+00:00[UTC]") // 1709210096789
@@ -19,5 +17,12 @@ import type { UnixUnit } from "../../unix/validate/isValidUnixUnit.js";
  * @example convertZonedToUnix("invalid") // null
  */
 export declare function convertZonedToUnix(value: string, options?: {
+    /**
+     * The unit the epoch value is returned in: `"milliseconds"` or `"seconds"`, each also accepted
+     * in its singular form. An explicit `undefined` is the same as omitted; any other value returns
+     * null.
+     *
+     * @defaultValue `"milliseconds"`
+     */
     epochUnit?: UnixUnit;
 }): number | null;

package/dist/zoned/convert/convertZonedToUnix.js

@@ -6,13 +6,11 @@ import { zonedDateTimeFrom } from "../../internal/index.js";
  *
  * - Uses Temporal.ZonedDateTime.toInstant to convert.
  * - Seconds floor toward −∞, as POSIX `time_t` counts whole elapsed seconds.
- * - `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.
+ * - A non-object `options` (such as a bare `"seconds"` string) returns null.
  * - Returns null for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
- * @param options optional: epochUnit ("seconds" | "milliseconds", singular accepted; default "milliseconds")
+ * @param options optional setting for the unit of the returned epoch value
  * @returns epoch number or null on invalid
  *
  * @example convertZonedToUnix("2024-02-29T12:34:56.789+00:00[UTC]") // 1709210096789

package/dist/zoned/convert/convertZonedToZoned.d.ts

@@ -5,7 +5,7 @@
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
- * @param timeZone target IANA timeZone identifier
+ * @param timeZone target IANA name or UTC offset
  * @returns zoned ISO 8601 string in target timeZone or "" when invalid
  *
  * @example convertZonedToZoned("2024-02-29T12:34:56.789+00:00[UTC]", "America/New_York") // "2024-02-29T07:34:56.789-05:00[America/New_York]"

package/dist/zoned/convert/convertZonedToZoned.js

@@ -7,7 +7,7 @@ import { zonedDateTimeFrom } from "../../internal/index.js";
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
- * @param timeZone target IANA timeZone identifier
+ * @param timeZone target IANA name or UTC offset
  * @returns zoned ISO 8601 string in target timeZone or "" when invalid
  *
  * @example convertZonedToZoned("2024-02-29T12:34:56.789+00:00[UTC]", "America/New_York") // "2024-02-29T07:34:56.789-05:00[America/New_York]"

package/dist/zoned/format/formatCalendarZoned.d.ts

@@ -1,19 +1,25 @@
+/**
+ * Options for `formatCalendarZoned`: the moment the day label is measured from and the length of
+ * the time-of-day half.
+ */
 export interface FormatCalendarZonedOptions {
     /**
-     * Anchor point for the relative diff.
+     * The instant the day label is measured from, as a zoned ISO string, a UTC ISO string or a
+     * numeric epoch in milliseconds. Whatever its form, it is converted into `value`'s own time zone
+     * before calendar days are compared, because a day label needs one zone's wall clock and
+     * `value`'s zone is whose "today" is being described. Any other value returns `""`.
      *
-     * - ZonedDateTime ISO string: converted into `value`'s own zone before
-     *   comparing calendar days. Unlike `formatRelativeZoned`'s `reference`
-     *   (which keeps a ZonedDateTime reference in its own zone for
-     *   elapsed-time diffing), a calendar *label* is meaningless without
-     *   picking one zone's wall clock — `value`'s zone is the natural choice,
-     *   since that is whose "today" is being described.
-     * - UTC ISO string or numeric epoch (ms): placed into `value`'s timezone.
-     * - Omitted: "now" in `value`'s own timezone.
+     * @defaultValue The current instant, read in `value`'s time zone.
      */
     reference?: string | number;
-    /** `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 zoned date-time as a relative day label plus time-of-day, e.g.
@@ -26,7 +32,7 @@ export interface FormatCalendarZonedOptions {
  *
  * @param value ZonedDateTime ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { reference, timeStyle }
+ * @param options optional settings for the reference moment and the time style
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendarZoned("2026-03-16T14:30:00-04:00[America/New_York]", "en-US", { reference: "2026-03-15T09:00:00-04:00[America/New_York]" }) // "tomorrow at 2:30 PM"

package/dist/zoned/format/formatCalendarZoned.js

@@ -4,6 +4,7 @@ import { formatCalendarDays } from "../../internal/formatCalendarDays.js";
 import { isValidUtc } from "../../utc/validate/index.js";
 import { isValidZonedFormatReference } from "../../internal/zonedFormatReference.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Format a zoned date-time as a relative day label plus time-of-day, e.g.
  * "Tomorrow at 2:30 PM" — the zoned counterpart of `formatCalendar`. See
@@ -15,7 +16,7 @@ import { isValidZonedDateTime } from "../validate/index.js";
  *
  * @param value ZonedDateTime ISO string to format
  * @param locale optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)
- * @param options optional: { reference, timeStyle }
+ * @param options optional settings for the reference moment and the time style
  * @returns the formatted calendar string, or "" on invalid input
  *
  * @example formatCalendarZoned("2026-03-16T14:30:00-04:00[America/New_York]", "en-US", { reference: "2026-03-15T09:00:00-04:00[America/New_York]" }) // "tomorrow at 2:30 PM"
@@ -32,24 +33,27 @@ export function formatCalendarZoned(value, locale, options = {}) {
             return "";
         if (!isValidZonedDateTime(value))
             return "";
-        if (!isValidZonedFormatReference(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (!isValidZonedFormatReference(referenceOption))
             return "";
         try {
             const target = zonedDateTimeFrom(value);
             const timeZone = target.timeZoneId;
             let reference;
-            if (options.reference === undefined) {
+            if (referenceOption === undefined) {
                 reference = Temporal.Now.zonedDateTimeISO(timeZone);
             }
-            else if (typeof options.reference === "string") {
-                reference = isValidUtc(options.reference)
-                    ? Temporal.Instant.from(options.reference).toZonedDateTimeISO(timeZone)
-                    : zonedDateTimeFrom(options.reference).withTimeZone(timeZone);
+            else if (typeof referenceOption === "string") {
+                reference = isValidUtc(referenceOption)
+                    ? Temporal.Instant.from(referenceOption).toZonedDateTimeISO(timeZone)
+                    : zonedDateTimeFrom(referenceOption).withTimeZone(timeZone);
             }
             else {
-                reference = Temporal.Instant.fromEpochMilliseconds(options.reference).toZonedDateTimeISO(timeZone);
+                reference =
+                    Temporal.Instant.fromEpochMilliseconds(referenceOption).toZonedDateTimeISO(timeZone);
             }
-            return formatCalendarDays(target.toPlainDate().since(reference.toPlainDate()).days, target.epochMilliseconds, timeZone, locale, options.timeStyle === undefined ? "short" : options.timeStyle);
+            return formatCalendarDays(target.toPlainDate().since(reference.toPlainDate()).days, target.epochMilliseconds, timeZone, locale, optionOrDefault(options.timeStyle, "short"));
         }
         catch {
             return "";

package/dist/zoned/format/formatRelativeZoned.d.ts

@@ -1,20 +1,48 @@
 import type { RelativeRoundingMethod, RelativeUnit } from "../../types/index.js";
+/**
+ * Options for `formatRelativeZoned`: how the phrase is worded, the unit it counts in, how the
+ * count rounds and the moment the distance is measured from.
+ */
 export interface FormatRelativeZonedOptions {
+    /**
+     * 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";
-    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 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;
     /**
-     * Anchor point for the relative diff.
+     * The instant the distance is measured from, as a zoned ISO string, a UTC ISO string or a numeric
+     * epoch in milliseconds. The distance is the exact time between the two instants; the reference's
+     * time zone only anchors how months and years are counted, which is its own zone for a zoned
+     * string and `value`'s zone for a UTC string or an epoch. Any other value returns `""`.
      *
-     * - ZonedDateTime ISO string: kept in its own zone; Temporal handles
-     *   cross-zone diffs correctly. The label is therefore zone-aware — a value
-     *   and reference in different zones can produce a non-zero diff even when
-     *   they describe the same absolute instant.
-     * - UTC ISO string: placed into `value`'s timezone before diffing so the
-     *   calendar anchor matches the value's wall clock.
-     * - Numeric epoch (ms): same — placed into `value`'s timezone.
-     * - Omitted: "now" in `value`'s own timezone.
+     * @defaultValue The current instant, read in `value`'s time zone.
      */
     reference?: string | number;
 }
@@ -27,13 +55,14 @@ export interface FormatRelativeZonedOptions {
  *   "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.
+ * - `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` or any other primitive returns `""`, as
  *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ZonedDateTime 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 }
+ * @param options optional settings for the wording, the display unit, rounding and the reference moment
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeZoned("2023-12-29T00:00:00+00:00[UTC]", "en-US", { reference: "2024-02-29T00:00:00+00:00[UTC]" }) // "2 months ago"

package/dist/zoned/format/formatRelativeZoned.js

@@ -13,13 +13,14 @@ import { isValidZonedDateTime } from "../validate/index.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.
+ * - `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` or any other primitive returns `""`, as
  *   Temporal's GetOptionsObject rejects it.
  *
  * @param value ZonedDateTime 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 }
+ * @param options optional settings for the wording, the display unit, rounding and the reference moment
  * @returns the formatted relative-time string, or "" on invalid input
  *
  * @example formatRelativeZoned("2023-12-29T00:00:00+00:00[UTC]", "en-US", { reference: "2024-02-29T00:00:00+00:00[UTC]" }) // "2 months ago"
@@ -37,12 +38,14 @@ export function formatRelativeZoned(value, locale, options = {}) {
             return "";
         if (!isValidZonedDateTime(value))
             return "";
-        if (!isValidZonedFormatReference(options.reference))
+        // Each option is read once (GetOption).
+        const referenceOption = options.reference;
+        if (!isValidZonedFormatReference(referenceOption))
             return "";
         try {
             const valueZDT = zonedDateTimeFrom(value);
             const valueInstant = valueZDT.toInstant();
-            const refZDT = resolveZonedReference(options.reference, valueZDT.timeZoneId);
+            const refZDT = resolveZonedReference(referenceOption, valueZDT.timeZoneId);
             const diff = valueInstant.since(refZDT.toInstant());
             // month/year are calendrical and need a relativeTo anchor
             return formatRelativeDuration(diff, locale, options, (unit) => durationTotal(diff, unit, refZDT));

package/dist/zoned/format/formatRfc2822.d.ts

@@ -5,8 +5,8 @@
  * - **Fixed grammar, not a display format.** RFC 5322 mandates English
  *   weekday/month abbreviations and a numeric `+HHMM`/`-HHMM` offset
  *   regardless of caller locale — there is no locale-appropriate alternative
- *   ordering to lose, so this does not conflict with Decision 1's exclusion
- *   of a general token formatter (see roadmap `issues/J.md`, J13).
+ *   ordering to lose, so this does not conflict with GMT's exclusion of a
+ *   general token formatter.
  * - Uses the input's own UTC offset at that instant (DST-aware); never emits
  *   an obsolete named zone like "GMT" or "EST" on output, only numeric.
  * - Day, hour, minute, and second are always zero-padded to 2 digits; year

package/dist/zoned/format/formatRfc2822.js

@@ -9,8 +9,8 @@ const NANOSECONDS_PER_MINUTE = 60_000_000_000;
  * - **Fixed grammar, not a display format.** RFC 5322 mandates English
  *   weekday/month abbreviations and a numeric `+HHMM`/`-HHMM` offset
  *   regardless of caller locale — there is no locale-appropriate alternative
- *   ordering to lose, so this does not conflict with Decision 1's exclusion
- *   of a general token formatter (see roadmap `issues/J.md`, J13).
+ *   ordering to lose, so this does not conflict with GMT's exclusion of a
+ *   general token formatter.
  * - Uses the input's own UTC offset at that instant (DST-aware); never emits
  *   an obsolete named zone like "GMT" or "EST" on output, only numeric.
  * - Day, hour, minute, and second are always zero-padded to 2 digits; year

package/dist/zoned/format/formatRfc3339.d.ts

@@ -8,9 +8,8 @@
  *   `Temporal.ZonedDateTime.prototype.toString()` reproduces by default —
  *   that annotation is *not* valid RFC 3339. This function's only job is to
  *   strip it (`{ timeZoneName: "never" }`), which is exactly the detail a
- *   caller reaching for "give me RFC 3339" would otherwise miss. (Go/no-go
- *   recorded in roadmap `issues/J.md` J13: this narrow gap is real; a
- *   parallel `utc`/`unix` wrapper was *not* added, because
+ *   caller reaching for "give me RFC 3339" would otherwise miss. (This
+ *   narrow gap is real; a parallel `utc`/`unix` wrapper was *not* added, because
  *   `Temporal.Instant.prototype.toString()` is already fully RFC 3339
  *   compliant with no bracket to strip — that would be a pure passthrough.)
  * - **Sub-minute offsets are written in UTC.** `time-numoffset` holds whole minutes, and RFC 3339

package/dist/zoned/format/formatRfc3339.js

@@ -11,9 +11,8 @@ const NANOSECONDS_PER_MINUTE = 60_000_000_000;
  *   `Temporal.ZonedDateTime.prototype.toString()` reproduces by default —
  *   that annotation is *not* valid RFC 3339. This function's only job is to
  *   strip it (`{ timeZoneName: "never" }`), which is exactly the detail a
- *   caller reaching for "give me RFC 3339" would otherwise miss. (Go/no-go
- *   recorded in roadmap `issues/J.md` J13: this narrow gap is real; a
- *   parallel `utc`/`unix` wrapper was *not* added, because
+ *   caller reaching for "give me RFC 3339" would otherwise miss. (This
+ *   narrow gap is real; a parallel `utc`/`unix` wrapper was *not* added, because
  *   `Temporal.Instant.prototype.toString()` is already fully RFC 3339
  *   compliant with no bracket to strip — that would be a pure passthrough.)
  * - **Sub-minute offsets are written in UTC.** `time-numoffset` holds whole minutes, and RFC 3339

package/dist/zoned/format/formatTimeZoneName.d.ts

@@ -18,7 +18,16 @@
  * const s: TimeZoneNameStyle = "shortGeneric";
  */
 export type TimeZoneNameStyle = "short" | "long" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric";
+/** Options for `formatTimeZoneName`: the form the zone name is written in. */
 export interface FormatTimeZoneNameOptions {
+    /**
+     * The form of the name, one of `Intl.DateTimeFormat`'s `timeZoneName` values. `"short"` and
+     * `"long"` give the abbreviated or full name and `"shortOffset"` and `"longOffset"` the UTC
+     * offset, all four for the offset in effect now. `"shortGeneric"` and `"longGeneric"` give a name
+     * that does not change with daylight saving.
+     *
+     * @defaultValue `"long"`
+     */
     style?: TimeZoneNameStyle;
 }
 /**
@@ -27,7 +36,7 @@ export interface FormatTimeZoneNameOptions {
  * - `options.style` covers every `Intl.DateTimeFormatOptions` `timeZoneName`
  *   value: "short" (EST), "long" (Eastern Standard Time), "shortOffset"
  *   (GMT-5), "longOffset" (GMT-05:00), "shortGeneric" (ET), "longGeneric"
- *   (Eastern Time). Default "long".
+ *   (Eastern Time).
  * - "short"/"long"/"shortOffset"/"longOffset" name the zone's *current*
  *   offset — for a DST-observing zone the label flips between standard and
  *   daylight names depending on when this is called, since there's no
@@ -39,9 +48,9 @@ export interface FormatTimeZoneNameOptions {
  * - Output depends on runtime ICU data.
  * - Returns "" for an invalid timeZone or locale.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset
  * @param locale BCP 47 locale tag (e.g. "en-US"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
- * @param options optional: { style } name style, default "long"
+ * @param options optional setting for the form of the name
  * @returns localized zone name, or "" on invalid input
  *
  * @example formatTimeZoneName("America/New_York", "en-US", { style: "shortGeneric" }) // "ET"

package/dist/zoned/format/formatTimeZoneName.js

@@ -2,13 +2,14 @@ import { Temporal } from "@js-temporal/polyfill";
 import { resolveRequiredLocale } from "../../internal/resolveLocale.js";
 import { isValidTimeZone } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Return the localized display name for an IANA timeZone.
  *
  * - `options.style` covers every `Intl.DateTimeFormatOptions` `timeZoneName`
  *   value: "short" (EST), "long" (Eastern Standard Time), "shortOffset"
  *   (GMT-5), "longOffset" (GMT-05:00), "shortGeneric" (ET), "longGeneric"
- *   (Eastern Time). Default "long".
+ *   (Eastern Time).
  * - "short"/"long"/"shortOffset"/"longOffset" name the zone's *current*
  *   offset — for a DST-observing zone the label flips between standard and
  *   daylight names depending on when this is called, since there's no
@@ -20,9 +21,9 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Output depends on runtime ICU data.
  * - Returns "" for an invalid timeZone or locale.
  *
- * @param timeZone IANA timeZone identifier
+ * @param timeZone IANA name or UTC offset
  * @param locale BCP 47 locale tag (e.g. "en-US"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""
- * @param options optional: { style } name style, default "long"
+ * @param options optional setting for the form of the name
  * @returns localized zone name, or "" on invalid input
  *
  * @example formatTimeZoneName("America/New_York", "en-US", { style: "shortGeneric" }) // "ET"
@@ -45,7 +46,7 @@ export function formatTimeZoneName(timeZone, locale, options) {
         if (resolvedLocale === null)
             return "";
         try {
-            const style = options?.style === undefined ? "long" : options.style;
+            const style = optionOrDefault(options?.style, "long");
             const formatter = new Intl.DateTimeFormat(resolvedLocale, {
                 timeZone,
                 timeZoneName: style,

package/dist/zoned/format/formatZonedDateTime.js

@@ -1,6 +1,7 @@
 import { normalizeDateTime, zonedDateTimeFrom } from "../../internal/index.js";
 import { instantFormatOptions } from "../../internal/instantFormatOptions.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { readDateTimeFormatOptions } from "../../internal/readDateTimeFormatOptions.js";
 /**
  * Format a zoned ISO 8601 datetime string using the Intl.DateTimeFormat implementation.
  *
@@ -51,7 +52,7 @@ export function formatZonedDateTime(value, locale, options) {
         // (GetDateTimeFormat ~any~, ~zoned-date-time~, ~all~), so the requested
         // fields and widths are kept.
         const zonedDateTime = zonedDateTimeFrom(value);
-        const resolved = instantFormatOptions(options ?? {}, zonedDateTime.timeZoneId, "zoned-date-time");
+        const resolved = instantFormatOptions(readDateTimeFormatOptions(options), zonedDateTime.timeZoneId, "zoned-date-time");
         if (resolved === null) {
             return "";
         }