@northguild/gmt 1.18.0 → 1.19.0

package/dist/internal/utcWallClock.js

@@ -0,0 +1,32 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../utc/validate/isValidUtc.js";
+import { frameWallClock, normalizeZoneFrame } from "./zoneFrame.js";
+/**
+ * Read a UTC ISO string on a local wall clock for the `parse*FromUtc` accessors: the instant it
+ * names, on the wall clock of `options.timeZone`. The utc twin of `unixWallClock`.
+ *
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value UTC ISO 8601 datetime string
+ * @param options optional `{ timeZone }`
+ * @returns the local wall clock, or null when the value or the zone is invalid
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00"
+ * @example utcWallClock("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
+ * @example utcWallClock("2024-03-15T14:30:00") // null (no Z)
+ */
+export function utcWallClock(value, options) {
+    if (!isValidUtc(value))
+        return null;
+    const frame = normalizeZoneFrame(options?.timeZone);
+    if (frame === null)
+        return null;
+    try {
+        return frameWallClock(Temporal.Instant.from(value), frame);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/yearWindowStart.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve `TwoDigitYearOptions.yearWindow` to the first year of a hundred-year window, or null
+ * when the option is absent or not one of its two forms.
+ *
+ * - An integer from 0 to 9900 is a fixed window starting in that year.
+ * - `"rolling"` (exact match) is the hundred years around today: 50 years before the current UTC
+ *   calendar year to 49 after it. The year is read once, from
+ *   `Temporal.Now.instant().toZonedDateTimeISO("UTC").year`, so the window moves at the UTC new
+ *   year, not mid-year: year granularity is a **GMT rule**. RFC 9110 §5.6.7 applies the same
+ *   50-year idea to an `rfc850-date` two-digit year, at day granularity; `internal/httpDateFields.ts`
+ *   implements that rule for HTTP dates and is not affected by this one.
+ * - Anything else (a non-integer, a negative, 9901, `NaN`, `Infinity`, a numeric string, any
+ *   other string, `null`) is null. Whether a null window matters is the caller's: a value with no
+ *   two-digit year needs none.
+ *
+ * `options` is read as an Object the way Temporal's GetOptionsObject reads one (a function is an
+ * Object); a non-Object yields null here, and the public function has already returned its
+ * sentinel for one by `isOptionsArgument`.
+ *
+ * @param options the caller's options bag
+ * @returns the window's first year, or null
+ *
+ * @example readYearWindowStart({ yearWindow: 1950 }) // 1950
+ * @example readYearWindowStart({ yearWindow: "rolling" }) // 1976 (in 2026)
+ * @example readYearWindowStart({}) // null
+ * @example readYearWindowStart({ yearWindow: 9901 }) // null
+ */
+export declare function readYearWindowStart(options: unknown): number | null;

package/dist/internal/yearWindowStart.js

@@ -0,0 +1,52 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isObject } from "./isObject.js";
+/** `TwoDigitYearOptions.yearWindow` as a number: the first year of the window, 0–9900. */
+const MIN_YEAR_WINDOW_START = 0;
+/** The highest start whose every year, start + 99, is still a four-digit ISO year. */
+const MAX_YEAR_WINDOW_START = 9900;
+/** A rolling window starts this many years before the current UTC calendar year. */
+const ROLLING_YEARS_BEFORE_NOW = 50;
+/**
+ * Resolve `TwoDigitYearOptions.yearWindow` to the first year of a hundred-year window, or null
+ * when the option is absent or not one of its two forms.
+ *
+ * - An integer from 0 to 9900 is a fixed window starting in that year.
+ * - `"rolling"` (exact match) is the hundred years around today: 50 years before the current UTC
+ *   calendar year to 49 after it. The year is read once, from
+ *   `Temporal.Now.instant().toZonedDateTimeISO("UTC").year`, so the window moves at the UTC new
+ *   year, not mid-year: year granularity is a **GMT rule**. RFC 9110 §5.6.7 applies the same
+ *   50-year idea to an `rfc850-date` two-digit year, at day granularity; `internal/httpDateFields.ts`
+ *   implements that rule for HTTP dates and is not affected by this one.
+ * - Anything else (a non-integer, a negative, 9901, `NaN`, `Infinity`, a numeric string, any
+ *   other string, `null`) is null. Whether a null window matters is the caller's: a value with no
+ *   two-digit year needs none.
+ *
+ * `options` is read as an Object the way Temporal's GetOptionsObject reads one (a function is an
+ * Object); a non-Object yields null here, and the public function has already returned its
+ * sentinel for one by `isOptionsArgument`.
+ *
+ * @param options the caller's options bag
+ * @returns the window's first year, or null
+ *
+ * @example readYearWindowStart({ yearWindow: 1950 }) // 1950
+ * @example readYearWindowStart({ yearWindow: "rolling" }) // 1976 (in 2026)
+ * @example readYearWindowStart({}) // null
+ * @example readYearWindowStart({ yearWindow: 9901 }) // null
+ */
+export function readYearWindowStart(options) {
+    if (!isObject(options)) {
+        return null;
+    }
+    const { yearWindow } = options;
+    if (yearWindow === "rolling") {
+        return (Temporal.Now.instant().toZonedDateTimeISO("UTC").year -
+            ROLLING_YEARS_BEFORE_NOW);
+    }
+    if (typeof yearWindow === "number" &&
+        Number.isInteger(yearWindow) &&
+        yearWindow >= MIN_YEAR_WINDOW_START &&
+        yearWindow <= MAX_YEAR_WINDOW_START) {
+        return yearWindow;
+    }
+    return null;
+}

