@northguild/gmt 1.17.0 → 1.18.0

package/dist/internal/instantNanoseconds.d.ts

@@ -1,16 +1,62 @@
+import { Temporal } from "@js-temporal/polyfill";
 /**
  * Parse an ISO 8601 instant string to epoch nanoseconds, or `null` when it is not one.
  *
- * The single definition of "an instant string GMT accepts": the RFC 9557 instant grammar
- * `Temporal.Instant.from` parses, restricted to ISO 8601 extended format before the first `[`
- * (`instantBody`: `<date>T<time>`, then `Z` or `±HH:MM[:SS[.fraction]]`), minus
- * leap seconds (which Temporal clamps rather than rejects). Basic format, a space or lower-case
- * `t` separator, a lower-case `z` and an hour-only time or offset are rejected. Annotations are read as Temporal reads them (proposal-temporal
+ * The single definition of "an instant string GMT accepts", and of the instant it names. Every
+ * GMT function that reads a moment without keeping its zone reads through here.
+ *
+ * **Which strings.** The RFC 9557 instant grammar `Temporal.Instant.from` parses, restricted to
+ * ISO 8601 extended format before the first `[` (`instantBody`: `<date>T<time>`, then `Z` or
+ * `±HH:MM[:SS[.fraction]]`), minus leap seconds (which Temporal clamps rather than rejects).
+ * Basic format, a space or lower-case `t` separator, a lower-case `z` and an hour-only time or
+ * offset are rejected. Annotations are read as Temporal reads them (proposal-temporal
  * `ParseISODateTime`, RFC 9557 §3.3): a time zone, calendar (`[u-ca=hebrew]`) or elective
- * (`[foo=bar]`) annotation is ignored, because an instant has neither zone nor calendar, and an
- * unknown critical one (`[!foo=bar]`) is rejected. Callers layer their own sentinel on top —
- * `toNanoseconds` returns `0n`, `spanNs` returns `null` — so the parse result stays unambiguous
- * here.
+ * (`[foo=bar]`) annotation never makes a string invalid, and an unknown critical one
+ * (`[!foo=bar]`) is rejected.
+ *
+ * **Which instant.** The written offset fixes it, as in `Temporal.Instant.from`, with one
+ * exception:
+ *
+ * - **A minute-rounded offset is read as its zone's real offset.** When the string has a
+ *   bracketed zone and an offset written to the minute, and that offset is the zone's actual
+ *   offset at that wall time rounded to the minute, the instant is the one the zone gives. This
+ *   is TC39 `ToTemporalZonedDateTime`'s match-minutes rule (`InterpretISODateTimeOffset`),
+ *   applied to the zone and the offset alone. It exists because
+ *   `Temporal.ZonedDateTime.prototype.toString` writes the offset rounded to the minute: in a
+ *   zone with a sub-minute offset (`Africa/Monrovia` before 1972, at −00:44:30, written
+ *   `-00:45`), the string a zoned function writes would otherwise be read up to 30 seconds off.
+ * - **The instant range is the only range.** The match has no `CheckISODaysRange` on the local
+ *   date, which `Temporal.ZonedDateTime.from` has, and does not need the written offset's own
+ *   reading to be in range. So every string Temporal writes for an instant in range is read
+ *   back, the first and last instants included: `-271821-04-19T23:58:45-00:01[Europe/London]`
+ *   (London's local mean time, −00:01:15) is the first instant, although its local date is
+ *   outside Temporal's date range and its reading at −00:01 is 15 seconds before the range.
+ * - **A repeated wall time inside a sub-minute offset change reads as its first pass.** The
+ *   match is against each candidate instant in order, so when a wall time happened twice and
+ *   the rounded offset fits the first pass, the first pass is the answer, even if the string
+ *   was written for the second. This is a class of strings, not one zone: it arises wherever a
+ *   zone's history has a fall-back of under a minute at a sub-minute offset. The example
+ *   test262 uses: Pacific/Niue moved from −11:19:40 to −11:20:00 at the end of
+ *   15 October 1952, so 23:59:40 to 23:59:59 happened twice, 20 seconds apart, and both passes
+ *   are written `-11:20`: `1952-10-15T23:59:59-11:20[Pacific/Niue]` reads as the pass at
+ *   −11:19:40. This is `Temporal.ZonedDateTime.from`'s own reading (test262
+ *   `intl402/Temporal/ZonedDateTime/from/zoneddatetime-sub-minute-offset.js`), and the one kind
+ *   of string Temporal writes that an instant reader does not read as the instant it was
+ *   written for. The exact offset, `-11:20:00`, names the second pass.
+ * - **Everything else keeps the written offset.** The complete list: a string without a
+ *   bracket; a `Z` instant; an offset written with seconds, which TC39 matches exactly
+ *   (`-00:45:00[Africa/Monrovia]` is −00:45:00); a bracket whose zone does not exist; and a
+ *   bracket whose zone has no instant in range with that wall time at the written offset or at
+ *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `-05:00[America/New_York]` in
+ *   June). Such a bracket is not validated here; a function that keeps the zone
+ *   (`transitTime`, `toOffsetInstant`) rejects it instead. Calendar and elective annotations
+ *   never change the reading. A string whose written reading is outside the instant range, and
+ *   which the zone does not bring inside it, is `null`.
+ *
+ * The zone's offset comes from Temporal's time-zone data; nothing here holds an offset or a
+ * zone name. A string in a whole-minute zone costs two offset lookups more than
+ * `Temporal.Instant.from`. Callers layer their own sentinel on top — `toNanoseconds` returns
+ * `0n`, `spanNs` returns `null` — so the parse result stays unambiguous here.
  *
  * @param value candidate ISO 8601 instant string
  * @returns nanoseconds since the Unix epoch, or null when `value` is not a valid instant
@@ -21,5 +67,25 @@
  * @example parseInstantNanoseconds("20240310T120000Z") // null — basic format
  * @example parseInstantNanoseconds("2024-03-10T12:00:00z") // null — lower-case z
  * @example parseInstantNanoseconds("1970-01-01T00:00:00Z[u-ca=hebrew]") // 0n — calendar annotation ignored
+ * @example parseInstantNanoseconds("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // -315615330000000000n — 01:04:30Z: Monrovia stood at -00:44:30
+ * @example parseInstantNanoseconds("1960-01-01T00:20:00-00:45") // -315615300000000000n — 01:05:00Z: no zone, so the offset is exact
+ * @example parseInstantNanoseconds("1952-10-15T23:59:59-11:20[Pacific/Niue]") // -543069621000000000n — the first pass of a repeated second, at -11:19:40
+ * @example parseInstantNanoseconds("-271821-04-19T23:58:45-00:01[Europe/London]") // -8640000000000000000000n — the first instant, at London's -00:01:15
+ * @example parseInstantNanoseconds("2024-06-15T10:00:00Z[Not/AZone]") // 1718445600000000000n — the bracket is not validated
  */
 export declare function parseInstantNanoseconds(value: string): bigint | null;
