@northguild/gmt 1.15.0 → 1.17.0

package/dist/instant/convert/fromOffsetInstant.js

@@ -0,0 +1,91 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { formatUtcOffset, parseInstantNanoseconds, parseUtcOffsetNanoseconds, wallClockAtOffset, } 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 (`wallClockAtOffset` keeps both range limits and sub-minute offsets).
+            const wallClock = wallClockAtOffset(instant, 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,96 @@
+/**
+ * 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",
+ * };
+ */
+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,162 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { formatUtcOffset, isoStringBody, parseInstantNanoseconds, TIME_ZONE_ANNOTATION, zonedDateTimeFrom, } from "../../internal/index.js";
+import { utcOffset } from "../../regex/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+/** A leading RFC 9557 time zone annotation: `[zone]` or `[!zone]`, with no `=`. */
+const timeZoneAnnotation = new RegExp(`^${TIME_ZONE_ANNOTATION}`);
+/**
+ * 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/intermodal/calculate/billingTimeline.d.ts

@@ -0,0 +1,94 @@
+/** The dates a billing timeline is counted from: the anchor, and the invoice and request once they exist. */
+export interface BillingDates {
+    /**
+     * The date the issue window is counted from, as an ISO date, such as the date the charge was
+     * last incurred or, for a re-bill, the issuance date of the invoice received.
+     */
+    anchorOn: string;
+    /** The date the invoice was issued, once it has been. */
+    invoiceIssuedOn?: string;
+    /** The date the dispute request was received, once it has been. */
+    requestReceivedOn?: string;
+}
+/** The three windows the caller supplies, in calendar days, none defaulted, and an optional agreed resolution date. */
+export interface BillingWindows {
+    /** Days from `anchorOn` within which the invoice must be issued. */
+    issueDays: number;
+    /** Days from `invoiceIssuedOn` within which a dispute may be raised. */
+    disputeDays: number;
+    /** Days from `requestReceivedOn` within which the dispute must be resolved. */
+    resolutionDays: number;
+    /** A resolution date the parties agreed instead; it replaces the computed one. */
+    agreedResolutionOn?: string;
+}
+/** What `billingTimeline` returns: each deadline as an ISO date, and each comparison once its date exists. */
+export interface BillingDeadlines {
+    /** `anchorOn + issueDays`. */
+    invoiceDeadline: string;
+    /** Whether `invoiceIssuedOn` is on or before `invoiceDeadline`; `null` until an invoice date exists. */
+    issuedByDeadline: boolean | null;
+    /** `invoiceIssuedOn + disputeDays`; `null` until an invoice date exists. */
+    disputeDeadline: string | null;
+    /** Whether `requestReceivedOn` is on or before `disputeDeadline`; `null` until a request date exists. */
+    requestedByDeadline: boolean | null;
+    /** `requestReceivedOn + resolutionDays`, or `agreedResolutionOn`; `null` until a request date exists. */
+    resolutionDeadline: string | null;
+}
+/**
+ * Lay out the deadline chain around a demurrage or detention invoice: the last date it may be
+ * issued, the last date it may be disputed, and the last date the dispute must be resolved.
+ *
+ * A billing regime or service contract can set up to three windows around an invoice: one to
+ * issue it, one to dispute it, and one to resolve the dispute. The number of days in each is the
+ * caller's fact; GMT carries none of them. The arithmetic is this function's: each deadline is a
+ * date, counted in calendar days from a date, with the anchor as day zero and the deadline day
+ * itself inside the window.
+ *
+ * - **Day zero is the anchor and the deadline is `anchor + days`** on the ISO 8601 calendar
+ *   (`Temporal.PlainDate.add`); a date is "by the deadline" when
+ *   `Temporal.PlainDate.compare(date, deadline) <= 0`. That is this function's stated contract,
+ *   not a reading of any rule; a regime that counts differently passes a different number.
+ * - **Deadlines are dates, never instants.** Reduce an instant to the billing party's local date
+ *   first with `convertUtcToPlainDate(instant, { timeZone })`; this function does not guess a
+ *   zone. `anchorOn` is whatever date the caller counts from, such as the last charged date
+ *   (`chargeableDays(...).chargedDates.at(-1)`) or, for a party re-billing a charge it was
+ *   itself billed, the issuance date of the invoice it received.
+ * - **Windows have no defaults.** Each is a safe integer of at least `0`; a missing, negative or
+ *   non-integer window returns `null`, because a silently defaulted window is a wrong deadline.
+ * - **The chain fills in as its dates exist.** With only `anchorOn` the result is a forecast:
+ *   `invoiceDeadline` is set and every other field is `null`. An invoice date sets
+ *   `issuedByDeadline` and `disputeDeadline`; a request date sets `requestedByDeadline` and
+ *   `resolutionDeadline`. An explicit `undefined` is an omission; any other value must be a
+ *   valid ISO date.
+ * - **The booleans compare dates and say nothing else.** Whether a charge is payable, whether a
+ *   dispute must be heard, and any consequence are the consumer's. GMT computes dates, not
+ *   liability.
+ * - **`agreedResolutionOn` replaces the computed `resolutionDeadline`** when given. It must be a
+ *   valid date on or after `requestReceivedOn`, else `null`; it is validated even when no
+ *   request exists, but cannot act without one.
+ * - **A request cannot precede the invoice it disputes.** `requestReceivedOn` without
+ *   `invoiceIssuedOn`, or earlier than it, is a data error and returns `null`. An invoice earlier
+ *   than the anchor is allowed: an invoice may be issued while charges still accrue.
+ * - Every emitted date is canonical bare ISO (`Temporal.PlainDate#toString()`), so an input
+ *   annotation such as `[u-ca=iso8601]` does not reach the output, as `addDate` behaves.
+ * - Returns `null` when `dates` or `windows` is not an object, `anchorOn` or a given optional
+ *   date is not a valid ISO date, a window is missing or not a safe integer of at least `0`, a
+ *   request exists without an invoice or before it, `agreedResolutionOn` is before the request,
+ *   or a deadline would leave Temporal's range.
+ *
+ * @param dates { anchorOn: string, invoiceIssuedOn?: string, requestReceivedOn?: string } ISO dates
+ * @param windows { issueDays: number, disputeDays: number, resolutionDays: number, agreedResolutionOn?: string } calendar-day windows, none defaulted
+ * @returns { invoiceDeadline, issuedByDeadline, disputeDeadline, requestedByDeadline, resolutionDeadline }, or null on invalid input
+ *
+ * @example billingTimeline({ anchorOn: "2026-03-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (no invoice yet: a forecast)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-31" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-30", requestedByDeadline: null, resolutionDeadline: null } (day 30 is the last day by the deadline)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-04-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: false, disputeDeadline: "2026-05-01", requestedByDeadline: null, resolutionDeadline: null } (day 31)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-20", requestReceivedOn: "2026-04-19" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-19", requestedByDeadline: true, resolutionDeadline: "2026-05-19" }
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-20", requestReceivedOn: "2026-04-20" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30, agreedResolutionOn: "2026-06-01" }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: true, disputeDeadline: "2026-04-19", requestedByDeadline: false, resolutionDeadline: "2026-06-01" } (an agreed date replaces the computed one)
+ * @example billingTimeline({ anchorOn: "2026-03-10", invoiceIssuedOn: "2026-04-05" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-04-09", issuedByDeadline: true, disputeDeadline: "2026-05-05", requestedByDeadline: null, resolutionDeadline: null } (a re-bill anchored on the invoice it received, not on the charge)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-05", requestReceivedOn: "2026-03-18" }, { issueDays: 14, disputeDays: 14, resolutionDays: 45 }) // { invoiceDeadline: "2026-03-15", issuedByDeadline: true, disputeDeadline: "2026-03-19", requestedByDeadline: true, resolutionDeadline: "2026-05-02" } (a service contract's own windows)
+ * @example billingTimeline({ anchorOn: "2028-01-30" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2028-02-29", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (calendar days across a leap day)
+ * @example billingTimeline({ anchorOn: "2026-03-01", invoiceIssuedOn: "2026-03-31" }, { disputeDays: 30, resolutionDays: 30 }) // null (issueDays has no default)
+ * @example billingTimeline({ anchorOn: "2026-03-01", requestReceivedOn: "2026-04-19" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // null (a request cannot precede the invoice it disputes)
+ */
+export declare function billingTimeline(dates: BillingDates, windows: BillingWindows): BillingDeadlines | null;