package/dist/internal/zoneBucketCap.d.ts

@@ -0,0 +1,18 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { ZoneBucketUnit } from "../types/index.js";
+/**
+ * True when `[start, end)` certainly touches more than `max` buckets of `unit`, decided from the span
+ * instead of stepping bucket by bucket (which costs milliseconds a step in some zones).
+ *
+ * Over a prefix of the range, the local wall clock runs continuously between offset transitions.
+ * Those stretches cover at least the prefix's length less every backward offset change, in at most
+ * one stretch more than there are transitions, and each stretch of wall clock holds at least
+ * `floor(length / LONGEST_UNIT_NANOSECONDS)` distinct unit starts, each the start of its own
+ * bucket before `end`. The count subtracts two per stretch for the partial units at its ends.
+ * The bound also holds for a count of distinct local dates, which the free-time walk keeps by
+ * folding a day that re-enters an earlier date: a date can re-enter only at an offset transition,
+ * where the two units dropped per stretch already sit, and the starts counted inside one stretch
+ * fall on strictly increasing dates.
+ * `false` means "not certain": the walk decides, exactly as before.
+ */
+export declare function certainlyTouchesMoreBuckets(startZoned: Temporal.ZonedDateTime, endZoned: Temporal.ZonedDateTime, unit: ZoneBucketUnit, max: number): boolean;

package/dist/internal/zoneBucketCap.js