+/**
+ * `parseInstantNanoseconds` as a `Temporal.Instant`, for callers that already hold a validated
+ * string and go on to Temporal arithmetic. Use it wherever a caller's instant string would
+ * otherwise go to `Temporal.Instant.from`, so a minute-rounded offset is read the same way
+ * everywhere. Throws where `Temporal.Instant.from` throws, so it sits inside the caller's `try`
+ * like any other Temporal parse.
+ *
+ * @param value ISO 8601 instant or zoned datetime string
+ * @returns the instant the string names
+ * @throws RangeError when `value` is not a valid instant
+ *
+ * @example instantFrom("1960-01-01T00:20:00-00:45[Africa/Monrovia]").toString() // "1960-01-01T01:04:30Z"
+ * @example instantFrom("2024-06-15T10:00:00") // throws RangeError
+ */
+export declare function instantFrom(value: string): Temporal.Instant;

package/dist/internal/instantNanoseconds.js

@@ -1,19 +1,83 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { instantLeapSecond } from "../regex/leap-second.js";
-import { hasInstantShape } from "./isoStringBody.js";
+import { hasInstantShape, isoStringBody } from "./isoStringBody.js";
+import { parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
+import { isValidEpoch, offsetAt, roundToMinute, utcEpochNanoseconds, } from "./zonedWallClock.js";
+/**
+ * The first time-zone annotation in the string, as `TIME_ZONE_ANNOTATION` defines one (a
+ * bracket without `=`), with its identifier captured without the critical flag. Only a string
+ * that names a zone can have a rounded offset to resolve. The capture goes to Temporal, which
+ * decides whether it is a zone.
+ */
+const zoneAnnotation = /\[!?([^\]=]+)\]/;
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+/** The most a minute-rounded offset can differ from the real one (half-expand rounding). */
+const HALF_MINUTE = 30000000000n;
+/** `±HH:MM`: the length of an offset written to the minute. */
+const MINUTE_OFFSET_LENGTH = 6;
+/**
+ * An instant body that ends in an offset written to the minute (`±HH:MM`), with no seconds
+ * part. The sign must sit directly before `HH:MM`, so `-04:56:02` does not match on its `56:02`.
+ */
+const minuteOffset = /[+-]\d{2}:\d{2}$/;
 /**
  * Parse an ISO 8601 instant string to epoch nanoseconds, or `null` when it is not one.
  *
- * The single definition of "an instant string GMT accepts": the RFC 9557 instant grammar
- * `Temporal.Instant.from` parses, restricted to ISO 8601 extended format before the first `[`
- * (`instantBody`: `<date>T<time>`, then `Z` or `±HH:MM[:SS[.fraction]]`), minus
- * leap seconds (which Temporal clamps rather than rejects). Basic format, a space or lower-case
- * `t` separator, a lower-case `z` and an hour-only time or offset are rejected. Annotations are read as Temporal reads them (proposal-temporal
+ * The single definition of "an instant string GMT accepts", and of the instant it names. Every
+ * GMT function that reads a moment without keeping its zone reads through here.
+ *
+ * **Which strings.** The RFC 9557 instant grammar `Temporal.Instant.from` parses, restricted to
+ * ISO 8601 extended format before the first `[` (`instantBody`: `<date>T<time>`, then `Z` or
+ * `±HH:MM[:SS[.fraction]]`), minus leap seconds (which Temporal clamps rather than rejects).
+ * Basic format, a space or lower-case `t` separator, a lower-case `z` and an hour-only time or
+ * offset are rejected. Annotations are read as Temporal reads them (proposal-temporal
  * `ParseISODateTime`, RFC 9557 §3.3): a time zone, calendar (`[u-ca=hebrew]`) or elective
- * (`[foo=bar]`) annotation is ignored, because an instant has neither zone nor calendar, and an
- * unknown critical one (`[!foo=bar]`) is rejected. Callers layer their own sentinel on top —
- * `toNanoseconds` returns `0n`, `spanNs` returns `null` — so the parse result stays unambiguous
- * here.
+ * (`[foo=bar]`) annotation never makes a string invalid, and an unknown critical one
+ * (`[!foo=bar]`) is rejected.
+ *
+ * **Which instant.** The written offset fixes it, as in `Temporal.Instant.from`, with one
+ * exception:
+ *
+ * - **A minute-rounded offset is read as its zone's real offset.** When the string has a
+ *   bracketed zone and an offset written to the minute, and that offset is the zone's actual
+ *   offset at that wall time rounded to the minute, the instant is the one the zone gives. This
+ *   is TC39 `ToTemporalZonedDateTime`'s match-minutes rule (`InterpretISODateTimeOffset`),
+ *   applied to the zone and the offset alone. It exists because
+ *   `Temporal.ZonedDateTime.prototype.toString` writes the offset rounded to the minute: in a
+ *   zone with a sub-minute offset (`Africa/Monrovia` before 1972, at −00:44:30, written
+ *   `-00:45`), the string a zoned function writes would otherwise be read up to 30 seconds off.
+ * - **The instant range is the only range.** The match has no `CheckISODaysRange` on the local
+ *   date, which `Temporal.ZonedDateTime.from` has, and does not need the written offset's own
+ *   reading to be in range. So every string Temporal writes for an instant in range is read
+ *   back, the first and last instants included: `-271821-04-19T23:58:45-00:01[Europe/London]`
+ *   (London's local mean time, −00:01:15) is the first instant, although its local date is
+ *   outside Temporal's date range and its reading at −00:01 is 15 seconds before the range.
+ * - **A repeated wall time inside a sub-minute offset change reads as its first pass.** The
+ *   match is against each candidate instant in order, so when a wall time happened twice and
+ *   the rounded offset fits the first pass, the first pass is the answer, even if the string
+ *   was written for the second. This is a class of strings, not one zone: it arises wherever a
+ *   zone's history has a fall-back of under a minute at a sub-minute offset. The example
+ *   test262 uses: Pacific/Niue moved from −11:19:40 to −11:20:00 at the end of
+ *   15 October 1952, so 23:59:40 to 23:59:59 happened twice, 20 seconds apart, and both passes
+ *   are written `-11:20`: `1952-10-15T23:59:59-11:20[Pacific/Niue]` reads as the pass at
+ *   −11:19:40. This is `Temporal.ZonedDateTime.from`'s own reading (test262
+ *   `intl402/Temporal/ZonedDateTime/from/zoneddatetime-sub-minute-offset.js`), and the one kind
+ *   of string Temporal writes that an instant reader does not read as the instant it was
+ *   written for. The exact offset, `-11:20:00`, names the second pass.
+ * - **Everything else keeps the written offset.** The complete list: a string without a
+ *   bracket; a `Z` instant; an offset written with seconds, which TC39 matches exactly
+ *   (`-00:45:00[Africa/Monrovia]` is −00:45:00); a bracket whose zone does not exist; and a
+ *   bracket whose zone has no instant in range with that wall time at the written offset or at
+ *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `-05:00[America/New_York]` in
+ *   June). Such a bracket is not validated here; a function that keeps the zone
+ *   (`transitTime`, `toOffsetInstant`) rejects it instead. Calendar and elective annotations
+ *   never change the reading. A string whose written reading is outside the instant range, and
+ *   which the zone does not bring inside it, is `null`.
+ *
+ * The zone's offset comes from Temporal's time-zone data; nothing here holds an offset or a
+ * zone name. A string in a whole-minute zone costs two offset lookups more than
+ * `Temporal.Instant.from`. Callers layer their own sentinel on top — `toNanoseconds` returns
+ * `0n`, `spanNs` returns `null` — so the parse result stays unambiguous here.
  *
  * @param value candidate ISO 8601 instant string
  * @returns nanoseconds since the Unix epoch, or null when `value` is not a valid instant
@@ -24,6 +88,11 @@ import { hasInstantShape } from "./isoStringBody.js";
  * @example parseInstantNanoseconds("20240310T120000Z") // null — basic format
  * @example parseInstantNanoseconds("2024-03-10T12:00:00z") // null — lower-case z
  * @example parseInstantNanoseconds("1970-01-01T00:00:00Z[u-ca=hebrew]") // 0n — calendar annotation ignored
+ * @example parseInstantNanoseconds("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // -315615330000000000n — 01:04:30Z: Monrovia stood at -00:44:30
+ * @example parseInstantNanoseconds("1960-01-01T00:20:00-00:45") // -315615300000000000n — 01:05:00Z: no zone, so the offset is exact
+ * @example parseInstantNanoseconds("1952-10-15T23:59:59-11:20[Pacific/Niue]") // -543069621000000000n — the first pass of a repeated second, at -11:19:40
+ * @example parseInstantNanoseconds("-271821-04-19T23:58:45-00:01[Europe/London]") // -8640000000000000000000n — the first instant, at London's -00:01:15
+ * @example parseInstantNanoseconds("2024-06-15T10:00:00Z[Not/AZone]") // 1718445600000000000n — the bracket is not validated
  */
 export function parseInstantNanoseconds(value) {
     if (typeof value !== "string") {
@@ -32,10 +101,122 @@ export function parseInstantNanoseconds(value) {
     if (instantLeapSecond.test(value) || !hasInstantShape(value)) {
         return null;
     }
+    let written;
+    try {
+        written = Temporal.Instant.from(value).epochNanoseconds;
+    }
+    catch {
+        // Not an instant as written. It may still be one through its zone: see `zonedReading`.
+        written = null;
+    }
+    const body = isoStringBody(value);
+    const zone = minuteOffset.test(body)
+        ? zoneAnnotation.exec(value)?.[1]
+        : undefined;
+    if (zone === undefined) {
+        return written;
+    }
     try {
-        return Temporal.Instant.from(value).epochNanoseconds;
+        return written === null
+            ? zonedReadingOutsideWrittenRange(value, body, zone)
+            : (zonedReading(zone, written, () => writtenOffset(body)) ?? written);
     }
     catch {
+        // The zone does not exist: the written offset stands.
+        return written;
+    }
+}
+/** The nanoseconds of the `±HH:MM` offset that ends `body`, parsed by Temporal. */
+function writtenOffset(body) {
+    return parseUtcOffsetNanoseconds(body.slice(-MINUTE_OFFSET_LENGTH));
+}
+/**
+ * TC39 `InterpretISODateTimeOffset`'s match for a minute-precision offset, on epoch nanoseconds:
+ * the instant `zone` gives a wall time written with `offset`, or `null` when the zone has no
+ * instant in range whose offset is `offset` or rounds to it.
+ *
+ * `written` is the wall time read at the written offset. A candidate instant has the same wall
+ * time at the zone's own offset, so it lies within half a minute of `written`, and the zone's
+ * offsets half a minute either side are the only ones a candidate can have. When both are whole
+ * minutes nothing can round, the written offset is never read, and the answer is `null`: the
+ * common case costs two offset lookups. Otherwise each candidate is checked against the zone and
+ * the earliest match wins, as the spec's loop over the possible instants does. It assumes a
+ * zone changes its offset at most once in any one minute.
+ *
+ * Unlike `Temporal.ZonedDateTime.from` this has no `CheckISODaysRange` on the local date: an
+ * instant is in range or it is not, whatever date its wall clock shows.
+ *
+ * @throws RangeError when `zone` is not a time zone
+ */
+function zonedReading(zone, written, offset) {
+    const before = offsetAt(zone, written - HALF_MINUTE);
+    const after = offsetAt(zone, written + HALF_MINUTE);
+    if (before % NANOSECONDS_PER_MINUTE === 0n &&
+        after % NANOSECONDS_PER_MINUTE === 0n) {
+        return null;
+    }
+    const writtenOffsetNanoseconds = offset();
+    if (writtenOffsetNanoseconds === null) {
+        return null;
+    }
+    // With one offset across the whole minute a candidate needs no second look at the zone: it
+    // lies inside that minute. Across a change, each side's candidate must fall on its own side.
+    const steady = before === after;
+    let earliest = null;
+    for (const candidateOffset of steady ? [before] : [before, after]) {
+        const candidate = written + writtenOffsetNanoseconds - candidateOffset;
+        if ((candidateOffset === writtenOffsetNanoseconds ||
+            roundToMinute(candidateOffset) === writtenOffsetNanoseconds) &&
+            isValidEpoch(candidate) &&
+            (steady || offsetAt(zone, candidate) === candidateOffset) &&
+            (earliest === null || candidate < earliest)) {
+            earliest = candidate;
+        }
+    }
+    return earliest;
+}
+/**
+ * `zonedReading` for a string `Temporal.Instant.from` refused. At the range limits the written,
+ * minute-rounded offset can put the literal reading just outside the instant range while the
+ * zone's real offset keeps the instant inside it: Europe/London at local mean time (−00:01:15)
+ * writes the first instant as `-271821-04-19T23:58:45-00:01`, 15 seconds before the range when
+ * read at −00:01. Temporal reads both halves again: the wall clock as a `PlainDateTime`, from
+ * the part before the first annotation, and the annotations on a stand-in instant, exactly as
+ * `Temporal.Instant.from` reads them (a calendar id is not checked). So every other reason the
+ * string was refused (an invalid date, an unknown critical annotation) is refused again here
+ * by the throw.
+ *
+ * @throws RangeError when the string is not a date-time, or `zone` is not a time zone
+ */
+function zonedReadingOutsideWrittenRange(value, body, zone) {
+    const offset = writtenOffset(body);
+    if (offset === null) {
         return null;
     }
+    // The annotations are read as an instant's are: on a stand-in instant, so an unknown critical
+    // annotation or a misplaced zone throws, and a calendar id is not checked.
+    Temporal.Instant.from(`1970-01-01T00:00:00Z${value.slice(body.length)}`);
+    const wall = Temporal.PlainDateTime.from(body);
+    return zonedReading(zone, utcEpochNanoseconds(wall) - offset, () => offset);
+}
+/**
+ * `parseInstantNanoseconds` as a `Temporal.Instant`, for callers that already hold a validated
+ * string and go on to Temporal arithmetic. Use it wherever a caller's instant string would
+ * otherwise go to `Temporal.Instant.from`, so a minute-rounded offset is read the same way
+ * everywhere. Throws where `Temporal.Instant.from` throws, so it sits inside the caller's `try`
+ * like any other Temporal parse.
+ *
+ * @param value ISO 8601 instant or zoned datetime string
+ * @returns the instant the string names
+ * @throws RangeError when `value` is not a valid instant
+ *
+ * @example instantFrom("1960-01-01T00:20:00-00:45[Africa/Monrovia]").toString() // "1960-01-01T01:04:30Z"
+ * @example instantFrom("2024-06-15T10:00:00") // throws RangeError
+ */
+export function instantFrom(value) {
+    const nanoseconds = parseInstantNanoseconds(value);
+    if (nanoseconds === null) {
+        throw new RangeError("Not an ISO 8601 instant string");
+    }
+    return Temporal.Instant.fromEpochNanoseconds(nanoseconds);
 }

package/dist/internal/joinDateTimeConnector.d.ts

@@ -34,4 +34,4 @@
  * @param timeStyle Intl.DateTimeFormatOptions `timeStyle` for the time half
  * @returns `dayLabel` joined to the localized time with the locale's own connector
  */
-export declare function joinDateTimeConnector(epochMilliseconds: number, timeZone: string, locale: string | string[] | undefined, dayLabel: string, timeStyle: "short" | "medium" | "full"): string;
+export declare function joinDateTimeConnector(epochMilliseconds: number, timeZone: string, locale: string | string[] | undefined, dayLabel: string, timeStyle: "short" | "medium" | "long" | "full"): string;

package/dist/internal/monthGridWeekRow.d.ts

@@ -7,7 +7,8 @@ import type { Temporal } from "@js-temporal/polyfill";
  * Shared by `getWeekOfMonth` (row for the date itself) and
  * `getWeeksInMonth` (row for the month's last day, i.e. the row count).
  * Week 1 is the row containing the 1st of the month, even when that row
- * is a partial week (date-fns's `getWeekOfMonth` convention).
+ * is a partial week: a month grid draws every day of the month, so its
+ * first row always holds the 1st. GMT's own rule; CLDR's `minDays` plays no part.
  *
  * Only the weekday of the 1st is read, so callers may pass `{ dayOfWeek }` without building a
  * date that could lie before the representable range (April 1 of -271821).

package/dist/internal/monthGridWeekRow.js

@@ -6,7 +6,8 @@
  * Shared by `getWeekOfMonth` (row for the date itself) and
  * `getWeeksInMonth` (row for the month's last day, i.e. the row count).
  * Week 1 is the row containing the 1st of the month, even when that row
- * is a partial week (date-fns's `getWeekOfMonth` convention).
+ * is a partial week: a month grid draws every day of the month, so its
+ * first row always holds the 1st. GMT's own rule; CLDR's `minDays` plays no part.
  *
  * Only the weekday of the 1st is read, so callers may pass `{ dayOfWeek }` without building a
  * date that could lie before the representable range (April 1 of -271821).

package/dist/internal/normalizeTimeZone.d.ts

@@ -1,11 +1,11 @@
 /**
- * Resolve the `timeZone` option of every `unix/` function and the `utc/` formatters.
+ * Resolve the `timeZone` option of every `unix/` and `utc/` function that takes one.
  *
  * - Omitted (`undefined`) → `"UTC"`. A Unix epoch and a UTC string name an instant, so no host
  *   zone is read unless asked for.
  * - `"local"` → the system time zone (`getSystemTimeZone()`), or `""` when the host reports none
  *   that is valid.
- * - A valid IANA identifier → returned as-is.
+ * - A valid IANA identifier or UTC offset (`"+05:30"`) → returned as-is.
  * - Anything else (`null`, `""`, a typo, a non-string) → `""`, the caller's cue to return its
  *   sentinel. ECMA-402 `Intl.DateTimeFormat` and Temporal `ToTemporalTimeZoneIdentifier` throw
  *   `RangeError` for an unknown zone, so a typo never silently renders UTC.

package/dist/internal/normalizeTimeZone.js

@@ -1,13 +1,13 @@
 import { getSystemTimeZone } from "../zoned/get/getSystemTimeZone.js";
 import { isValidTimeZone } from "../zoned/validate/index.js";
 /**
- * Resolve the `timeZone` option of every `unix/` function and the `utc/` formatters.
+ * Resolve the `timeZone` option of every `unix/` and `utc/` function that takes one.
  *
  * - Omitted (`undefined`) → `"UTC"`. A Unix epoch and a UTC string name an instant, so no host
  *   zone is read unless asked for.
  * - `"local"` → the system time zone (`getSystemTimeZone()`), or `""` when the host reports none
  *   that is valid.
- * - A valid IANA identifier → returned as-is.
+ * - A valid IANA identifier or UTC offset (`"+05:30"`) → returned as-is.
  * - Anything else (`null`, `""`, a typo, a non-string) → `""`, the caller's cue to return its
  *   sentinel. ECMA-402 `Intl.DateTimeFormat` and Temporal `ToTemporalTimeZoneIdentifier` throw
  *   `RangeError` for an unknown zone, so a typo never silently renders UTC.

package/dist/internal/operatingSchedule.d.ts

@@ -0,0 +1,129 @@
+import type { Disambiguation } from "../types/index.js";
+import { type IntervalNanoseconds } from "./intervalNanoseconds.js";
+/** A `LocalWindow` validated once: canonical PlainTime strings, and whether it wraps midnight. */
+export type ResolvedWindow = {
+    from: string;
+    to: string;
+    wraps: boolean;
+};
+/** An `OperatingSchedule` reduced to the lookups the day walk needs. */
+export type ResolvedSchedule = {
+    timeZone: string;
+    /** Windows by ISO weekday; index 0 is unused. */
+    weekly: readonly (readonly ResolvedWindow[])[];
+    holidays: ReadonlySet<string>;
+    overrides: ReadonlyMap<string, readonly ResolvedWindow[]>;
+};
+/**
+ * Local dates a range may span, counted from the date its start falls on: about 27 years, the
+ * same bound `bucketRange` puts on a day walk. A walk that runs out answers with the sentinel,
+ * never a partial list.
+ */
+export declare const MAX_SCHEDULE_DAYS = 10000;
+/**
+ * The search horizon of `nextOpenAt`, `nextCloseAt` and `addOperatingTime` when the caller
+ * gives no `within`: one calendar year in the schedule's zone.
+ */
+export declare const DEFAULT_OPERATING_HORIZON = "P1Y";
+/**
+ * Parse `OperatingSchedule['weekly']`: an object whose own keys are ISO weekdays `"1"`–`"7"`,
+ * each holding an array of `LocalWindow`s (or `undefined`, meaning closed). Any other key, or a
+ * malformed window, returns `null`.
+ */
+export declare function parseWeeklyPattern(value: unknown): ResolvedWindow[][] | null;
+/** Validate an `OperatingSchedule`, or `null` when any part of it is malformed. */
+export declare function parseOperatingSchedule(value: unknown): ResolvedSchedule | null;
+/**
+ * Read `disambiguation` from an options argument. Omitted means `"compatible"`, as in
+ * `resolveLocal`; anything but the four Temporal values, or an options argument that is not an
+ * object, returns `null`.
+ */
+export declare function parseScheduleDisambiguation(options: unknown): Disambiguation | null;
+/**
+ * The last instant a search may answer with: `from` plus `within` (default one year), added in
+ * the schedule's zone so `P1D` is one local day. It is clamped to the search cap: the last instant
+ * before the local date `MAX_SCHEDULE_DAYS + 1` after the one `from` falls on, so a search answers
+ * anywhere on the 10,000th date and nowhere after it. A horizon past Temporal's last instant is
+ * that instant, since nothing after it can be answered. `null` when `within` is not a
+ * non-negative ISO duration.
+ */
+export declare function parseSearchHorizon(fromNs: bigint, within: unknown, timeZone: string): bigint | null;
+/**
+ * What the walk tells its caller.
+ *
+ * - `run` is a finished open run: sorted, disjoint, non-touching and never extended later.
+ * - `day` announces that every window still to come starts at or after `bound`, and passes the
+ *   runs still `pending`: sorted and disjoint, each ending at or after `bound`, so a later window
+ *   may extend them but cannot add open time before `bound`. A caller can answer from them once
+ *   its answer lies at or before `bound`.
+ * - Returning `true` from either stops the walk; stopping from `day` hands the pending runs to
+ *   `run` first.
+ */
+export type ScheduleVisitor = {
+    run: (run: IntervalNanoseconds) => boolean;
+    day: (bound: bigint, pending: readonly IntervalNanoseconds[]) => boolean;
+};
+/**
+ * How a walk ended. `unresolvedStart` is the earliest instant a window rejected under
+ * `"reject"` could open at, among those that could still be open at or after `fromNs`;
+ * `undefined` when there is none. A rejected window on a date the walk did not reach starts at
+ * or after the last `bound` it announced.
+ */
+export type ScheduleWalk = {
+    unresolvedStart: bigint | undefined;
+};
+/**
+ * Walk the schedule's local dates from a little before `fromNs`, handing the visitor each open
+ * run as soon as no later window can extend it.
+ *
+ * - Dates come from the day buckets `floorToZone` and `bucketRange` use, so a deleted date
+ *   (`Pacific/Apia`, 2011-12-30) is never visited, and a date the clock re-enters after a
+ *   fall-back (`America/Goose_Bay`, 2010-11-06) is visited once.
+ * - A window can start as early as the previous date's first instant (see `resolveDateWindows`),
+ *   so the walk settles one date behind: once a date is resolved, the first instant of the date
+ *   resolved before it is the `bound` no later window starts before.
+ * - When the visitor stops the walk from `day`, or the last representable day is reached, the
+ *   runs still pending are handed over too.
+ * - Returns `null` when a day bucket could not be found, or the walk would resolve a date
+ *   `MAX_SCHEDULE_DAYS + 2` after the one `fromNs` falls on. Neither use reaches that: a range
+ *   is refused up front past `MAX_SCHEDULE_DAYS` dates, and a search's horizon ends with the
+ *   `MAX_SCHEDULE_DAYS`th date, so its walk stops by the horizon one date later.
+ */
+export declare function walkSchedule(schedule: ResolvedSchedule, fromNs: bigint, disambiguation: Disambiguation, visitor: ScheduleVisitor): ScheduleWalk | null;
+/**
+ * The schedule's open runs clipped to `[startNs, endNs)`, in the range's own strings where a run
+ * is clipped. `null` when the walk fails (see `walkSchedule`), or when a window rejected under
+ * `"reject"` reaches into the range.
+ */
+export declare function scheduleRunsWithin(schedule: ResolvedSchedule, range: IntervalNanoseconds, disambiguation: Disambiguation): IntervalNanoseconds[] | null;
+/**
+ * The first instant at or after `fromNs` that the schedule is open: `fromNs` itself inside an
+ * open run, else the start of the next run. Answered as soon as no later window can open
+ * sooner, without waiting for the run to close. `undefined` when none falls at or before
+ * `horizonNs`, `null` when the walk fails or a window rejected under `"reject"` could open
+ * sooner.
+ */
+export declare function firstOpenInstant(schedule: ResolvedSchedule, fromNs: bigint, horizonNs: bigint, disambiguation: Disambiguation): bigint | undefined | null;
+/**
+ * The first instant at or after `fromNs` that the schedule is closed: `fromNs` itself outside
+ * every open run, else the end of the run holding it. A closed `fromNs` is answered as soon as
+ * no later window can cover it. `undefined` when the answer falls after `horizonNs`, `null` when
+ * the walk fails or a window rejected under `"reject"` could keep the schedule open past it.
+ */
+export declare function firstClosedInstant(schedule: ResolvedSchedule, fromNs: bigint, horizonNs: bigint, disambiguation: Disambiguation): bigint | undefined | null;
+/**
+ * The instant at which `amountNs` of open time has elapsed since `fromNs`: the earliest `X`
+ * with exactly that much open time in `[fromNs, X)`. `fromNs` itself when `amountNs` is zero.
+ * Answered as soon as no later window can add open time before `X`. `undefined` when `X` falls
+ * after `horizonNs`, `null` when the walk fails or a window rejected under `"reject"` could add
+ * open time before `X`.
+ */
+export declare function instantAfterOpenTime(schedule: ResolvedSchedule, fromNs: bigint, amountNs: bigint, horizonNs: bigint, disambiguation: Disambiguation): bigint | undefined | null;
+/**
+ * An amount of open time in nanoseconds, from an ISO duration of hours and smaller units.
+ * `null` for a negative duration, for any calendar unit (years, months, weeks or days — `P1D`
+ * could mean 24 open hours or one working day, so it is not guessed), or invalid input.
+ */
+export declare function parseOpenTimeAmount(value: unknown): bigint | null;
+/** Epoch nanoseconds as a UTC instant string ending in `Z`. */
+export declare function instantText(nanoseconds: bigint): string;