@northguild/gmt 1.16.0 → 1.18.0

package/dist/internal/daylightTime.js

@@ -0,0 +1,164 @@
+import { zonedNextTransition, zonedPreviousTransition, } from "./zonedWallClockOperations.js";
+/**
+ * The longest a daylight period can last: a forward change and the backward change that undoes it
+ * are less than 365 days apart. Daylight time is seasonal, so it recurs within every year, and
+ * 365 days is the shortest year. A longer advance is a change of standard time.
+ */
+const DAYLIGHT_PERIOD_LIMIT_NANOSECONDS = 365n * 86400000000000n;
+/**
+ * Offset changes read in each direction before the walk gives up and answers `false`, the
+ * sentinel: a bounded loop that runs out never returns a partial answer. Every walk here is also
+ * limited to 365 days, and a year of `Africa/Casablanca` holds four changes, so no real zone
+ * reaches the bound; `daylightTime.test.ts` reaches it with a made-up zone.
+ */
+const MAX_WALKED_CHANGES = 64;
+function offsetChangeAt(transition) {
+    return {
+        at: transition.epochNanoseconds,
+        step: transition.offsetNanoseconds -
+            transition.subtract({ nanoseconds: 1 }).offsetNanoseconds,
+    };
+}
+/**
+ * Apply one change to the list of advances not yet undone. A forward change joins the list. A
+ * backward change undoes the most recent advance of the same size, if that advance is less than
+ * 365 days old, and returns it; otherwise it undoes nothing.
+ */
+function applyChange(open, change) {
+    if (change.step > 0) {
+        open.push(change);
+        return null;
+    }
+    for (let i = open.length - 1; i >= 0; i--) {
+        if (open[i].step !== -change.step) {
+            continue;
+        }
+        if (change.at - open[i].at >= DAYLIGHT_PERIOD_LIMIT_NANOSECONDS) {
+            return null;
+        }
+        return open.splice(i, 1)[0];
+    }
+    return null;
+}
+/** Whether `to` is less than the daylight period limit after `from`. */
+function isWithinLimit(from, to) {
+    return to - from < DAYLIGHT_PERIOD_LIMIT_NANOSECONDS;
+}
+/**
+ * The advances still open just before `next`: made in the 365 days before it and not yet undone.
+ * An older advance cannot be undone at or after `next`. Null past `MAX_WALKED_CHANGES` changes.
+ *
+ * @param next the first change after the instant being judged
+ * @param latest the change before `next`, already known to be within the limit
+ */
+function openAdvancesBefore(next, latest) {
+    const changes = [offsetChangeAt(latest)];
+    let cursor = latest;
+    for (let i = 0; i <= MAX_WALKED_CHANGES; i++) {
+        const previous = zonedPreviousTransition(cursor, next.epochNanoseconds - DAYLIGHT_PERIOD_LIMIT_NANOSECONDS);
+        if (previous === null ||
+            !isWithinLimit(previous.epochNanoseconds, next.epochNanoseconds)) {
+            const open = [];
+            for (const change of changes) {
+                applyChange(open, change);
+            }
+            return open;
+        }
+        changes.unshift(offsetChangeAt(previous));
+        cursor = previous;
+    }
+    return null;
+}
+/**
+ * Whether a change from `next` onwards undoes one of the `open` advances made at or before `at`.
+ * It has to come less than 365 days after `at`, since the advance is no later than `at`.
+ */
+function isUndoneFrom(next, open, at) {
+    let cursor = next;
+    for (let i = 0; i <= MAX_WALKED_CHANGES; i++) {
+        if (cursor === null || !isWithinLimit(at, cursor.epochNanoseconds)) {
+            return false;
+        }
+        const undone = applyChange(open, offsetChangeAt(cursor));
+        if (undone !== null && undone.at <= at) {
+            return true;
+        }
+        cursor = zonedNextTransition(cursor, at + DAYLIGHT_PERIOD_LIMIT_NANOSECONDS);
+    }
+    return false;
+}
+/**
+ * Whether an instant is in daylight saving time, read from the zone's offset changes alone.
+ *
+ * The rule: daylight time runs from a forward change of the clocks to the backward change that
+ * undoes it. A backward change undoes the most recent forward change of the same size that is not
+ * yet undone, and only if it comes less than 365 days after it. An instant is in daylight time when
+ * it is at or after such a forward change and before the backward change paired with it.
+ *
+ * A forward change that is never undone, or undone a year or more later, is a change of standard
+ * time (`Europe/Istanbul` 2016, `Europe/Moscow` 2011 to 2014), as is any backward change with no
+ * forward change to undo (`Asia/Almaty` 2024).
+ *
+ * This is GMT's own definition, not the tz database's daylight flag, which no JavaScript API
+ * exposes and offsets do not determine.
+ *
+ * Cost: one transition lookup forward, then one back, and more only outside the ordinary summer
+ * case. A paired change is less than 365 days away, so every lookup is given that limit and reads
+ * no further: with GMT's own search (temporalCompat D13) at most 74 offset samples and 51 reads to
+ * pin a change, for any zone and any instant.
+ *
+ * @param zoned the instant, in the zone to read
+ * @returns true in daylight time, false in standard time or when the walk exceeds its bound
+ */
+export function isInDaylightTime(zoned) {
+    const at = zoned.epochNanoseconds;
+    // Daylight time ends with a clock change. No change ahead, or none within the limit: standard.
+    const next = zonedNextTransition(zoned, at + DAYLIGHT_PERIOD_LIMIT_NANOSECONDS);
+    if (next === null || !isWithinLimit(at, next.epochNanoseconds)) {
+        return false;
+    }
+    // It begins with one too, and no change in the 365 days before `next` leaves nothing to undo.
+    const latest = zonedPreviousTransition(next, next.epochNanoseconds - DAYLIGHT_PERIOD_LIMIT_NANOSECONDS);
+    if (latest === null ||
+        !isWithinLimit(latest.epochNanoseconds, next.epochNanoseconds)) {
+        return false;
+    }
+    // The ordinary summer: the clocks last went forward, and next go back by as much. The latest
+    // advance is the most recent one open, so `next` undoes it whatever came before.
+    const latestStep = offsetChangeAt(latest).step;
+    const nextStep = next.offsetNanoseconds - zoned.offsetNanoseconds;
+    if (latestStep > 0 && nextStep === -latestStep) {
+        return true;
+    }
+    const open = openAdvancesBefore(next, latest);
+    if (open === null || open.length === 0) {
+        return false;
+    }
+    return isUndoneFrom(next, open, at);
+}
+/**
+ * Whether a zone observes daylight saving time as of an instant: the instant is in daylight time,
+ * or a daylight period begins within the 365 days after it. Same rule as `isInDaylightTime`.
+ *
+ * @param zoned the instant to judge from, in the zone to read
+ * @returns true when the zone observes daylight time then, false otherwise or past the walk bound
+ */
+export function observesDaylightTime(zoned) {
+    if (isInDaylightTime(zoned)) {
+        return true;
+    }
+    let cursor = zoned;
+    for (let i = 0; i <= MAX_WALKED_CHANGES; i++) {
+        const next = zonedNextTransition(cursor, zoned.epochNanoseconds + DAYLIGHT_PERIOD_LIMIT_NANOSECONDS);
+        if (next === null ||
+            next.epochNanoseconds - zoned.epochNanoseconds >=
+                DAYLIGHT_PERIOD_LIMIT_NANOSECONDS) {
+            return false;
+        }
+        if (isInDaylightTime(next)) {
+            return true;
+        }
+        cursor = next;
+    }
+    return false;
+}

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 {};