@northguild/gmt 1.14.2 → 1.16.0

package/dist/instant/convert/fromOffsetInstant.js

@@ -0,0 +1,99 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { formatUtcOffset, parseInstantNanoseconds, parseUtcOffsetNanoseconds, } from "../../internal/index.js";
+import { utcOffset } from "../../regex/index.js";
+/**
+ * Render an instant-plus-offset pair back to the local time it describes.
+ *
+ * The inverse of `toOffsetInstant`: `toOffsetInstant(fromOffsetInstant(pair))` returns
+ * `pair`, for zones with and without DST.
+ *
+ * - Without `timeZone`, returns `<date>T<time>±HH:MM` — the wall clock the event carried and
+ *   the offset it carried it in, which is all an offset-only pair knows.
+ * - With `timeZone`, returns the bracketed zoned string `<date>T<time>±HH:MM[Zone]`, so the
+ *   zone survives the round trip instead of being silently dropped.
+ * - A `timeZone` whose offset at `instant` is not `offset` returns `""`. The pair is stating
+ *   two things that cannot both be true, and the whole point of carrying both fields is that
+ *   a contradiction between them is visible.
+ * - `timeZone` accepts every identifier Temporal does, as `toOffsetInstant`'s bracket does —
+ *   including the single-component IANA names (`EST5EDT`, `Zulu`). A `timeZone` that is really
+ *   an offset (`"-04:00"`, or the `"-0400"`/`"+05"` spellings Temporal canonicalises to one)
+ *   returns `""`: it names no place, and no pair `toOffsetInstant` produces carries one.
+ * - `offset` is canonicalised, so `"+05:45:00"` renders as `+05:45` and `"-00:00"` as
+ *   `+00:00`. `Z` is not an accepted offset — for an event that happened at UTC the pair's
+ *   offset is `+00:00`. RFC 9557 §2.2 gives `Z` and `-00:00` a different meaning from `+00:00`
+ *   ("UTC known, local offset unknown"); a pair cannot carry that, so all three render as
+ *   `+00:00`.
+ * - With a `timeZone`, a sub-minute offset is *written* rounded to the minute, because RFC
+ *   9557 has no field for the seconds — `Africa/Monrovia`'s `-00:44:30` renders as `-00:45`.
+ *   The bracketed zone is what resolves it, so the instant stays exact and the round trip
+ *   returns `-00:44:30`. Without a `timeZone` there is no zone to resolve against, so the
+ *   full `±HH:MM:SS` is written instead; that is ISO 8601, not RFC 9557.
+ * - Returns `""` on invalid input.
+ *
+ * @param value `{ instant, offset, timeZone? }` pair, as produced by `toOffsetInstant`
+ * @returns local ISO 8601 string carrying the pair's own offset, or "" on invalid input
+ *
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-04:00" }) // "2024-07-15T12:00:00-04:00"
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }) // "2024-07-15T12:00:00-04:00[America/New_York]"
+ * @example fromOffsetInstant({ instant: "2024-11-03T05:30:00Z", offset: "-04:00", timeZone: "America/New_York" }) // "2024-11-03T01:30:00-04:00[America/New_York]" — the first 01:30 of the fall-back night
+ * @example fromOffsetInstant({ instant: "2024-11-03T06:30:00Z", offset: "-05:00", timeZone: "America/New_York" }) // "2024-11-03T01:30:00-05:00[America/New_York]" — the second, an hour later
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "+00:00" }) // "2024-07-15T16:00:00+00:00"
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-00:00" }) // "2024-07-15T16:00:00+00:00" (RFC 9557's "offset unknown" is not kept)
+ * @example fromOffsetInstant({ instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" }) // "1969-12-31T23:15:30-00:45[Africa/Monrovia]" — RFC 9557 rounds the written offset; the zone keeps the instant exact
+ * @example fromOffsetInstant({ instant: "1970-01-01T00:00:00Z", offset: "-00:44:30" }) // "1969-12-31T23:15:30-00:44:30" — no zone to round against, so the seconds are written
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-05:00", timeZone: "America/New_York" }) // "" (offset contradicts the zone)
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "-04:00" }) // "" (an offset is not a zone)
+ * @example fromOffsetInstant({ instant: "2024-07-15T16:00:00Z", offset: "Z" }) // "" (a designator, not an offset)
+ * @example fromOffsetInstant({ instant: "not an instant", offset: "-04:00" }) // ""
+ */
+export function fromOffsetInstant(value) {
+    try {
+        if (typeof value !== "object" || value === null) {
+            return "";
+        }
+        const epochNanoseconds = parseInstantNanoseconds(value.instant);
+        const offsetNanoseconds = parseUtcOffsetNanoseconds(value.offset);
+        if (epochNanoseconds === null || offsetNanoseconds === null) {
+            return "";
+        }
+        const offset = formatUtcOffset(offsetNanoseconds);
+        if (offset === null) {
+            return "";
+        }
+        try {
+            const instant = Temporal.Instant.fromEpochNanoseconds(epochNanoseconds);
+            if (value.timeZone !== undefined) {
+                // Temporal is the authority on what identifier this is, exactly as it is for a
+                // bracketed zone in `toOffsetInstant` — an unrecognised one throws, and the two
+                // functions have to agree or a pair one produced would not survive the other. The
+                // canonicalised id is what gets tested for an offset, since `"-0400"` and `"+05"` are
+                // offsets too and only Temporal knows that.
+                const zoned = instant.toZonedDateTimeISO(value.timeZone);
+                if (utcOffset.test(zoned.timeZoneId)) {
+                    return "";
+                }
+                return zoned.offset === offset ? zoned.toString() : "";
+            }
+            // With no zone, the offset is the only thing that can shift the instant onto a wall
+            // clock. The shift happens on the wall clock, never on the instant: `PlainDateTime`
+            // reaches a day further either side than `Instant` does, so shifting the instant first
+            // would reject the last 14 hours of the representable range — where a pair like
+            // `{ "+275760-09-13T00:00:00Z", "+14:00" }` names a local time that exists. No offset
+            // time zone is used either, since Temporal refuses to build one from a sub-minute
+            // offset.
+            const wallClock = instant
+                .toZonedDateTimeISO("UTC")
+                .toPlainDateTime()
+                .add({ nanoseconds: Number(offsetNanoseconds) });
+            return `${wallClock.toString()}${offset}`;
+        }
+        catch {
+            return "";
+        }
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/instant/convert/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./classifyLocal.js";
+export * from "./fromOffsetInstant.js";
+export * from "./resolveLocal.js";
+export * from "./toOffsetInstant.js";

package/dist/instant/convert/index.js

@@ -0,0 +1,4 @@
+export * from "./classifyLocal.js";
+export * from "./fromOffsetInstant.js";
+export * from "./resolveLocal.js";
+export * from "./toOffsetInstant.js";

package/dist/instant/convert/resolveLocal.d.ts

@@ -0,0 +1,40 @@
+import type { Disambiguation } from "../../types/index.js";
+/**
+ * Resolve a zoneless local wall time against an IANA zone and return the instant it names.
+ *
+ * Feeds deliver wall times with no offset all the time — "gate-out 08:00" — and turning one
+ * into an instant takes a zone the sender did not send plus a policy for the two days a year
+ * the mapping is not one-to-one. This states both.
+ *
+ * - `disambiguation` decides what happens when the wall time is ambiguous (a fall-back hour
+ *   that happens twice) or nonexistent (a spring-forward hour that never happens):
+ *   `"compatible"` (the default, matching Temporal), `"earlier"`, `"later"`, or `"reject"`,
+ *   which returns `""` rather than resolving. Call `classifyLocal` first to find out which
+ *   case you are in before a policy is applied.
+ * - Returns a UTC instant, exactly — no rounding, so a nanosecond wall time survives. Pass it
+ *   to `toOffsetInstant` for the offset pair, or reach for `convertPlainDateTimeToZoned` when
+ *   what you want is the bracketed zoned string (it defaults to millisecond precision).
+ * - `localDateTime` is a PlainDateTime string, as `isValidDateTime` accepts: `<date>T<time>`
+ *   with no offset (an offset means the wall time already resolved). Its RFC 9557 annotations
+ *   are read as `Temporal.PlainDateTime.from` reads them, so a time zone annotation
+ *   (`[America/New_York]`) is ignored and `timeZone` alone resolves the wall time.
+ * - Returns `""` on invalid input.
+ *
+ * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
+ * @param timeZone IANA timeZone identifier the wall time is read in
+ * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject")
+ * @returns UTC instant string ending in "Z", or "" on invalid input
+ *
+ * @example resolveLocal("2024-07-15T12:00:00", "America/New_York") // "2024-07-15T16:00:00Z"
+ * @example resolveLocal("2024-11-03T01:30:00", "America/New_York") // "2024-11-03T05:30:00Z" (ambiguous; "compatible" takes the earlier)
+ * @example resolveLocal("2024-11-03T01:30:00", "America/New_York", { disambiguation: "later" }) // "2024-11-03T06:30:00Z" (the same wall time, an hour later)
+ * @example resolveLocal("2024-11-03T01:30:00", "America/New_York", { disambiguation: "reject" }) // "" (ambiguous, and not guessed)
+ * @example resolveLocal("2024-03-10T02:30:00", "America/New_York") // "2024-03-10T07:30:00Z" (nonexistent; "compatible" takes the later)
+ * @example resolveLocal("2024-03-10T02:30:00", "America/New_York", { disambiguation: "earlier" }) // "2024-03-10T06:30:00Z"
+ * @example resolveLocal("2024-07-15T12:00:00-04:00", "America/New_York") // "" (not a zoneless wall time)
+ * @example resolveLocal("2024-07-15T12:00:00[foo=bar]", "America/New_York") // "2024-07-15T16:00:00Z" (elective annotation ignored)
+ * @example resolveLocal("2024-07-15T12:00:00", "Invalid/Zone") // ""
+ */
+export declare function resolveLocal(localDateTime: string, timeZone: string, optionsArg?: {
+    disambiguation?: Disambiguation;
+}): string;

package/dist/instant/convert/resolveLocal.js

@@ -0,0 +1,76 @@
+import { isValidDateTime } from "../../plain/validate/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { isoStringBody, zonedDateTimeFrom } from "../../internal/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
+const DISAMBIGUATIONS = [
+    "compatible",
+    "earlier",
+    "later",
+    "reject",
+];
+/**
+ * Resolve a zoneless local wall time against an IANA zone and return the instant it names.
+ *
+ * Feeds deliver wall times with no offset all the time — "gate-out 08:00" — and turning one
+ * into an instant takes a zone the sender did not send plus a policy for the two days a year
+ * the mapping is not one-to-one. This states both.
+ *
+ * - `disambiguation` decides what happens when the wall time is ambiguous (a fall-back hour
+ *   that happens twice) or nonexistent (a spring-forward hour that never happens):
+ *   `"compatible"` (the default, matching Temporal), `"earlier"`, `"later"`, or `"reject"`,
+ *   which returns `""` rather than resolving. Call `classifyLocal` first to find out which
+ *   case you are in before a policy is applied.
+ * - Returns a UTC instant, exactly — no rounding, so a nanosecond wall time survives. Pass it
+ *   to `toOffsetInstant` for the offset pair, or reach for `convertPlainDateTimeToZoned` when
+ *   what you want is the bracketed zoned string (it defaults to millisecond precision).
+ * - `localDateTime` is a PlainDateTime string, as `isValidDateTime` accepts: `<date>T<time>`
+ *   with no offset (an offset means the wall time already resolved). Its RFC 9557 annotations
+ *   are read as `Temporal.PlainDateTime.from` reads them, so a time zone annotation
+ *   (`[America/New_York]`) is ignored and `timeZone` alone resolves the wall time.
+ * - Returns `""` on invalid input.
+ *
+ * @param localDateTime zoneless ISO 8601 local datetime string (e.g. "2024-11-03T01:30:00")
+ * @param timeZone IANA timeZone identifier the wall time is read in
+ * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject")
+ * @returns UTC instant string ending in "Z", or "" on invalid input
+ *
+ * @example resolveLocal("2024-07-15T12:00:00", "America/New_York") // "2024-07-15T16:00:00Z"
+ * @example resolveLocal("2024-11-03T01:30:00", "America/New_York") // "2024-11-03T05:30:00Z" (ambiguous; "compatible" takes the earlier)
+ * @example resolveLocal("2024-11-03T01:30:00", "America/New_York", { disambiguation: "later" }) // "2024-11-03T06:30:00Z" (the same wall time, an hour later)
+ * @example resolveLocal("2024-11-03T01:30:00", "America/New_York", { disambiguation: "reject" }) // "" (ambiguous, and not guessed)
+ * @example resolveLocal("2024-03-10T02:30:00", "America/New_York") // "2024-03-10T07:30:00Z" (nonexistent; "compatible" takes the later)
+ * @example resolveLocal("2024-03-10T02:30:00", "America/New_York", { disambiguation: "earlier" }) // "2024-03-10T06:30:00Z"
+ * @example resolveLocal("2024-07-15T12:00:00-04:00", "America/New_York") // "" (not a zoneless wall time)
+ * @example resolveLocal("2024-07-15T12:00:00[foo=bar]", "America/New_York") // "2024-07-15T16:00:00Z" (elective annotation ignored)
+ * @example resolveLocal("2024-07-15T12:00:00", "Invalid/Zone") // ""
+ */
+export function resolveLocal(localDateTime, timeZone, optionsArg) {
+    try {
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const disambiguation = optionsArg?.disambiguation === undefined
+            ? "compatible"
+            : optionsArg.disambiguation;
+        if (!isValidDateTime(localDateTime) ||
+            !isValidTimeZone(timeZone) ||
+            !DISAMBIGUATIONS.includes(disambiguation)) {
+            return "";
+        }
+        try {
+            return zonedDateTimeFrom(`${isoStringBody(localDateTime)}[${timeZone}]`, {
+                disambiguation,
+            })
+                .toInstant()
+                .toString();
+        }
+        catch {
+            return "";
+        }
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/instant/convert/toOffsetInstant.d.ts

@@ -0,0 +1,73 @@
+export interface OffsetInstant {
+    instant: string;
+    offset: string;
+    timeZone?: string;
+}
+/**
+ * Split an ISO 8601 instant string into the instant-plus-offset pair the world exchanges.
+ *
+ * - **An offset is not a zone.** `-05:00` does not identify `America/New_York` — it is every
+ *   zone at `-05:00` that day. Keep the offset for what already happened; keep the zone for
+ *   anything still to be scheduled. `timeZone` is optional because most feeds send no zone.
+ * - Accepts a `Z` instant, a bare `±HH:MM` offset, or a bracketed IANA zone, in ISO 8601
+ *   extended format with a `T` separator — `isValidInstant`'s grammar. Basic format, a space or
+ *   lower-case `t` separator and a lower-case `z` return null. RFC 9557
+ *   annotations are read as Temporal reads them (RFC 9557 §3.3, proposal-temporal
+ *   `ParseISODateTime`): a calendar (`[u-ca=hebrew]`) or elective (`[x-provenance=estimated]`)
+ *   annotation is ignored, and an unknown critical one (`[!foo=bar]`) returns null.
+ * - A bracketed zone whose offset contradicts it (`"...T12:00:00-05:00[America/New_York]"` in
+ *   July) returns null. The string states two things that cannot both be true, and guessing
+ *   which one the sender meant is exactly the bug the pair exists to prevent.
+ * - A bracketed *offset* time zone (Temporal's own `[-04:00]` shape) yields no `timeZone`
+ *   field. It names no place, so filling the field with it would claim GMT knows where the
+ *   event happened when all it has is the offset it already stores. Every other bracketed
+ *   identifier Temporal accepts is kept, including the single-component IANA names (`EST5EDT`,
+ *   `Zulu`), in its IANA casing.
+ * - `timeZone` names the zone the offset is read in, and is how a UTC-only feed gets a pair
+ *   with a local offset. It also overrides a zone bracketed in the string — the instant is
+ *   unchanged either way, only the local rendering differs. It is validated with
+ *   `isValidTimeZone`, so any IANA Zone or Link name is accepted, single-component ones
+ *   (`Japan`, `Zulu`, `EST5EDT`) included. An offset identifier (`"-05:00"`) sets the offset
+ *   and, like a bracketed offset zone, yields no `timeZone` field.
+ * - The returned `timeZone` is the identifier in its IANA casing on every path —
+ *   `"america/new_york"` comes back as `"America/New_York"` — because identifiers match
+ *   case-insensitively (ECMA-402). That is what the bracket path and `fromOffsetInstant` return,
+ *   so `toOffsetInstant(fromOffsetInstant(pair))` returns `pair`. A link name is kept, not
+ *   replaced by its target. Compatibility: earlier releases echoed the argument's casing; pass
+ *   the IANA-cased identifier to get the same string back.
+ * - A `Z` (or RFC 3339 `-00:00`) instant is recorded with offset `+00:00`. RFC 9557 §2.2 reads
+ *   `Z` and `-00:00` as "UTC known, local offset unknown", which differs from an explicit
+ *   `+00:00`; the pair has no spelling for an unknown offset, so that distinction is not kept.
+ * - An offset with fractional seconds (`+01:00:00.5`), which `isValidInstant` accepts, returns
+ *   null: `offset` holds at most `±HH:MM:SS`.
+ * - `offset` is `±HH:MM`, except for the handful of zones that did not run on a whole minute
+ *   before 1972, where it is `±HH:MM:SS` — `Africa/Monrovia` really was `-00:44:30`, and
+ *   rounding it would put the pair 30 seconds from the event it describes. Such a zone's
+ *   *string* still carries the rounded `-00:45`, because RFC 9557 caps a written offset at
+ *   minutes; the bracketed zone is what resolves it, so the instant stays exact.
+ * - Returns null on invalid input, not a zero-offset pair — `+00:00` is a real offset.
+ *
+ * @param value ISO 8601 instant string, with an offset designator and optionally a bracketed zone
+ * @param timeZone optional IANA zone identifier to read the offset in
+ * @returns `{ instant, offset, timeZone? }`, or null on invalid input
+ *
+ * @example toOffsetInstant("2024-07-15T12:00:00-04:00[America/New_York]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
+ * @example toOffsetInstant("2024-07-15T12:00:00-04:00") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an offset with no zone behind it
+ * @example toOffsetInstant("2024-07-15T16:00:00Z") // { instant: "2024-07-15T16:00:00Z", offset: "+00:00" }
+ * @example toOffsetInstant("2024-07-15T16:00:00Z", "America/New_York") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
+ * @example toOffsetInstant("2024-01-15T17:00:00Z", "America/New_York") // { instant: "2024-01-15T17:00:00Z", offset: "-05:00", timeZone: "America/New_York" } — same wall time, different offset, six months apart
+ * @example toOffsetInstant("1970-01-01T00:00:00Z", "Africa/Monrovia") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" }
+ * @example toOffsetInstant("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" } — the zone, not the rounded offset, fixes the instant
+ * @example toOffsetInstant("2024-07-15T12:00:00-04:00[-04:00]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — a bracketed offset is not a zone, so no timeZone field
+ * @example toOffsetInstant("2024-07-15T12:00:00-05:00[America/New_York]") // null (offset contradicts the bracketed zone)
+ * @example toOffsetInstant("2024-07-15T12:00:00-04:00[foo=bar]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an elective annotation is ignored
+ * @example toOffsetInstant("2024-07-15T12:00:00-04:00[!foo=bar]") // null (an unknown critical annotation)
+ * @example toOffsetInstant("2024-07-15T12:00:00") // null (no offset designator)
+ * @example toOffsetInstant("20240715T120000-0400") // null (basic format)
+ * @example toOffsetInstant("2024-07-15T16:00:00Z", "america/new_york") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" } — IANA casing
+ * @example toOffsetInstant("2024-07-15T16:00:00Z", "Japan") // { instant: "2024-07-15T16:00:00Z", offset: "+09:00", timeZone: "Japan" }
+ * @example toOffsetInstant("2024-07-15T16:00:00-00:00") // { instant: "2024-07-15T16:00:00Z", offset: "+00:00" } — "offset unknown" is not preserved
+ * @example toOffsetInstant("2024-07-15T16:00:00+01:00:00.5") // null (fractional-second offset)
+ * @example toOffsetInstant("2024-07-15T16:00:00Z", "Invalid/Zone") // null
+ */
+export declare function toOffsetInstant(value: string, timeZone?: string): OffsetInstant | null;

package/dist/instant/convert/toOffsetInstant.js

@@ -0,0 +1,185 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { formatUtcOffset, isoStringBody, parseInstantNanoseconds, zonedDateTimeFrom, } from "../../internal/index.js";
+import { utcOffset } from "../../regex/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+/**
+ * An absolute instant paired with the local UTC offset in force where the event happened.
+ *
+ * @remarks Members:
+ *
+ * | Member | Type | Description |
+ * | --- | --- | --- |
+ * | `instant` | `string` | UTC instant, ISO 8601 ending in `Z` (e.g. `2024-07-15T16:00:00Z`). Orders events globally. |
+ * | `offset` | `string` | UTC offset in force where the event happened, `±HH:MM` (or `±HH:MM:SS` for a pre-1972 zone that did not run on a whole minute). Renders the event as the human on the ground saw it. |
+ * | `timeZone` | `string \| undefined` | IANA zone identifier, when one is known. Absent from most feeds, so absent from most pairs. |
+ *
+ * Neither `instant` nor `offset` derives from the other, which is why both are stored. It is
+ * the shape GS1 EPCIS 2.0 (`eventTime` + a required `eventTimeZoneOffset`), UN/EDIFACT DTM
+ * (qualifier `303`/`304`) and DICOM (`DT` + `&ZZXX`) all exchange.
+ *
+ * @example
+ * import { OffsetInstant } from "@northguild/gmt/instant";
+ * const pair: OffsetInstant = {
+ *   instant: "2024-07-15T16:00:00Z",
+ *   offset: "-04:00",
+ *   timeZone: "America/New_York",
+ * };
+ */
+/** A leading RFC 9557 time zone annotation: `[zone]` or `[!zone]`, with no `=`. */
+const timeZoneAnnotation = /^\[!?[^\]=]+\]/;
+/**
+ * Split an ISO 8601 instant string into the instant-plus-offset pair the world exchanges.
+ *
+ * - **An offset is not a zone.** `-05:00` does not identify `America/New_York` — it is every
+ *   zone at `-05:00` that day. Keep the offset for what already happened; keep the zone for
+ *   anything still to be scheduled. `timeZone` is optional because most feeds send no zone.
+ * - Accepts a `Z` instant, a bare `±HH:MM` offset, or a bracketed IANA zone, in ISO 8601
+ *   extended format with a `T` separator — `isValidInstant`'s grammar. Basic format, a space or
+ *   lower-case `t` separator and a lower-case `z` return null. RFC 9557
+ *   annotations are read as Temporal reads them (RFC 9557 §3.3, proposal-temporal
+ *   `ParseISODateTime`): a calendar (`[u-ca=hebrew]`) or elective (`[x-provenance=estimated]`)
+ *   annotation is ignored, and an unknown critical one (`[!foo=bar]`) returns null.
+ * - A bracketed zone whose offset contradicts it (`"...T12:00:00-05:00[America/New_York]"` in
+ *   July) returns null. The string states two things that cannot both be true, and guessing
+ *   which one the sender meant is exactly the bug the pair exists to prevent.
+ * - A bracketed *offset* time zone (Temporal's own `[-04:00]` shape) yields no `timeZone`
+ *   field. It names no place, so filling the field with it would claim GMT knows where the
+ *   event happened when all it has is the offset it already stores. Every other bracketed
+ *   identifier Temporal accepts is kept, including the single-component IANA names (`EST5EDT`,
+ *   `Zulu`), in its IANA casing.
+ * - `timeZone` names the zone the offset is read in, and is how a UTC-only feed gets a pair
+ *   with a local offset. It also overrides a zone bracketed in the string — the instant is
+ *   unchanged either way, only the local rendering differs. It is validated with
+ *   `isValidTimeZone`, so any IANA Zone or Link name is accepted, single-component ones
+ *   (`Japan`, `Zulu`, `EST5EDT`) included. An offset identifier (`"-05:00"`) sets the offset
+ *   and, like a bracketed offset zone, yields no `timeZone` field.
+ * - The returned `timeZone` is the identifier in its IANA casing on every path —
+ *   `"america/new_york"` comes back as `"America/New_York"` — because identifiers match
+ *   case-insensitively (ECMA-402). That is what the bracket path and `fromOffsetInstant` return,
+ *   so `toOffsetInstant(fromOffsetInstant(pair))` returns `pair`. A link name is kept, not
+ *   replaced by its target. Compatibility: earlier releases echoed the argument's casing; pass
+ *   the IANA-cased identifier to get the same string back.
+ * - A `Z` (or RFC 3339 `-00:00`) instant is recorded with offset `+00:00`. RFC 9557 §2.2 reads
+ *   `Z` and `-00:00` as "UTC known, local offset unknown", which differs from an explicit
+ *   `+00:00`; the pair has no spelling for an unknown offset, so that distinction is not kept.
+ * - An offset with fractional seconds (`+01:00:00.5`), which `isValidInstant` accepts, returns
+ *   null: `offset` holds at most `±HH:MM:SS`.
+ * - `offset` is `±HH:MM`, except for the handful of zones that did not run on a whole minute
+ *   before 1972, where it is `±HH:MM:SS` — `Africa/Monrovia` really was `-00:44:30`, and
+ *   rounding it would put the pair 30 seconds from the event it describes. Such a zone's
+ *   *string* still carries the rounded `-00:45`, because RFC 9557 caps a written offset at
+ *   minutes; the bracketed zone is what resolves it, so the instant stays exact.
+ * - Returns null on invalid input, not a zero-offset pair — `+00:00` is a real offset.
+ *
+ * @param value ISO 8601 instant string, with an offset designator and optionally a bracketed zone
+ * @param timeZone optional IANA zone identifier to read the offset in
+ * @returns `{ instant, offset, timeZone? }`, or null on invalid input
+ *
+ * @example toOffsetInstant("2024-07-15T12:00:00-04:00[America/New_York]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
+ * @example toOffsetInstant("2024-07-15T12:00:00-04:00") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an offset with no zone behind it
+ * @example toOffsetInstant("2024-07-15T16:00:00Z") // { instant: "2024-07-15T16:00:00Z", offset: "+00:00" }
+ * @example toOffsetInstant("2024-07-15T16:00:00Z", "America/New_York") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" }
+ * @example toOffsetInstant("2024-01-15T17:00:00Z", "America/New_York") // { instant: "2024-01-15T17:00:00Z", offset: "-05:00", timeZone: "America/New_York" } — same wall time, different offset, six months apart
+ * @example toOffsetInstant("1970-01-01T00:00:00Z", "Africa/Monrovia") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" }
+ * @example toOffsetInstant("1969-12-31T23:15:30-00:45[Africa/Monrovia]") // { instant: "1970-01-01T00:00:00Z", offset: "-00:44:30", timeZone: "Africa/Monrovia" } — the zone, not the rounded offset, fixes the instant
+ * @example toOffsetInstant("2024-07-15T12:00:00-04:00[-04:00]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — a bracketed offset is not a zone, so no timeZone field
+ * @example toOffsetInstant("2024-07-15T12:00:00-05:00[America/New_York]") // null (offset contradicts the bracketed zone)
+ * @example toOffsetInstant("2024-07-15T12:00:00-04:00[foo=bar]") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00" } — an elective annotation is ignored
+ * @example toOffsetInstant("2024-07-15T12:00:00-04:00[!foo=bar]") // null (an unknown critical annotation)
+ * @example toOffsetInstant("2024-07-15T12:00:00") // null (no offset designator)
+ * @example toOffsetInstant("20240715T120000-0400") // null (basic format)
+ * @example toOffsetInstant("2024-07-15T16:00:00Z", "america/new_york") // { instant: "2024-07-15T16:00:00Z", offset: "-04:00", timeZone: "America/New_York" } — IANA casing
+ * @example toOffsetInstant("2024-07-15T16:00:00Z", "Japan") // { instant: "2024-07-15T16:00:00Z", offset: "+09:00", timeZone: "Japan" }
+ * @example toOffsetInstant("2024-07-15T16:00:00-00:00") // { instant: "2024-07-15T16:00:00Z", offset: "+00:00" } — "offset unknown" is not preserved
+ * @example toOffsetInstant("2024-07-15T16:00:00+01:00:00.5") // null (fractional-second offset)
+ * @example toOffsetInstant("2024-07-15T16:00:00Z", "Invalid/Zone") // null
+ */
+export function toOffsetInstant(value, timeZone) {
+    const epochNanoseconds = parseInstantNanoseconds(value);
+    if (epochNanoseconds === null) {
+        return null;
+    }
+    if (timeZone !== undefined && !isValidTimeZone(timeZone)) {
+        return null;
+    }
+    try {
+        // `parseInstantNanoseconds` reads the offset and ignores the bracket, so a self-
+        // contradictory string parses fine as an instant. `ZonedDateTime.from` is what checks
+        // the two agree, and it runs even when `timeZone` overrides the bracketed zone.
+        // Only a time zone annotation makes the string zoned: it is the first annotation, and the
+        // only kind with no `=` (RFC 9557 §4.1). A calendar or elective annotation alone leaves an
+        // offset-only instant.
+        const body = isoStringBody(value);
+        const bracketed = timeZoneAnnotation.test(value.slice(body.length))
+            ? zonedDateTimeFrom(value)
+            : null;
+        // Temporal also accepts a bracketed *offset* time zone (`[-04:00]`), and canonicalises
+        // every spelling of one (`[-0400]`, `[+05]`) to `±HH:MM`. That names no place and must
+        // not reach the `timeZone` field, which would then claim GMT knows where the event
+        // happened when all it has is the offset it already stores. The test is for an offset
+        // because that is the one kind of bracketed identifier to drop; Temporal has already
+        // validated every other one as part of the string.
+        const bracketedZone = bracketed !== null && !utcOffset.test(bracketed.timeZoneId)
+            ? bracketed.timeZoneId
+            : undefined;
+        // Where a bracket is present, Temporal's own resolution is the authority on the
+        // instant, not `Temporal.Instant.from`'s literal reading of the offset. For a zone that
+        // did not run on a whole minute the two disagree: RFC 9557 caps a string's offset at
+        // minutes, so `Africa/Monrovia` writes `-00:45` for a real `-00:44:30`, and reading
+        // that literally lands 30 seconds late. `ZonedDateTime.from` resolves the rounded
+        // offset against the zone's true one. For every other zone the two agree exactly, and a
+        // mismatched offset has already thrown.
+        const instant = bracketed !== null
+            ? bracketed.toInstant()
+            : Temporal.Instant.fromEpochNanoseconds(epochNanoseconds);
+        const resolvedZone = timeZone ?? bracketedZone;
+        if (resolvedZone !== undefined) {
+            return offsetInstantInZone(instant, resolvedZone);
+        }
+        // No zone, so the only offset on record is the one written in the string — and with a
+        // bracket present Temporal has already read it.
+        if (bracketed !== null) {
+            return { instant: instant.toString(), offset: bracketed.offset };
+        }
+        const offset = writtenOffset(instant, body);
+        return offset === null ? null : { instant: instant.toString(), offset };
+    }
+    catch {
+        return null;
+    }
+}
+/** The pair read in `zone`; an offset zone names no place, so it fills no `timeZone` field. */
+function offsetInstantInZone(instant, zone) {
+    // `timeZoneId` is the identifier in its IANA casing (ECMA-402
+    // GetAvailableNamedTimeZoneIdentifier matches case-insensitively and returns the database's
+    // spelling), which is what the bracket path and `fromOffsetInstant` already return. A link
+    // name stays a link name: `Asia/Calcutta` is not rewritten to `Asia/Kolkata`.
+    const zoned = instant.toZonedDateTimeISO(zone);
+    // An offset `timeZone` (`"-05:00"`, canonicalised by Temporal) sets the offset like a
+    // bracketed offset zone does and, naming no place, fills no `timeZone` field.
+    if (utcOffset.test(zoned.timeZoneId)) {
+        return { instant: instant.toString(), offset: zoned.offset };
+    }
+    return {
+        instant: instant.toString(),
+        offset: zoned.offset,
+        timeZone: zoned.timeZoneId,
+    };
+}
+/** The offset the string's own digits were written in, recovered for an unbracketed value. */
+function writtenOffset(instant, body) {
+    // With no zone and no bracket, the offset is the distance between two wall clocks: the digits as
+    // written, and the same instant read in UTC. That recovers it without slicing the
+    // string. The subtraction stays on `PlainDateTime` rather than going through an
+    // instant, because a wall clock reaches a day further either side than an instant does
+    // — `+275760-09-13T14:00:00+14:00` names a representable instant whose digits, read as
+    // UTC, are past the end of the range. `PlainDateTime.from` parses every shape this
+    // grammar allows but the `Z` designator, and a `Z` string's wall clock *is* the UTC
+    // one, so its offset is `+00:00` by definition.
+    const utcWallClock = instant.toZonedDateTimeISO("UTC").toPlainDateTime();
+    const writtenWallClock = body.endsWith("Z") || body.endsWith("z")
+        ? utcWallClock
+        : Temporal.PlainDateTime.from(body);
+    return formatUtcOffset(BigInt(utcWallClock.until(writtenWallClock, { largestUnit: "nanosecond" })
+        .nanoseconds));
+}

package/dist/instant/index.d.ts

@@ -0,0 +1,2 @@
+export * from "@js-temporal/polyfill";
+export * from "./convert/index.js";

package/dist/instant/index.js

@@ -0,0 +1,3 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
+export * from "./convert/index.js";

package/dist/internal/adjustZonedBusinessDays.js

@@ -1,13 +1,15 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { advanceBusinessDays } from "./advanceBusinessDays.js";
+import { DEFAULT_BUSINESS_CALENDAR, stepBusinessDates, } from "./businessCalendar.js";
+import { plainToZoned, zonedWithPlainTime } from "./zonedWallClockOperations.js";
+import { zonedDateTimeFrom } from "./zonedWallClock.js";
 export function adjustZonedBusinessDays(value, direction, absAmount) {
     try {
-        const zoned = Temporal.ZonedDateTime.from(value);
+        const zoned = zonedDateTimeFrom(value);
         const plainDate = zoned.toPlainDate();
-        const resultDate = advanceBusinessDays(plainDate, direction, absAmount);
-        const resultZoned = resultDate
-            .toZonedDateTime(zoned.timeZoneId)
-            .withPlainTime(zoned.toPlainTime());
+        const resultDate = stepBusinessDates(plainDate, direction, absAmount, DEFAULT_BUSINESS_CALENDAR);
+        if (resultDate === null) {
+            return "";
+        }
+        const resultZoned = zonedWithPlainTime(plainToZoned(resultDate, zoned.timeZoneId), zoned.toPlainTime());
         return resultZoned.toString();
     }
     catch {

package/dist/internal/businessCalendar.d.ts

@@ -0,0 +1,46 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { BusinessCalendar } from "../types/index.js";
+/**
+ * Calendar days a single business-day walk may step before giving up — roughly 547 years, far
+ * past any real schedule. A walk that runs out returns the sentinel, never a partial answer.
+ */
+export declare const MAX_BUSINESS_DAY_STEPS = 200000;
+/** A `BusinessCalendar` reduced to the two lookups every walk needs. */
+export type ResolvedBusinessCalendar = {
+    weekend: Set<number>;
+    holidays: Set<string>;
+};
+export declare const DEFAULT_BUSINESS_CALENDAR: ResolvedBusinessCalendar;
+/**
+ * Reduce a caller-supplied `BusinessCalendar` to its lookups, or `null` when it is not one.
+ *
+ * `undefined` is rejected here; `resolveBusinessCalendar` is the entry point that treats an
+ * absent calendar as the default Saturday–Sunday week.
+ */
+export declare function parseBusinessCalendar(calendar: unknown): ResolvedBusinessCalendar | null;
+/**
+ * Resolve an optional calendar: absent means the default Saturday–Sunday week with no
+ * holidays, anything else must be a valid `BusinessCalendar` or this returns `null`.
+ */
+export declare function resolveBusinessCalendar(calendar: BusinessCalendar | undefined): ResolvedBusinessCalendar | null;
+/** True when `date` is neither a weekend day nor a holiday in `calendar`. */
+export declare function isBusinessDate(date: Temporal.PlainDate, calendar: ResolvedBusinessCalendar): boolean;
+/**
+ * The first business day at or beyond `date`, walking in `direction`.
+ *
+ * `date` is an ISO-calendar date, as every caller validates. Returns `date` itself when it is
+ * already a business day, and `null` when the walk exceeds `MAX_BUSINESS_DAY_STEPS`. Throws a
+ * `RangeError` when the walk passes a Temporal range limit.
+ */
+export declare function businessDateFrom(date: Temporal.PlainDate, direction: 1 | -1, calendar: ResolvedBusinessCalendar): Temporal.PlainDate | null;
+/**
+ * Step `count` business days from `date` in `direction`, counting only days that are business
+ * days in `calendar`.
+ *
+ * `date` is an ISO-calendar date, as every caller validates. `count` is a non-negative whole
+ * number of business days. `date` itself is never counted, so a `count` of 0 returns `date`
+ * unchanged even when it is not a business day. Returns `null`
+ * when the walk exceeds `MAX_BUSINESS_DAY_STEPS`, and throws a `RangeError` when it passes a
+ * Temporal range limit.
+ */
+export declare function stepBusinessDates(date: Temporal.PlainDate, direction: 1 | -1, count: number, calendar: ResolvedBusinessCalendar): Temporal.PlainDate | null;