@@ -0,0 +1,64 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { zonedNextTransition } from "./zonedWallClockOperations.js";
+/**
+ * A bounded walk over a zone's local buckets (hours, days, weeks, months) can refuse a span that is
+ * certainly too long without stepping through it. `bucketRange` refuses a range past 10,000
+ * buckets this way, and the free-time walk a dwell past 10,000 local days. `false` always means
+ * "not certain": the caller walks, exactly as it would without this check, so no answer changes.
+ */
+const NANOSECONDS_PER_HOUR = 3600000000000n;
+/**
+ * The longest wall-clock stretch of each unit. Any wall-clock interval this long holds a unit
+ * start: an hour holds an hour start, 24 hours a midnight, 7 days a Monday, 31 days a first of
+ * the month.
+ */
+const LONGEST_UNIT_NANOSECONDS = {
+    hour: NANOSECONDS_PER_HOUR,
+    day: 24n * NANOSECONDS_PER_HOUR,
+    week: 168n * NANOSECONDS_PER_HOUR,
+    month: 744n * NANOSECONDS_PER_HOUR,
+};
+/** Offset transitions read before the pre-count gives up and leaves the answer to the walk. */
+const MAX_PRECOUNT_TRANSITIONS = 4_096;
+/**
+ * True when `[start, end)` certainly touches more than `max` buckets of `unit`, decided from the span
+ * instead of stepping bucket by bucket (which costs milliseconds a step in some zones).
+ *
+ * Over a prefix of the range, the local wall clock runs continuously between offset transitions.
+ * Those stretches cover at least the prefix's length less every backward offset change, in at most
+ * one stretch more than there are transitions, and each stretch of wall clock holds at least
+ * `floor(length / LONGEST_UNIT_NANOSECONDS)` distinct unit starts, each the start of its own
+ * bucket before `end`. The count subtracts two per stretch for the partial units at its ends.
+ * The bound also holds for a count of distinct local dates, which the free-time walk keeps by
+ * folding a day that re-enters an earlier date: a date can re-enter only at an offset transition,
+ * where the two units dropped per stretch already sit, and the starts counted inside one stretch
+ * fall on strictly increasing dates.
+ * `false` means "not certain": the walk decides, exactly as before.
+ */
+export function certainlyTouchesMoreBuckets(startZoned, endZoned, unit, max) {
+    const unitNs = LONGEST_UNIT_NANOSECONDS[unit];
+    const startNs = startZoned.epochNanoseconds;
+    const prefixEndNs = [
+        endZoned.epochNanoseconds,
+        startNs + 2n * BigInt(max + 1) * unitNs,
+    ].reduce((a, b) => (a < b ? a : b));
+    if (prefixEndNs - startNs <= BigInt(max) * unitNs) {
+        return false;
+    }
+    let backwardNs = 0n;
+    let transitions = 0;
+    try {
+        for (let current = startZoned, next = zonedNextTransition(current); next !== null && next.epochNanoseconds < prefixEndNs; current = next, next = zonedNextTransition(current)) {
+            if (++transitions > MAX_PRECOUNT_TRANSITIONS) {
+                return false;
+            }
+            const shift = BigInt(current.offsetNanoseconds - next.offsetNanoseconds);
+            backwardNs += shift > 0n ? shift : 0n;
+        }
+    }
+    catch {
+        return false;
+    }
+    const wallStarts = (prefixEndNs - startNs - backwardNs) / unitNs;
+    return wallStarts - 2n * BigInt(transitions + 1) > BigInt(max);
+}

package/dist/internal/zoneFrame.d.ts

