@northguild/gmt 1.17.0 → 1.18.0

package/dist/internal/durationUntilString.js

@@ -2,16 +2,17 @@ import { Temporal } from "@js-temporal/polyfill";
 import { plainDateUntil } from "./plainDateUntil.js";
 import { zonedUntil } from "./zonedWallClockDifference.js";
 export function durationUntilString(start, end, largestUnit, options) {
-    const untilOptions = {
-        largestUnit,
+    // Each option is read once (GetOption); the difference below works on these values.
+    const roundingOptions = {
         smallestUnit: options?.smallestUnit,
         roundingIncrement: options?.roundingIncrement,
         roundingMode: options?.roundingMode,
     };
+    const untilOptions = { largestUnit, ...roundingOptions };
     const duration = start instanceof Temporal.ZonedDateTime
         ? zonedUntil(start, end, untilOptions)
         : start instanceof Temporal.PlainDate
-            ? plainDateUntil(start, end, largestUnit, options)
+            ? plainDateUntil(start, end, largestUnit, roundingOptions)
             : start.until(end, untilOptions);
     return duration.toString({
         smallestUnit: options?.toStringSmallestUnit,

package/dist/internal/englishCalendarNames.js

@@ -2,8 +2,7 @@
 // RFC 7231) mandate English weekday/month
 // abbreviations regardless of the caller's locale — these are fixed,
 // non-locale-adaptive grammars, not a display format, so hardcoding the
-// English names here is not the i18n bug it would be in a formatter (see
-// roadmap Decision 1 / J13's "Why this survives Decision 1").
+// English names here is not the i18n bug it would be in a formatter.
 // Index 0 = Monday, aligned with Temporal's 1-7 `dayOfWeek` via `[dayOfWeek - 1]`.
 export const ENGLISH_WEEKDAY_NAMES = [
     "Mon",

package/dist/internal/epochNanoseconds.d.ts

@@ -8,6 +8,8 @@ export declare const MIN_EPOCH_NANOSECONDS = -8640000000000000000000n;
  * +10^8 days from the Unix epoch, i.e. `+275760-09-13T00:00:00Z`.
  */
 export declare const MAX_EPOCH_NANOSECONDS = 8640000000000000000000n;
+/** TC39 `CheckISODaysRange`: a date may sit at most 10^8 days from the Unix epoch. */
+export declare const MAX_ISO_EPOCH_DAYS = 100000000;
 /**
  * Digits in `MAX_EPOCH_NANOSECONDS` (22) — the longest a decimal form of an in-range
  * epoch-nanosecond value can be, sign excluded.

package/dist/internal/epochNanoseconds.js

@@ -8,6 +8,8 @@ export const MIN_EPOCH_NANOSECONDS = -8640000000000000000000n;
  * +10^8 days from the Unix epoch, i.e. `+275760-09-13T00:00:00Z`.
  */
 export const MAX_EPOCH_NANOSECONDS = 8640000000000000000000n;
+/** TC39 `CheckISODaysRange`: a date may sit at most 10^8 days from the Unix epoch. */
+export const MAX_ISO_EPOCH_DAYS = 100_000_000;
 /**
  * Digits in `MAX_EPOCH_NANOSECONDS` (22) — the longest a decimal form of an in-range
  * epoch-nanosecond value can be, sign excluded.

package/dist/internal/exactDuration.d.ts

@@ -0,0 +1,37 @@
+/**
+ * An ISO 8601 duration as exact elapsed nanoseconds, signed, or `null` when it is not one.
+ *
+ * The transport rule for a span of exact time (`transitTime`, `classifyPunctuality`,
+ * `nextDeparture`, …):
+ *
+ * - Hours, minutes, seconds and fractions are elapsed time, and a day is 24 hours exactly. That
+ *   is how TC39 Temporal's `Duration.prototype.round` and `total` read a day when no
+ *   `relativeTo` is given.
+ * - Years, months and weeks return `null`: `round` and `total` require a `relativeTo` for them,
+ *   so they have no exact length on their own. A zero calendar component (`P0Y1D`) changes
+ *   nothing. (`Temporal.Instant#add` accepts no date unit at all, days included; callers add the
+ *   nanoseconds this returns instead.)
+ * - The result keeps the duration's sign, so a caller that needs a non-negative amount checks
+ *   `< 0n` itself. `-PT0S` is `0n`.
+ * - Summed in bigint, so it stays exact past 2^53 ns and across the whole instant range.
+ *
+ * @param value candidate ISO 8601 duration string
+ * @returns the duration in nanoseconds, negative for a negative duration, or null on invalid input
+ *
+ * @example exactDurationNanoseconds("PT1H") // 3600000000000n
+ * @example exactDurationNanoseconds("-PT5M") // -300000000000n
+ * @example exactDurationNanoseconds("P1D") // 86400000000000n
+ * @example exactDurationNanoseconds("P1W") // null
+ */
+export declare function exactDurationNanoseconds(value: unknown): bigint | null;
+/**
+ * `exactDurationNanoseconds` for an amount that may not be negative — a tolerance, a minimum
+ * connection — or `null`. Zero is allowed, and `-PT0S` is zero.
+ *
+ * @param value candidate ISO 8601 duration string
+ * @returns the duration in nanoseconds, zero or more, or null on invalid input or a negative duration
+ *
+ * @example nonNegativeExactDurationNanoseconds("PT15M") // 900000000000n
+ * @example nonNegativeExactDurationNanoseconds("-PT15M") // null
+ */
+export declare function nonNegativeExactDurationNanoseconds(value: unknown): bigint | null;

package/dist/internal/exactDuration.js

@@ -0,0 +1,64 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { NANOSECONDS_PER_DAY, NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, } from "./foreignEpochs.js";
+const NANOSECONDS_PER_HOUR = 3600000000000n;
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+/**
+ * An ISO 8601 duration as exact elapsed nanoseconds, signed, or `null` when it is not one.
+ *
+ * The transport rule for a span of exact time (`transitTime`, `classifyPunctuality`,
+ * `nextDeparture`, …):
+ *
+ * - Hours, minutes, seconds and fractions are elapsed time, and a day is 24 hours exactly. That
+ *   is how TC39 Temporal's `Duration.prototype.round` and `total` read a day when no
+ *   `relativeTo` is given.
+ * - Years, months and weeks return `null`: `round` and `total` require a `relativeTo` for them,
+ *   so they have no exact length on their own. A zero calendar component (`P0Y1D`) changes
+ *   nothing. (`Temporal.Instant#add` accepts no date unit at all, days included; callers add the
+ *   nanoseconds this returns instead.)
+ * - The result keeps the duration's sign, so a caller that needs a non-negative amount checks
+ *   `< 0n` itself. `-PT0S` is `0n`.
+ * - Summed in bigint, so it stays exact past 2^53 ns and across the whole instant range.
+ *
+ * @param value candidate ISO 8601 duration string
+ * @returns the duration in nanoseconds, negative for a negative duration, or null on invalid input
+ *
+ * @example exactDurationNanoseconds("PT1H") // 3600000000000n
+ * @example exactDurationNanoseconds("-PT5M") // -300000000000n
+ * @example exactDurationNanoseconds("P1D") // 86400000000000n
+ * @example exactDurationNanoseconds("P1W") // null
+ */
+export function exactDurationNanoseconds(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    try {
+        const duration = Temporal.Duration.from(value);
+        if (duration.years !== 0 || duration.months !== 0 || duration.weeks !== 0) {
+            return null;
+        }
+        return (BigInt(duration.days) * NANOSECONDS_PER_DAY +
+            BigInt(duration.hours) * NANOSECONDS_PER_HOUR +
+            BigInt(duration.minutes) * NANOSECONDS_PER_MINUTE +
+            BigInt(duration.seconds) * NANOSECONDS_PER_SECOND +
+            BigInt(duration.milliseconds) * NANOSECONDS_PER_MILLISECOND +
+            BigInt(duration.microseconds) * NANOSECONDS_PER_MICROSECOND +
+            BigInt(duration.nanoseconds));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `exactDurationNanoseconds` for an amount that may not be negative — a tolerance, a minimum
+ * connection — or `null`. Zero is allowed, and `-PT0S` is zero.
+ *
+ * @param value candidate ISO 8601 duration string
+ * @returns the duration in nanoseconds, zero or more, or null on invalid input or a negative duration
+ *
+ * @example nonNegativeExactDurationNanoseconds("PT15M") // 900000000000n
+ * @example nonNegativeExactDurationNanoseconds("-PT15M") // null
+ */
+export function nonNegativeExactDurationNanoseconds(value) {
+    const nanoseconds = exactDurationNanoseconds(value);
+    return nanoseconds === null || nanoseconds < 0n ? null : nanoseconds;
+}

package/dist/internal/exactMoment.d.ts

@@ -0,0 +1,72 @@
+/**
+ * How an exact moment was written, so a result can be written the same way: in a named zone
+ * (the bracket), at a UTC offset (its text exactly as written), or as a `Z` instant.
+ */
+export type MomentNotation = {
+    kind: "zone";
+    timeZone: string;
+} | {
+    kind: "offset";
+    offset: string;
+} | {
+    kind: "utc";
+};
+/** An exact moment: its epoch nanoseconds and how it was written. */
+export type ExactMoment = {
+    nanoseconds: bigint;
+    notation: MomentNotation;
+};
+/**
+ * Read an exact moment the way `transitTime` reads a departure, or `null`.
+ *
+ * - A zoned string (`…-04:00[America/New_York]`) is read through its bracket, which must name a
+ *   real zone that agrees with the offset, as `isValidZonedDateTime` requires. An offset written
+ *   to the minute agrees when it is the zone's sub-minute offset rounded (TC39
+ *   `ToTemporalZonedDateTime`, match-minutes), which is how `writeExactMoment` writes one.
+ * - A wall time with a bracket and no offset is read in that zone with the `"compatible"`
+ *   disambiguation policy (`context/reference/LOCAL_TIME_RESOLUTION.md`): an **ambiguous** wall
+ *   time, a fall-back hour the clock ran through twice, resolves to the **earlier** instant
+ *   (`2024-11-03T01:30:00[America/New_York]` is `01:30-04:00`), and a **nonexistent** one, a
+ *   spring-forward hour the clock skipped, to the **later** instant
+ *   (`2024-03-10T02:30:00[America/New_York]` is `03:30-04:00`). A caller that must not guess
+ *   refuses the offset-less form before calling, as `nextDeparture` does.
+ * - A string that names a zone the zoned read rejects is `null`; it never falls back to its
+ *   offset. That includes a zoned string whose local date is −271821-04-19, which
+ *   `Temporal.ZonedDateTime.from` refuses although its instant is in range.
+ * - Otherwise an instant (`Z` or an offset) as `parseInstantNanoseconds` reads it: calendar and
+ *   elective annotations are ignored and a critical unknown one is rejected. Its offset text is
+ *   kept exactly as written, sub-minute and `,` fractions included.
+ *
+ * @param value candidate zoned datetime or instant string
+ * @returns the moment's epoch nanoseconds and notation, or null on invalid input
+ *
+ * @example readExactMoment("2024-06-15T10:00:00+09:00") // { nanoseconds: 1718413200000000000n, notation: { kind: "offset", offset: "+09:00" } }
+ * @example readExactMoment("2024-06-15T10:00:00Z[Not/AZone]") // null
+ * @example readExactMoment("2024-03-10T02:30:00[America/New_York]") // { nanoseconds: 1710055800000000000n, notation: { kind: "zone", timeZone: "America/New_York" } } (nonexistent: the later instant, 03:30-04:00)
+ */
+export declare function readExactMoment(value: unknown): ExactMoment | null;
+/**
+ * Write epoch nanoseconds the way a moment was written: in its zone, at its offset text, or as a
+ * `Z` instant. `""` when the nanoseconds leave the instant range (±8.64e21 ns).
+ *
+ * - A zone notation is written as Temporal writes a `ZonedDateTime`: the offset in force at that
+ *   instant, rounded to the minute (`-00:45` for Monrovia's −00:44:30), then the bracket.
+ *   `readExactMoment` and `parseInstantNanoseconds` read that string back as the same instant,
+ *   with two exceptions, both Temporal's own. A wall time repeated inside a sub-minute offset
+ *   change reads as its first pass, in both readers (`parseInstantNanoseconds` states the
+ *   rule). And `readExactMoment`, a zoned read, refuses a string whose local date is
+ *   −271821-04-19 (`CheckISODaysRange` in `Temporal.ZonedDateTime.from`): the string written
+ *   for the first hours of the instant range in a zone west of Greenwich reads as `null` there,
+ *   and as its instant in `parseInstantNanoseconds`
+ *   (`context/domination/js-temporal-polyfill-bugs.md` § J).
+ * - An offset notation keeps its text as written. The wall clock is shifted, never the instant
+ *   (`wallClockAtOffset`), so the last hours of the range still write at a positive offset.
+ *
+ * @param nanoseconds epoch nanoseconds of the moment to write
+ * @param notation how to write it, from `readExactMoment`
+ * @returns the moment as a zoned, offset or `Z` string, or "" when it is out of range
+ *
+ * @example writeExactMoment(0n, { kind: "offset", offset: "+09:00" }) // "1970-01-01T09:00:00+09:00"
+ * @example writeExactMoment(0n, { kind: "zone", timeZone: "UTC" }) // "1970-01-01T00:00:00+00:00[UTC]"
+ */
+export declare function writeExactMoment(nanoseconds: bigint, notation: MomentNotation): string;

package/dist/internal/exactMoment.js

@@ -0,0 +1,114 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../zoned/validate/isValidZonedDateTime.js";
+import { parseInstantNanoseconds } from "./instantNanoseconds.js";
+import { EXTENDED_UTC_OFFSET, TIME_ZONE_ANNOTATION } from "./isoStringBody.js";
+import { wallClockAtOffset } from "./wallClockAtOffset.js";
+import { utcOffsetStringNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+/**
+ * Trailing `Z` or extended offset of an instant string, before any annotation. The offset grammar
+ * is `isValidInstant`'s own (`EXTENDED_UTC_OFFSET`), so every offset it accepts, `,` fractions
+ * included, is captured as written.
+ */
+const trailingOffset = new RegExp(`(Z|${EXTENDED_UTC_OFFSET})(?:\\[[^\\]]*\\])*$`);
+/**
+ * A time-zone annotation anywhere in the string (`TIME_ZONE_ANNOTATION`). Every `key=value`
+ * bracket is a tagged annotation, which the instant parse already decides.
+ */
+const zoneAnnotation = new RegExp(TIME_ZONE_ANNOTATION);
+/**
+ * Read an exact moment the way `transitTime` reads a departure, or `null`.
+ *
+ * - A zoned string (`…-04:00[America/New_York]`) is read through its bracket, which must name a
+ *   real zone that agrees with the offset, as `isValidZonedDateTime` requires. An offset written
+ *   to the minute agrees when it is the zone's sub-minute offset rounded (TC39
+ *   `ToTemporalZonedDateTime`, match-minutes), which is how `writeExactMoment` writes one.
+ * - A wall time with a bracket and no offset is read in that zone with the `"compatible"`
+ *   disambiguation policy (`context/reference/LOCAL_TIME_RESOLUTION.md`): an **ambiguous** wall
+ *   time, a fall-back hour the clock ran through twice, resolves to the **earlier** instant
+ *   (`2024-11-03T01:30:00[America/New_York]` is `01:30-04:00`), and a **nonexistent** one, a
+ *   spring-forward hour the clock skipped, to the **later** instant
+ *   (`2024-03-10T02:30:00[America/New_York]` is `03:30-04:00`). A caller that must not guess
+ *   refuses the offset-less form before calling, as `nextDeparture` does.
+ * - A string that names a zone the zoned read rejects is `null`; it never falls back to its
+ *   offset. That includes a zoned string whose local date is −271821-04-19, which
+ *   `Temporal.ZonedDateTime.from` refuses although its instant is in range.
+ * - Otherwise an instant (`Z` or an offset) as `parseInstantNanoseconds` reads it: calendar and
+ *   elective annotations are ignored and a critical unknown one is rejected. Its offset text is
+ *   kept exactly as written, sub-minute and `,` fractions included.
+ *
+ * @param value candidate zoned datetime or instant string
+ * @returns the moment's epoch nanoseconds and notation, or null on invalid input
+ *
+ * @example readExactMoment("2024-06-15T10:00:00+09:00") // { nanoseconds: 1718413200000000000n, notation: { kind: "offset", offset: "+09:00" } }
+ * @example readExactMoment("2024-06-15T10:00:00Z[Not/AZone]") // null
+ * @example readExactMoment("2024-03-10T02:30:00[America/New_York]") // { nanoseconds: 1710055800000000000n, notation: { kind: "zone", timeZone: "America/New_York" } } (nonexistent: the later instant, 03:30-04:00)
+ */
+export function readExactMoment(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    try {
+        if (isValidZonedDateTime(value)) {
+            const zoned = zonedDateTimeFrom(value);
+            return {
+                nanoseconds: zoned.epochNanoseconds,
+                notation: { kind: "zone", timeZone: zoned.timeZoneId },
+            };
+        }
+        if (zoneAnnotation.test(value)) {
+            return null;
+        }
+        const nanoseconds = parseInstantNanoseconds(value);
+        if (nanoseconds === null) {
+            return null;
+        }
+        const offset = trailingOffset.exec(value)?.[1] ?? "Z";
+        return {
+            nanoseconds,
+            notation: offset === "Z" ? { kind: "utc" } : { kind: "offset", offset },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write epoch nanoseconds the way a moment was written: in its zone, at its offset text, or as a
+ * `Z` instant. `""` when the nanoseconds leave the instant range (±8.64e21 ns).
+ *
+ * - A zone notation is written as Temporal writes a `ZonedDateTime`: the offset in force at that
+ *   instant, rounded to the minute (`-00:45` for Monrovia's −00:44:30), then the bracket.
+ *   `readExactMoment` and `parseInstantNanoseconds` read that string back as the same instant,
+ *   with two exceptions, both Temporal's own. A wall time repeated inside a sub-minute offset
+ *   change reads as its first pass, in both readers (`parseInstantNanoseconds` states the
+ *   rule). And `readExactMoment`, a zoned read, refuses a string whose local date is
+ *   −271821-04-19 (`CheckISODaysRange` in `Temporal.ZonedDateTime.from`): the string written
+ *   for the first hours of the instant range in a zone west of Greenwich reads as `null` there,
+ *   and as its instant in `parseInstantNanoseconds`
+ *   (`context/domination/js-temporal-polyfill-bugs.md` § J).
+ * - An offset notation keeps its text as written. The wall clock is shifted, never the instant
+ *   (`wallClockAtOffset`), so the last hours of the range still write at a positive offset.
+ *
+ * @param nanoseconds epoch nanoseconds of the moment to write
+ * @param notation how to write it, from `readExactMoment`
+ * @returns the moment as a zoned, offset or `Z` string, or "" when it is out of range
+ *
+ * @example writeExactMoment(0n, { kind: "offset", offset: "+09:00" }) // "1970-01-01T09:00:00+09:00"
+ * @example writeExactMoment(0n, { kind: "zone", timeZone: "UTC" }) // "1970-01-01T00:00:00+00:00[UTC]"
+ */
+export function writeExactMoment(nanoseconds, notation) {
+    try {
+        const instant = Temporal.Instant.fromEpochNanoseconds(nanoseconds);
+        if (notation.kind === "zone") {
+            return instant.toZonedDateTimeISO(notation.timeZone).toString();
+        }
+        if (notation.kind === "utc") {
+            return instant.toString();
+        }
+        const wall = wallClockAtOffset(instant, utcOffsetStringNanoseconds(notation.offset));
+        return `${wall.toString()}${notation.offset}`;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/internal/fiscalCalendar.d.ts

@@ -10,9 +10,10 @@ import type { FiscalPattern } from "../types/index.js";
  * off the result.
  *
  * - The month-day is moved into `year` with Temporal's `overflow: "constrain"`, so a
- *   February 29 anchor targets February 28 in a common year before the weekday shift. A
- *   "month-end" rule (the 26 CFR 1.441-2 style, "the last Saturday of February") would
- *   instead put a February 28 anchor on February 29 in a leap year; this does not.
+ *   February 29 anchor targets February 28 in a common year before the weekday shift. A rule
+ *   tied to the end of a month ("the last Saturday of February", or the Saturday nearest the
+ *   month's last day) would instead put a February 28 anchor on February 29 in a leap year;
+ *   this does not.
  */
 export declare function fiscalYearEndIn(anchor: Temporal.PlainDate, year: number): Temporal.PlainDate;
 /**

package/dist/internal/fiscalCalendar.js

@@ -32,9 +32,10 @@ const NEAREST_WEEKDAY_RADIUS = 3;
  * off the result.
  *
  * - The month-day is moved into `year` with Temporal's `overflow: "constrain"`, so a
- *   February 29 anchor targets February 28 in a common year before the weekday shift. A
- *   "month-end" rule (the 26 CFR 1.441-2 style, "the last Saturday of February") would
- *   instead put a February 28 anchor on February 29 in a leap year; this does not.
+ *   February 29 anchor targets February 28 in a common year before the weekday shift. A rule
+ *   tied to the end of a month ("the last Saturday of February", or the Saturday nearest the
+ *   month's last day) would instead put a February 28 anchor on February 29 in a leap year;
+ *   this does not.
  */
 export function fiscalYearEndIn(anchor, year) {
     const target = anchor.with({ year }, { overflow: "constrain" });

package/dist/internal/formatCalendarDays.d.ts

@@ -13,7 +13,7 @@ import type { Temporal } from "@js-temporal/polyfill";
  * @example formatCalendarDays(1, 1710685800000, "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
  * @example formatCalendarDays(-9, 1710685800000, "UTC", "en-US", "short") // "March 17, 2024 at 2:30 PM"
  */
-export declare function formatCalendarDays(diffDays: number, epochMilliseconds: number, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "full"): string;
+export declare function formatCalendarDays(diffDays: number, epochMilliseconds: number, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "long" | "full"): string;
 /**
  * `formatCalendarDays` for two instants, counting calendar days between their dates in `timeZone`.
  *
@@ -25,4 +25,4 @@ export declare function formatCalendarDays(diffDays: number, epochMilliseconds:
  * @returns the phrase; throws where Temporal or `Intl` throws
  * @example formatCalendarInstants(Temporal.Instant.from("2024-03-17T14:30:00Z"), Temporal.Instant.from("2024-03-16T09:00:00Z"), "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
  */
-export declare function formatCalendarInstants(target: Temporal.Instant, reference: Temporal.Instant, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "full"): string;
+export declare function formatCalendarInstants(target: Temporal.Instant, reference: Temporal.Instant, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "long" | "full"): string;

package/dist/internal/formatRelativeDuration.d.ts

@@ -23,5 +23,25 @@ export interface RelativeDurationFormatOptions {
  * @example formatRelativeDuration(Temporal.Duration.from({ hours: 36 }), "en-US", { largestUnit: "hour" }, () => 0) // "in 36 hours"
  * @example formatRelativeDuration(Temporal.Duration.from({ days: 400 }), "en-US", {}, () => 1) // "next year" (month/year totals come from calendarTotal)
  */
-export declare function formatRelativeDuration(diff: Temporal.Duration, locale: string | string[] | undefined, options: RelativeDurationFormatOptions, calendarTotal: (unit: RelativeUnitName) => number): string;
+export declare function formatRelativeDuration(diff: Temporal.Duration, locale: string | string[] | undefined, options: RelativeDurationFormatOptions, calendarTotal: (unit: RelativeUnit) => number): string;
+/**
+ * Round a distance to a whole number of `unit` and render it with `Intl.RelativeTimeFormat`. The
+ * shared last step of every `formatRelative*` function.
+ *
+ * - `numeric` and `style` are read here, once each (GetOption); `roundingMethod` is passed in
+ *   because the caller has already read it.
+ *
+ * @param total the signed fractional distance in `unit`
+ * @param unit the singular unit the distance is written in
+ * @param locale BCP 47 locale(s) passed through to `Intl.RelativeTimeFormat`
+ * @param options the caller's options, read for `numeric` (default `"auto"`) and `style`
+ *   (default `"long"`)
+ * @param roundingMethod the caller's `roundingMethod`, `undefined` for the default `"round"`
+ * @returns the formatted phrase; throws where `Intl` throws or the rounding method is invalid, for
+ *   the caller's sentinel
+ * @example formatRelativeAmount(-1.5, "hour", "en-US", {}, "floor") // "2 hours ago"
+ * @example formatRelativeAmount(1, "day", "en-US", { numeric: "always" }, undefined) // "in 1 day"
+ * @example formatRelativeAmount(1, "day", "en-US", { style: "wide" as never }, undefined) // throws RangeError
+ */
+export declare function formatRelativeAmount(total: number, unit: RelativeUnit, locale: string | string[] | undefined, options: Pick<RelativeDurationFormatOptions, "numeric" | "style">, roundingMethod: RelativeRoundingMethod | undefined): string;
 export {};

package/dist/internal/formatRelativeDuration.js

@@ -1,5 +1,18 @@
 import { normalizeDateTime } from "./normalizeDateTime.js";
 import { resolveRelativeRounding } from "./resolveRelativeRounding.js";
+import { optionOrDefault } from "./optionOrDefault.js";
+import { resolveRelativeUnit } from "./resolveRelativeUnit.js";
+// The units of the seven-unit functions: Temporal's datetime unit group down to the second, less
+// the sub-second units, which Intl.RelativeTimeFormat does not have.
+const RELATIVE_UNITS = [
+    "year",
+    "month",
+    "week",
+    "day",
+    "hour",
+    "minute",
+    "second",
+];
 // Seconds up to a day, then formatRelativeDate's day thresholds (7, 28 and 365 days).
 const SECONDS_PER_DAY = 86_400;
 const AUTO_UNITS = [
@@ -26,20 +39,47 @@ const AUTO_UNITS = [
  * @example formatRelativeDuration(Temporal.Duration.from({ days: 400 }), "en-US", {}, () => 1) // "next year" (month/year totals come from calendarTotal)
  */
 export function formatRelativeDuration(diff, locale, options, calendarTotal) {
+    // Each option is read once (GetOption), and largestUnit is validated before anything is measured.
+    const forcedUnit = resolveRelativeUnit(options.largestUnit, RELATIVE_UNITS);
+    const roundingMethod = options.roundingMethod;
     const absSeconds = Math.abs(diff.total("second"));
-    const unit = options.largestUnit === undefined
+    const unit = forcedUnit === undefined
         ? (AUTO_UNITS.find((t) => absSeconds < t.maxSeconds)?.unit ?? "year")
-        : options.largestUnit;
-    let amount;
+        : forcedUnit;
+    let total;
     try {
-        amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+        total = diff.total(unit);
     }
     catch {
         // month/year are calendrical and need a relativeTo anchor.
-        amount = resolveRelativeRounding(calendarTotal(unit), options.roundingMethod);
+        total = calendarTotal(unit);
     }
+    // Outside the retry: an invalid roundingMethod throws once, straight to the caller's sentinel.
+    return formatRelativeAmount(total, unit, locale, options, roundingMethod);
+}
+/**
+ * Round a distance to a whole number of `unit` and render it with `Intl.RelativeTimeFormat`. The
+ * shared last step of every `formatRelative*` function.
+ *
+ * - `numeric` and `style` are read here, once each (GetOption); `roundingMethod` is passed in
+ *   because the caller has already read it.
+ *
+ * @param total the signed fractional distance in `unit`
+ * @param unit the singular unit the distance is written in
+ * @param locale BCP 47 locale(s) passed through to `Intl.RelativeTimeFormat`
+ * @param options the caller's options, read for `numeric` (default `"auto"`) and `style`
+ *   (default `"long"`)
+ * @param roundingMethod the caller's `roundingMethod`, `undefined` for the default `"round"`
+ * @returns the formatted phrase; throws where `Intl` throws or the rounding method is invalid, for
+ *   the caller's sentinel
+ * @example formatRelativeAmount(-1.5, "hour", "en-US", {}, "floor") // "2 hours ago"
+ * @example formatRelativeAmount(1, "day", "en-US", { numeric: "always" }, undefined) // "in 1 day"
+ * @example formatRelativeAmount(1, "day", "en-US", { style: "wide" as never }, undefined) // throws RangeError
+ */
+export function formatRelativeAmount(total, unit, locale, options, roundingMethod) {
+    const amount = resolveRelativeRounding(total, roundingMethod);
     return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-        numeric: options.numeric === undefined ? "auto" : options.numeric,
-        style: options.style === undefined ? "long" : options.style,
+        numeric: optionOrDefault(options.numeric, "auto"),
+        style: optionOrDefault(options.style, "long"),
     }).format(amount, unit));
 }

package/dist/internal/index.d.ts

@@ -7,6 +7,7 @@ export { calendarOfAllDateValues, calendarSystemOfDateValue, } from "./calendarV
 export { calendarOfAllZonedValues, calendarSystemOfZonedValue, } from "./calendarValueOfZoned.js";
 export { formatZonedInCalendar, parseCalendarZonedValue, } from "./calendarZonedString.js";
 export { cycleFieldValue } from "./cycleFieldValue.js";
+export { isInDaylightTime, observesDaylightTime } from "./daylightTime.js";
 export { fiscalPeriodOfWeek, fiscalYearOf } from "./fiscalCalendar.js";
 export { floorDivide } from "./floorDivide.js";
 export { DOT_NET_TICKS_EPOCH_OFFSET, EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PHANTOM_END_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, EXCEL_PHANTOM_SERIAL, FILE_TIME_EPOCH_OFFSET_TICKS, MAX_DOT_NET_TICKS, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MAX_FILE_TIME, MILLISECONDS_PER_DAY, MIN_DOT_NET_TICKS, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, MIN_FILE_TIME, MIN_PG_MICROSECONDS, NANOSECONDS_PER_DAY, NANOSECONDS_PER_DAY_NUMBER, NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, NANOSECONDS_PER_TICK, NTP_EPOCH_OFFSET_NANOSECONDS, NTP_ERA_UNITS, NTP_UNITS_PER_SECOND, PG_EPOCH_OFFSET_MICROSECONDS, } from "./foreignEpochs.js";
@@ -14,13 +15,15 @@ export { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "./epochNa
 export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.js";
+export { exactDurationNanoseconds, nonNegativeExactDurationNanoseconds, } from "./exactDuration.js";
+export { type ExactMoment, readExactMoment, writeExactMoment, } from "./exactMoment.js";
 export { formatDateInCalendar } from "./formatDateInCalendar.js";
 export { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "./freeTimeLedger.js";
 export { halfOpenAbuts, halfOpenContainsPoint, halfOpenContainsSpan, halfOpenDifference, halfOpenIntersection, halfOpenMerge, halfOpenOverlap, halfOpenUnion, halfOpenXor, } from "./halfOpenIntervals.js";
-export { EXTENDED_UTC_OFFSET, isoStringBody, TIME_ZONE_ANNOTATION, } from "./isoStringBody.js";
+export { isoStringBody, TIME_ZONE_ANNOTATION } from "./isoStringBody.js";
 export { formatHourDuration } from "./hourDurationString.js";
 export { canonicalInstantIntervals } from "./instantIntervalText.js";
-export { parseInstantNanoseconds } from "./instantNanoseconds.js";
+export { instantFrom, parseInstantNanoseconds } from "./instantNanoseconds.js";
 export { coalesceIntervalNanoseconds, parseIntervalNanoseconds, parseIntervalNanosecondsList, } from "./intervalNanoseconds.js";
 export { resolveDurationRelativeTo } from "./resolveDurationRelativeTo.js";
 export { formatUtcOffset, parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
@@ -39,6 +42,7 @@ export { monthGridWeekRow } from "./monthGridWeekRow.js";
 export { normalizeDateTime } from "./normalizeDateTime.js";
 export { DATE_PATTERN_FIELDS, DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, TIME_PATTERN_FIELDS, } from "./patternToken.js";
 export { plainDateAdd } from "./plainDateAdd.js";
+export { parsePunctualityTolerance, punctualityOf } from "./punctuality.js";
 export { plainDateUntil } from "./plainDateUntil.js";
 export { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
 export { resolveDurationUnit } from "./resolveDurationUnit.js";
@@ -46,10 +50,11 @@ export { resolveOverflow } from "./resolveOverflow.js";
 export { resolveRelativeRounding } from "./resolveRelativeRounding.js";
 export { parseUnixEpochInterval, parseUnixEpochIntervalList, parseUnixEpochIntervalPair, parseUnixEpochValue, } from "./unixEpochValue.js";
 export { tileByUnit } from "./splitStep.js";
+export { parseTimestampEvents } from "./timestampEvents.js";
 export { countZonedBuckets, nextZonedBucketStart, type WeekStartDay, zonedUnitEnd, zonedUnitStart, } from "./zonedBucket.js";
 export { countZonedLocalDates } from "./zonedLocalDates.js";
-export { utcOffsetStringNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+export { zonedDateTimeFrom } from "./zonedWallClock.js";
 export { wallClockAtOffset } from "./wallClockAtOffset.js";
 export { durationCompare, durationRound, durationTotal, isCalendarDifferenceAcrossZones, plainUntilWithRounding, zonedUntil, } from "./zonedWallClockDifference.js";
-export { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
+export { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedPreviousTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
 export { zonelessCalendarDate } from "./zonelessCalendarDate.js";

package/dist/internal/index.js

@@ -7,6 +7,7 @@ export { calendarOfAllDateValues, calendarSystemOfDateValue, } from "./calendarV
 export { calendarOfAllZonedValues, calendarSystemOfZonedValue, } from "./calendarValueOfZoned.js";
 export { formatZonedInCalendar, parseCalendarZonedValue, } from "./calendarZonedString.js";
 export { cycleFieldValue } from "./cycleFieldValue.js";
+export { isInDaylightTime, observesDaylightTime } from "./daylightTime.js";
 export { fiscalPeriodOfWeek, fiscalYearOf } from "./fiscalCalendar.js";
 export { floorDivide } from "./floorDivide.js";
 export { DOT_NET_TICKS_EPOCH_OFFSET, EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PHANTOM_END_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, EXCEL_PHANTOM_SERIAL, FILE_TIME_EPOCH_OFFSET_TICKS, MAX_DOT_NET_TICKS, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MAX_FILE_TIME, MILLISECONDS_PER_DAY, MIN_DOT_NET_TICKS, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, MIN_FILE_TIME, MIN_PG_MICROSECONDS, NANOSECONDS_PER_DAY, NANOSECONDS_PER_DAY_NUMBER, NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, NANOSECONDS_PER_TICK, NTP_EPOCH_OFFSET_NANOSECONDS, NTP_ERA_UNITS, NTP_UNITS_PER_SECOND, PG_EPOCH_OFFSET_MICROSECONDS, } from "./foreignEpochs.js";
@@ -14,13 +15,15 @@ export { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "./epochNa
 export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.js";
+export { exactDurationNanoseconds, nonNegativeExactDurationNanoseconds, } from "./exactDuration.js";
+export { readExactMoment, writeExactMoment, } from "./exactMoment.js";
 export { formatDateInCalendar } from "./formatDateInCalendar.js";
 export { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "./freeTimeLedger.js";
 export { halfOpenAbuts, halfOpenContainsPoint, halfOpenContainsSpan, halfOpenDifference, halfOpenIntersection, halfOpenMerge, halfOpenOverlap, halfOpenUnion, halfOpenXor, } from "./halfOpenIntervals.js";
-export { EXTENDED_UTC_OFFSET, isoStringBody, TIME_ZONE_ANNOTATION, } from "./isoStringBody.js";
+export { isoStringBody, TIME_ZONE_ANNOTATION } from "./isoStringBody.js";
 export { formatHourDuration } from "./hourDurationString.js";
 export { canonicalInstantIntervals } from "./instantIntervalText.js";
-export { parseInstantNanoseconds } from "./instantNanoseconds.js";
+export { instantFrom, parseInstantNanoseconds } from "./instantNanoseconds.js";
 export { coalesceIntervalNanoseconds, parseIntervalNanoseconds, parseIntervalNanosecondsList, } from "./intervalNanoseconds.js";
 export { resolveDurationRelativeTo } from "./resolveDurationRelativeTo.js";
 export { formatUtcOffset, parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
@@ -39,6 +42,7 @@ export { monthGridWeekRow } from "./monthGridWeekRow.js";
 export { normalizeDateTime } from "./normalizeDateTime.js";
 export { DATE_PATTERN_FIELDS, DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, TIME_PATTERN_FIELDS, } from "./patternToken.js";
 export { plainDateAdd } from "./plainDateAdd.js";
+export { parsePunctualityTolerance, punctualityOf } from "./punctuality.js";
 export { plainDateUntil } from "./plainDateUntil.js";
 export { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
 export { resolveDurationUnit } from "./resolveDurationUnit.js";
@@ -46,10 +50,11 @@ export { resolveOverflow } from "./resolveOverflow.js";
 export { resolveRelativeRounding } from "./resolveRelativeRounding.js";
 export { parseUnixEpochInterval, parseUnixEpochIntervalList, parseUnixEpochIntervalPair, parseUnixEpochValue, } from "./unixEpochValue.js";
 export { tileByUnit } from "./splitStep.js";
+export { parseTimestampEvents } from "./timestampEvents.js";
 export { countZonedBuckets, nextZonedBucketStart, zonedUnitEnd, zonedUnitStart, } from "./zonedBucket.js";
 export { countZonedLocalDates } from "./zonedLocalDates.js";
-export { utcOffsetStringNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+export { zonedDateTimeFrom } from "./zonedWallClock.js";
 export { wallClockAtOffset } from "./wallClockAtOffset.js";
 export { durationCompare, durationRound, durationTotal, isCalendarDifferenceAcrossZones, plainUntilWithRounding, zonedUntil, } from "./zonedWallClockDifference.js";
-export { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
+export { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedPreviousTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
 export { zonelessCalendarDate } from "./zonelessCalendarDate.js";

package/dist/internal/instantFormatOptions.js

@@ -4,6 +4,7 @@
 // and GetDateTimeFormat with required ~any~ and inherit ~all~, so every caller
 // field, including `era` and `timeZoneName`, is passed on unchanged.
 import { plainDateTimeFormatOptions } from "./plainFormatOptions.js";
+import { optionOrDefault } from "./optionOrDefault.js";
 // GetDateTimeFormat requiredOptions for ~any~. `era` and `timeZoneName` are
 // deliberately absent: neither suppresses the defaults.
 const REQUIRED_FIELDS = [
@@ -58,7 +59,7 @@ export function instantFormatOptions(options, timeZone, defaults) {
         ...DEFAULT_FIELDS,
         ...(defaults === "zoned-date-time"
             ? {
-                timeZoneName: options.timeZoneName === undefined ? "short" : options.timeZoneName,
+                timeZoneName: optionOrDefault(options.timeZoneName, "short"),
             }
             : {}),
         timeZone,