@@ -0,0 +1,180 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * How local time is read for a time zone argument: a Temporal time zone, plus the part of a stored
+ * UTC offset no time zone identifier can carry.
+ *
+ * A time zone identifier stops at minutes (TC39 Temporal §13.31, the RFC 9557 / ISO 8601 grammar:
+ * `TimeZoneIdentifier ::: UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`), but a zone's real
+ * offset does not: `Africa/Monrovia` stood at `-00:44:30` until 1972, and `getTimeZoneOffset`
+ * returns it. A fixed offset is still a complete rule for local time, so a function whose result
+ * names no zone reads one at any precision.
+ *
+ * The real offset is the offset of `timeZone` plus `shiftNanoseconds`. One frame serves a whole
+ * call, so every value of the call is placed in the same zone.
+ */
+export type ZoneFrame = {
+    /**
+     * A Temporal time zone identifier. For an offset with seconds it is the offset's whole minutes
+     * (`-00:44` for `-00:44:30`, `+02:10` for `+02:10:08`, `+00:00` within a minute of zero).
+     */
+    timeZone: string;
+    /**
+     * `0n`, or the seconds the real offset has beyond the offset of `timeZone`, in nanoseconds:
+     * under a minute, with the offset's own sign (east positive).
+     */
+    shiftNanoseconds: bigint;
+};
+/**
+ * Read a time zone argument that may also be a stored UTC offset.
+ *
+ * The only place that turns "time zone identifier or stored offset" into something Temporal can
+ * use. It accepts exactly what `isValidTimeZone` or `isValidUtcOffset` accepts, by five rules in
+ * order:
+ *
+ * 1. Not a string: null.
+ * 2. A time zone identifier (`isValidTimeZone`): that identifier as written, no shift. Every
+ *    argument that was valid before stored offsets were read takes this branch.
+ * 3. Not a stored offset (`±HH:MM[:SS]`): null.
+ * 4. A whole number of minutes (`+05:30:00`): the identifier it canonicalises to (`+05:30`), no
+ *    shift.
+ * 5. Otherwise (`-00:44:30`): the offset's whole minutes as the zone (`-00:44`), shifted by its
+ *    seconds with the offset's own sign (30 seconds further west).
+ *
+ * - The returned `timeZone` is always a time zone identifier, so it is safe in a bracket or in
+ *   `Intl.DateTimeFormat`. A seconds offset never becomes one: a caller that writes the zone into
+ *   its result validates with `isValidTimeZone` instead and does not call this.
+ *
+ * @param zone the caller's time zone argument
+ * @returns the frame, or null when `zone` is neither a time zone identifier nor a stored offset
+ *
+ * @example zoneFrame("America/New_York") // { timeZone: "America/New_York", shiftNanoseconds: 0n }
+ * @example zoneFrame("+05:30:00") // { timeZone: "+05:30", shiftNanoseconds: 0n }
+ * @example zoneFrame("-00:44:30") // { timeZone: "-00:44", shiftNanoseconds: -30000000000n }
+ * @example zoneFrame("Z") // null
+ */
+export declare function zoneFrame(zone: unknown): ZoneFrame | null;
+/**
+ * Read the `timeZone` option of a `unix/` or `utc/` function whose result names no zone.
+ *
+ * - Omitted (`undefined`) is `"UTC"`: an epoch and a UTC string name an instant, so no host zone
+ *   is read unless asked for.
+ * - `"local"` is the system time zone, or null when the host reports none that is valid.
+ * - Anything else is read by `zoneFrame`.
+ *
+ * `normalizeTimeZone` is the twin for a function that writes the zone into its result or hands it
+ * to `Intl.DateTimeFormat`: it accepts a time zone identifier only.
+ *
+ * @param option the caller's `timeZone` option
+ * @returns the frame, or null when the option is invalid
+ *
+ * @example normalizeZoneFrame(undefined) // { timeZone: "UTC", shiftNanoseconds: 0n }
+ * @example normalizeZoneFrame("local") // the system zone, e.g. { timeZone: "America/New_York", shiftNanoseconds: 0n }
+ * @example normalizeZoneFrame("-00:44:30") // { timeZone: "-00:44", shiftNanoseconds: -30000000000n }
+ * @example normalizeZoneFrame("America/New_Yrok") // null
+ */
+export declare function normalizeZoneFrame(option?: unknown): ZoneFrame | null;
+/**
+ * Read an instant on a frame's local wall clock. For a function that only reads fields.
+ *
+ * - A seconds offset is read with `wallClockAtOffset`, which is exact up to both limits of the
+ *   instant range; `frameZoned` is not.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param frame the frame from `zoneFrame`
+ * @returns the local wall clock
+ *
+ * @example frameWallClock(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")).toString() // "1970-01-01T12:00:00"
+ */
+export declare function frameWallClock(instant: Temporal.Instant, frame: ZoneFrame): Temporal.PlainDateTime;
+/**
+ * Read the current instant on a frame's local wall clock.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param frame the frame from `zoneFrame`
+ * @returns the local wall clock now
+ *
+ * @example frameNowWallClock(zoneFrame("-00:44:30")).toPlainDate().toString() // today's date at -00:44:30
+ */
+export declare function frameNowWallClock(frame: ZoneFrame): Temporal.PlainDateTime;
+/**
+ * Place an instant on a frame's local clock as a `Temporal.ZonedDateTime`, for a body that does
+ * arithmetic on one.
+ *
+ * - For a seconds offset the value sits in the frame's minute zone, at the instant plus the
+ *   shift, so its wall clock is the real local one. At a constant offset, arithmetic on the wall
+ *   clock is the same in any fixed-offset zone, and a day is always 24 hours. Its own
+ *   `epochNanoseconds`, `offset` and `timeZoneId` are not the real ones: turn a result back with
+ *   `frameInstant`, and never write it as a string.
+ * - Every value of one call is placed with the same frame, so all of them sit in one zone and
+ *   are off by the same shift. Comparing their `epochNanoseconds`, and `until` between them, give
+ *   what the real instants give.
+ * - Throws `RangeError` when the instant plus the shift is outside the instant range: within the
+ *   shift's length, under a minute, of the last instant for an offset east of UTC, and of the
+ *   first for one west. The caller returns its sentinel there, and its JSDoc says so. A function
+ *   that only reads fields uses `frameWallClock`, which has no such edge.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param frame the frame from `zoneFrame`
+ * @returns the zoned date-time to compute with
+ *
+ * @example frameInstant(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")).startOfDay(), zoneFrame("-00:44:30")).toString() // "1970-01-01T00:44:30Z"
+ */
+export declare function frameZoned(instant: Temporal.Instant, frame: ZoneFrame): Temporal.ZonedDateTime;
+/**
+ * The real epoch nanoseconds of a value `frameZoned` produced, or one computed from it.
+ *
+ * @param zoned a zoned date-time on the frame's local clock
+ * @param frame the frame it was placed on
+ * @returns epoch nanoseconds of the instant it names
+ *
+ * @example frameEpochNanoseconds(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")), zoneFrame("-00:44:30")) // 45870000000000n
+ */
+export declare function frameEpochNanoseconds(zoned: Temporal.ZonedDateTime, frame: ZoneFrame): bigint;
+/**
+ * The real instant of a value `frameZoned` produced, or one computed from it.
+ *
+ * Throws `RangeError` when the instant is outside Temporal's range; callers wrap it in their own
+ * try/catch.
+ *
+ * @param zoned a zoned date-time on the frame's local clock
+ * @param frame the frame it was placed on
+ * @returns the instant it names
+ *
+ * @example frameInstant(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")), zoneFrame("-00:44:30")).toString() // "1970-01-01T12:44:30Z"
+ */
+export declare function frameInstant(zoned: Temporal.ZonedDateTime, frame: ZoneFrame): Temporal.Instant;
+/**
+ * A frame's stored offset as text: `±HH:MM:SS` for a seconds offset.
+ *
+ * Throws `RangeError` for a frame with no shift, whose offset is its zone's to give; callers wrap
+ * it in their own try/catch.
+ *
+ * @param frame a frame whose `shiftNanoseconds` is not `0n`
+ * @returns the offset string
+ *
+ * @example frameOffset(zoneFrame("-00:44:30")) // "-00:44:30"
+ */
+export declare function frameOffset(frame: ZoneFrame): string;
+/**
+ * The instant a local wall time names at a frame's stored offset.
+ *
+ * The wall time and the offset are joined into one date-time string and read by Temporal, which
+ * reads an offset with seconds there (TC39 Temporal §13.31,
+ * `DateTimeUTCOffset[Z] ::: [+Z] UTCDesignator | UTCOffset[+SubMinutePrecision]`). A fixed offset has no
+ * transition, so the wall time is never repeated or skipped and there is nothing to disambiguate.
+ * Exact up to both limits of the instant range.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param wallClock an ISO 8601 `<date>T<time>` body with no offset and no annotation
+ * @param frame a frame whose `shiftNanoseconds` is not `0n`
+ * @returns the instant
+ *
+ * @example instantOfWallClock("1970-01-01T12:00:00", zoneFrame("-00:44:30")).toString() // "1970-01-01T12:44:30Z"
+ */
+export declare function instantOfWallClock(wallClock: string, frame: ZoneFrame): Temporal.Instant;

package/dist/internal/zoneFrame.js

@@ -0,0 +1,221 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getSystemTimeZone } from "../zoned/get/getSystemTimeZone.js";
+import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
+import { instantFrom } from "./instantNanoseconds.js";
+import { formatUtcOffset, parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
+import { wallClockAtOffset } from "./wallClockAtOffset.js";
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+/**
+ * Read a time zone argument that may also be a stored UTC offset.
+ *
+ * The only place that turns "time zone identifier or stored offset" into something Temporal can
+ * use. It accepts exactly what `isValidTimeZone` or `isValidUtcOffset` accepts, by five rules in
+ * order:
+ *
+ * 1. Not a string: null.
+ * 2. A time zone identifier (`isValidTimeZone`): that identifier as written, no shift. Every
+ *    argument that was valid before stored offsets were read takes this branch.
+ * 3. Not a stored offset (`±HH:MM[:SS]`): null.
+ * 4. A whole number of minutes (`+05:30:00`): the identifier it canonicalises to (`+05:30`), no
+ *    shift.
+ * 5. Otherwise (`-00:44:30`): the offset's whole minutes as the zone (`-00:44`), shifted by its
+ *    seconds with the offset's own sign (30 seconds further west).
+ *
+ * - The returned `timeZone` is always a time zone identifier, so it is safe in a bracket or in
+ *   `Intl.DateTimeFormat`. A seconds offset never becomes one: a caller that writes the zone into
+ *   its result validates with `isValidTimeZone` instead and does not call this.
+ *
+ * @param zone the caller's time zone argument
+ * @returns the frame, or null when `zone` is neither a time zone identifier nor a stored offset
+ *
+ * @example zoneFrame("America/New_York") // { timeZone: "America/New_York", shiftNanoseconds: 0n }
+ * @example zoneFrame("+05:30:00") // { timeZone: "+05:30", shiftNanoseconds: 0n }
+ * @example zoneFrame("-00:44:30") // { timeZone: "-00:44", shiftNanoseconds: -30000000000n }
+ * @example zoneFrame("Z") // null
+ */
+export function zoneFrame(zone) {
+    if (typeof zone !== "string") {
+        return null;
+    }
+    if (isValidTimeZone(zone)) {
+        return { timeZone: zone, shiftNanoseconds: 0n };
+    }
+    const offsetNanoseconds = parseUtcOffsetNanoseconds(zone);
+    if (offsetNanoseconds === null) {
+        return null;
+    }
+    // BigInt remainder keeps the dividend's sign, so this is the offset's seconds with its sign,
+    // and what is left is its whole minutes: the minute offset between it and zero.
+    const shiftNanoseconds = offsetNanoseconds % NANOSECONDS_PER_MINUTE;
+    const timeZone = formatUtcOffset(offsetNanoseconds - shiftNanoseconds);
+    return timeZone === null ? null : { timeZone, shiftNanoseconds };
+}
+/** The real offset of a frame with a shift: its minute zone's offset plus the shift. */
+function frameOffsetNanoseconds(frame) {
+    // The zone of a shifted frame is one `zoneFrame` wrote with `formatUtcOffset`, so it reads back.
+    const zoneOffset = parseUtcOffsetNanoseconds(frame.timeZone);
+    if (frame.shiftNanoseconds === 0n || zoneOffset === null) {
+        throw new RangeError("the frame carries no stored offset");
+    }
+    return zoneOffset + frame.shiftNanoseconds;
+}
+/**
+ * Read the `timeZone` option of a `unix/` or `utc/` function whose result names no zone.
+ *
+ * - Omitted (`undefined`) is `"UTC"`: an epoch and a UTC string name an instant, so no host zone
+ *   is read unless asked for.
+ * - `"local"` is the system time zone, or null when the host reports none that is valid.
+ * - Anything else is read by `zoneFrame`.
+ *
+ * `normalizeTimeZone` is the twin for a function that writes the zone into its result or hands it
+ * to `Intl.DateTimeFormat`: it accepts a time zone identifier only.
+ *
+ * @param option the caller's `timeZone` option
+ * @returns the frame, or null when the option is invalid
+ *
+ * @example normalizeZoneFrame(undefined) // { timeZone: "UTC", shiftNanoseconds: 0n }
+ * @example normalizeZoneFrame("local") // the system zone, e.g. { timeZone: "America/New_York", shiftNanoseconds: 0n }
+ * @example normalizeZoneFrame("-00:44:30") // { timeZone: "-00:44", shiftNanoseconds: -30000000000n }
+ * @example normalizeZoneFrame("America/New_Yrok") // null
+ */
+export function normalizeZoneFrame(option) {
+    if (option === undefined) {
+        return { timeZone: "UTC", shiftNanoseconds: 0n };
+    }
+    return zoneFrame(option === "local" ? getSystemTimeZone() : option);
+}
+/**
+ * Read an instant on a frame's local wall clock. For a function that only reads fields.
+ *
+ * - A seconds offset is read with `wallClockAtOffset`, which is exact up to both limits of the
+ *   instant range; `frameZoned` is not.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param frame the frame from `zoneFrame`
+ * @returns the local wall clock
+ *
+ * @example frameWallClock(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")).toString() // "1970-01-01T12:00:00"
+ */
+export function frameWallClock(instant, frame) {
+    return frame.shiftNanoseconds === 0n
+        ? instant.toZonedDateTimeISO(frame.timeZone).toPlainDateTime()
+        : wallClockAtOffset(instant, frameOffsetNanoseconds(frame));
+}
+/**
+ * Read the current instant on a frame's local wall clock.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param frame the frame from `zoneFrame`
+ * @returns the local wall clock now
+ *
+ * @example frameNowWallClock(zoneFrame("-00:44:30")).toPlainDate().toString() // today's date at -00:44:30
+ */
+export function frameNowWallClock(frame) {
+    return frame.shiftNanoseconds === 0n
+        ? Temporal.Now.zonedDateTimeISO(frame.timeZone).toPlainDateTime()
+        : wallClockAtOffset(Temporal.Now.instant(), frameOffsetNanoseconds(frame));
+}
+/**
+ * Place an instant on a frame's local clock as a `Temporal.ZonedDateTime`, for a body that does
+ * arithmetic on one.
+ *
+ * - For a seconds offset the value sits in the frame's minute zone, at the instant plus the
+ *   shift, so its wall clock is the real local one. At a constant offset, arithmetic on the wall
+ *   clock is the same in any fixed-offset zone, and a day is always 24 hours. Its own
+ *   `epochNanoseconds`, `offset` and `timeZoneId` are not the real ones: turn a result back with
+ *   `frameInstant`, and never write it as a string.
+ * - Every value of one call is placed with the same frame, so all of them sit in one zone and
+ *   are off by the same shift. Comparing their `epochNanoseconds`, and `until` between them, give
+ *   what the real instants give.
+ * - Throws `RangeError` when the instant plus the shift is outside the instant range: within the
+ *   shift's length, under a minute, of the last instant for an offset east of UTC, and of the
+ *   first for one west. The caller returns its sentinel there, and its JSDoc says so. A function
+ *   that only reads fields uses `frameWallClock`, which has no such edge.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param frame the frame from `zoneFrame`
+ * @returns the zoned date-time to compute with
+ *
+ * @example frameInstant(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")).startOfDay(), zoneFrame("-00:44:30")).toString() // "1970-01-01T00:44:30Z"
+ */
+export function frameZoned(instant, frame) {
+    return frame.shiftNanoseconds === 0n
+        ? instant.toZonedDateTimeISO(frame.timeZone)
+        : instant
+            .add({ nanoseconds: Number(frame.shiftNanoseconds) })
+            .toZonedDateTimeISO(frame.timeZone);
+}
+/**
+ * The real epoch nanoseconds of a value `frameZoned` produced, or one computed from it.
+ *
+ * @param zoned a zoned date-time on the frame's local clock
+ * @param frame the frame it was placed on
+ * @returns epoch nanoseconds of the instant it names
+ *
+ * @example frameEpochNanoseconds(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")), zoneFrame("-00:44:30")) // 45870000000000n
+ */
+export function frameEpochNanoseconds(zoned, frame) {
+    // The value was placed the shift later than its instant, so that the minute zone's wall clock
+    // is the real local one: local time = instant + offset (TC39 Temporal GetISODateTimeFor).
+    return zoned.epochNanoseconds - frame.shiftNanoseconds;
+}
+/**
+ * The real instant of a value `frameZoned` produced, or one computed from it.
+ *
+ * Throws `RangeError` when the instant is outside Temporal's range; callers wrap it in their own
+ * try/catch.
+ *
+ * @param zoned a zoned date-time on the frame's local clock
+ * @param frame the frame it was placed on
+ * @returns the instant it names
+ *
+ * @example frameInstant(frameZoned(Temporal.Instant.from("1970-01-01T12:44:30Z"), zoneFrame("-00:44:30")), zoneFrame("-00:44:30")).toString() // "1970-01-01T12:44:30Z"
+ */
+export function frameInstant(zoned, frame) {
+    return frame.shiftNanoseconds === 0n
+        ? zoned.toInstant()
+        : Temporal.Instant.fromEpochNanoseconds(frameEpochNanoseconds(zoned, frame));
+}
+/**
+ * A frame's stored offset as text: `±HH:MM:SS` for a seconds offset.
+ *
+ * Throws `RangeError` for a frame with no shift, whose offset is its zone's to give; callers wrap
+ * it in their own try/catch.
+ *
+ * @param frame a frame whose `shiftNanoseconds` is not `0n`
+ * @returns the offset string
+ *
+ * @example frameOffset(zoneFrame("-00:44:30")) // "-00:44:30"
+ */
+export function frameOffset(frame) {
+    const offset = formatUtcOffset(frameOffsetNanoseconds(frame));
+    if (offset === null) {
+        throw new RangeError("the frame carries no stored offset");
+    }
+    return offset;
+}
+/**
+ * The instant a local wall time names at a frame's stored offset.
+ *
+ * The wall time and the offset are joined into one date-time string and read by Temporal, which
+ * reads an offset with seconds there (TC39 Temporal §13.31,
+ * `DateTimeUTCOffset[Z] ::: [+Z] UTCDesignator | UTCOffset[+SubMinutePrecision]`). A fixed offset has no
+ * transition, so the wall time is never repeated or skipped and there is nothing to disambiguate.
+ * Exact up to both limits of the instant range.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param wallClock an ISO 8601 `<date>T<time>` body with no offset and no annotation
+ * @param frame a frame whose `shiftNanoseconds` is not `0n`
+ * @returns the instant
+ *
+ * @example instantOfWallClock("1970-01-01T12:00:00", zoneFrame("-00:44:30")).toString() // "1970-01-01T12:44:30Z"
+ */
+export function instantOfWallClock(wallClock, frame) {
+    return instantFrom(`${wallClock}${frameOffset(frame)}`);
+}

package/dist/internal/zonedNowUnitValue.d.ts

@@ -1,11 +1,13 @@
 import { Temporal } from "@js-temporal/polyfill";
 /**
  * One field of a zoned "now" as the `get*NowUnit` accessors return it: zero-padded to two digits
- * (three for sub-second fields), the year and day of week unpadded. The week number is the
+ * (three for sub-second fields), the day of week unpadded, and the year as Temporal writes one
+ * (`isoYearString`: four digits, or a sign and six outside 0000–9999). The week number is the
  * caller's, since the plain and zoned accessors read it through `parseWeekFromDate` and the utc and
  * unix ones from the ISO date.
  *
- * @param now the current moment on the wall clock being read
+ * @param now the current moment on the wall clock being read: a zoned date-time, or the plain wall
+ *   clock of a stored UTC offset with seconds, which no time zone identifier can carry
  * @param unit a singular unit, `dayOfWeek` included (already validated by the caller)
  * @param week the week number for `now`, as a string
  * @returns the field, or "" for any other unit
@@ -13,11 +15,12 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example zonedNowUnitValue(Temporal.ZonedDateTime.from("2024-03-05T07:08:09+00:00[UTC]"), "week", () => "10") // "10"
  * @example zonedNowUnitValue(Temporal.ZonedDateTime.from("2024-03-05T07:08:09+00:00[UTC]"), "quarter", () => "10") // ""
  */
-export declare function zonedNowUnitValue(now: Temporal.ZonedDateTime, unit: string | null | undefined, week: (now: Temporal.ZonedDateTime) => string): string;
+export declare function zonedNowUnitValue<Clock extends Temporal.ZonedDateTime | Temporal.PlainDateTime>(now: Clock, unit: string | null | undefined, week: (now: Clock) => string): string;
 /**
  * The ISO 8601 week number of `now`'s date, the week the utc and unix `get*NowUnit` accessors read.
  *
- * @param now the current moment on the wall clock being read
+ * @param now the current moment on the wall clock being read: a zoned date-time, or the plain wall
+ *   clock of a stored UTC offset with seconds, which no time zone identifier can carry
  * @returns the week number as a string
  * @example isoWeekOfYear(Temporal.ZonedDateTime.from("2024-12-30T00:00:00+00:00[UTC]")) // "1"
  */