@northguild/gmt 1.16.0 → 1.18.0

package/dist/transport/calculate/scheduleDelivery.js

@@ -0,0 +1,300 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { TIME_ZONE_ANNOTATION, exactDurationNanoseconds, isOptionsArgument, isoStringBody, zonedDateTimeFrom, } from "../../internal/index.js";
+import { isValidDateTime } from "../../plain/validate/isValidDateTime.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
+import { isValidZonedDateTime } from "../../zoned/validate/isValidZonedDateTime.js";
+import { etaAtZone } from "../convert/etaAtZone.js";
+import { transitTime } from "./transitTime.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
+/**
+ * A time-zone annotation anywhere in the string (`TIME_ZONE_ANNOTATION`): a bracket without
+ * `=`. A departure that names a zone must name a real one that agrees with its offset.
+ */
+const zoneAnnotation = new RegExp(TIME_ZONE_ANNOTATION);
+/**
+ * A departure resolved to the exact instant it names, or `null`.
+ *
+ * An instant (`Z`/offset) is already exact; a zoned string is exact through its bracket, which
+ * is read and must be real and agree with its offset (unlike `crossingTime`, which never reads
+ * one). A zoneless wall time is a published local schedule time, exact only through
+ * `wallTimeZone` — the caller decides which zone that is: `startTimeZone` for the first leg,
+ * the previous leg's `timeZone` for any other leg (see `legDeparture`). Without one, a
+ * zoneless departure is not a moment. `cursor` picks the pass of a repeated hour (see
+ * `wallTimeInstant`).
+ */
+function departureInstant(departure, wallTimeZone, cursor) {
+    if (typeof departure !== "string") {
+        return null;
+    }
+    if (isValidZonedDateTime(departure)) {
+        return wallTimeInstant(departure, cursor);
+    }
+    if (zoneAnnotation.test(departure)) {
+        return null;
+    }
+    if (isValidInstant(departure)) {
+        return Temporal.Instant.from(departure);
+    }
+    if (wallTimeZone !== undefined && isValidDateTime(departure)) {
+        // resolveLocal's core: the zone the schedule's wall time is exact in.
+        return wallTimeInstant(`${isoStringBody(departure)}[${wallTimeZone}]`, cursor);
+    }
+    return null;
+}
+/**
+ * The instant a zoned string names. On a later leg (`cursor` set), a wall time the clock showed
+ * twice — a fall-back hour — resolves to the earliest pass at or after `cursor`, the first
+ * moment the cargo can leave: a printed hub time never says which pass it means, and the one a
+ * shipper would catch is the first the cargo is ready for. Otherwise, and when neither pass is
+ * at or after `cursor` (a real miss), it resolves `"compatible"`: the earlier pass of a
+ * repeated hour, the later instant of a skipped one. A written offset names one pass, so both
+ * reads agree and it always wins. A repeated hour is told apart from a skipped one by whether
+ * both passes keep the wall time asked for.
+ */
+function wallTimeInstant(zoned, cursor) {
+    if (cursor !== null) {
+        const earlier = zonedDateTimeFrom(zoned, { disambiguation: "earlier" });
+        const later = zonedDateTimeFrom(zoned, { disambiguation: "later" });
+        const repeated = !earlier.toInstant().equals(later.toInstant()) &&
+            earlier.toPlainDateTime().equals(later.toPlainDateTime());
+        if (repeated) {
+            for (const pass of [earlier.toInstant(), later.toInstant()]) {
+                if (Temporal.Instant.compare(pass, cursor) >= 0) {
+                    return pass;
+                }
+            }
+        }
+    }
+    return zonedDateTimeFrom(zoned, { disambiguation: "compatible" }).toInstant();
+}
+/** The three opaque tag keys of a leg, echoed onto its LegTime. */
+const TAG_KEYS = ["mode", "origin", "destination"];
+/**
+ * The leg's tags, ready to spread onto its LegTime — an unsupplied key stays truly absent —
+ * or `null` when a present tag is not a string.
+ */
+function legTags(leg) {
+    const tags = {};
+    for (const key of TAG_KEYS) {
+        const tag = leg[key];
+        if (tag === undefined) {
+            continue;
+        }
+        if (typeof tag !== "string") {
+            return null;
+        }
+        tags[key] = tag;
+    }
+    return tags;
+}
+/**
+ * The instant this leg leaves: its scheduled `departure`, or the connection cursor (the previous
+ * arrival plus its dwell) it chains from. A zoneless `departure` is read as a wall time in
+ * `startTimeZone` on the first leg (`cursor === null`), or in `previousTimeZone` — the previous
+ * leg's own `timeZone`, already proven real by that leg's `legBoundaries` call — on any other
+ * leg; `previousTimeZone` is `undefined`, and ignored, on the first leg. A scheduled departure
+ * before the cursor — inside the previous handoff's minimum connect time, or before the arrival
+ * itself — is a missed connection, invalid input rather than a negative wait; equal passes, a
+ * zero-slack connection is feasible. `null` on the first leg (no cursor) means the leg's
+ * departure did not resolve.
+ */
+function legDeparture(leg, cursor, startTimeZone, previousTimeZone) {
+    if (cursor !== null && leg.departure === undefined) {
+        return cursor;
+    }
+    const wallTimeZone = cursor === null ? startTimeZone : previousTimeZone;
+    const departure = departureInstant(leg.departure, wallTimeZone, cursor);
+    if (departure === null) {
+        return null;
+    }
+    if (cursor !== null && Temporal.Instant.compare(departure, cursor) < 0) {
+        return null;
+    }
+    return departure;
+}
+/**
+ * Whether a final leg's `dwellAfter` is a dwell `transitTime` would accept — an ISO 8601
+ * duration with no years, months or weeks — and is not negative. Checked on the duration alone:
+ * the last dwell moves nothing, so no instant is computed and the range cannot reject it.
+ */
+function isValidFinalDwell(dwellAfter) {
+    const nanoseconds = exactDurationNanoseconds(dwellAfter);
+    return nanoseconds !== null && nanoseconds >= 0n;
+}
+/**
+ * A leg's arrival, its local rendering, and the dwell hop to when the next leg may leave.
+ *
+ * `transitTime` gives both the leg and the hop the duration grammar (calendar units refused, a
+ * day is 24 hours). A leg that lands before it departs, or a hop that lands before its own
+ * arrival, is negative time — a data error. The final leg's hop is not taken (`released` is
+ * `null`): its dwell is validated as a duration and echoed, never turned into an instant.
+ */
+function legBoundaries(departure, leg, isFinal) {
+    const arrival = transitTime(departure.toString(), leg.duration);
+    if (arrival === "") {
+        return null;
+    }
+    const arrivalInstant = Temporal.Instant.from(arrival);
+    if (Temporal.Instant.compare(arrivalInstant, departure) < 0) {
+        return null;
+    }
+    const localArrival = etaAtZone(arrival, leg.timeZone);
+    if (localArrival === "") {
+        return null;
+    }
+    const dwellAfter = optionOrDefault(leg.dwellAfter, "PT0S");
+    if (isFinal) {
+        return isValidFinalDwell(dwellAfter)
+            ? { arrival, localArrival, dwellAfter, released: null }
+            : null;
+    }
+    const releasedString = transitTime(arrival, dwellAfter);
+    if (releasedString === "") {
+        return null;
+    }
+    const released = Temporal.Instant.from(releasedString);
+    if (Temporal.Instant.compare(released, arrivalInstant) < 0) {
+        return null;
+    }
+    return { arrival, localArrival, dwellAfter, released };
+}
+/**
+ * Chain the legs: each leg leaves at its scheduled departure or at the cursor the previous leg
+ * released, and lands as `legBoundaries` computes. `previousTimeZone` carries leg N-1's own
+ * `timeZone` forward so leg N's zoneless departure can be read in it; it stays `undefined`
+ * before leg 0 (where `startTimeZone` applies instead, never this) and is captured only once
+ * `legBoundaries` has proven that zone real, never speculatively. `null` when any leg is
+ * malformed, misses its connection, or leaves the instant range.
+ */
+function chainLegs(legs, startTimeZone) {
+    const legTimes = [];
+    let cursor = null;
+    let previousTimeZone;
+    for (const [index, leg] of legs.entries()) {
+        if (typeof leg !== "object" || leg === null) {
+            return null;
+        }
+        const tags = legTags(leg);
+        if (tags === null) {
+            return null;
+        }
+        const departure = legDeparture(leg, cursor, startTimeZone, previousTimeZone);
+        if (departure === null) {
+            return null;
+        }
+        const boundaries = legBoundaries(departure, leg, index === legs.length - 1);
+        if (boundaries === null) {
+            return null;
+        }
+        cursor = boundaries.released;
+        previousTimeZone = leg.timeZone;
+        legTimes.push({
+            arrival: boundaries.arrival,
+            localArrival: boundaries.localArrival,
+            dwellAfter: boundaries.dwellAfter,
+            ...tags,
+        });
+    }
+    return legTimes;
+}
+/**
+ * Chain the legs of a multi-modal move into an end-to-end ETA with zone-local times at every
+ * handoff.
+ *
+ * A truck→ship→rail move is published as one departure plus a duration per leg, and the hour
+ * naive implementations lose lives at the handoffs: every leg boundary here is an exact
+ * instant, and local rendering happens only at the edges, via `etaAtZone`.
+ *
+ * - **Each leg's arrival plus its `dwellAfter` is the next leg's departure** unless the next leg
+ *   carries an explicit `departure` — a scheduled connection the cargo waits for. `dwellAfter`
+ *   is the handling time at the handoff, the minimum connect time: a scheduled departure
+ *   earlier than the previous arrival plus its dwell is a missed connection and returns `null`
+ *   (equal passes — a zero-slack connection is feasible). It follows `transitTime`'s duration
+ *   grammar, may not be negative, and is echoed on the `LegTime` exactly as written (`"PT90M"`
+ *   stays `"PT90M"`), `"PT0S"` when omitted. The last leg's dwell moves nothing — there is no
+ *   leg after it — so it is validated as a duration (no years, months or weeks, not negative)
+ *   and echoed, but never added to an instant: it cannot turn a representable ETA into `null`.
+ * - **`departure` must be exact:** an instant (`Z`/offset) or a zoned string, whose bracketed
+ *   zone is read and must be real and agree with its offset. The first leg requires one.
+ * - **`startTimeZone` resolves the first leg alone:** schedules are published as zone-local wall
+ *   times, so a zoneless first-leg departure is read in `startTimeZone`. Zoneless without the
+ *   option is `null`; the option is ignored when the departure is already exact; an invalid
+ *   `startTimeZone` is `null` even when unused; it is never applied to a later leg — see the next
+ *   rule for those.
+ * - **A later leg's zoneless departure is read in the previous leg's `timeZone`:** a real
+ *   timetable publishes a local wall time at every hub, not just at origin, and leg N−1's
+ *   `timeZone` is exactly leg N's departure zone. So a zoneless departure on any leg but the
+ *   first is read there, with the same `"compatible"` disambiguation as `startTimeZone`. This is
+ *   a separate, always-on mechanism — `startTimeZone` still names only the first leg's zone and
+ *   cannot be used for a later one. The missed-connection check still runs after resolution, so a
+ *   later zoneless departure that resolves earlier than the cursor is still `null`.
+ * - **Local-time resolution policy (`"compatible"`).** A zoned departure written without an
+ *   offset (`"2024-11-03T01:30:00[America/New_York]"`), a zoneless first departure read in
+ *   `startTimeZone`, and a zoneless later-leg departure read in the previous leg's `timeZone`
+ *   are all wall times. An **ambiguous** wall time — a fall-back hour the clock ran through
+ *   twice — resolves to the **earlier** instant; a **nonexistent** one — a spring-forward hour
+ *   the clock skipped — resolves to the **later** instant. Write the offset to pick the other
+ *   pass of a repeated hour.
+ * - **A repeated hour at a hub takes the pass the cargo can catch.** On any leg but the first, an
+ *   ambiguous wall time resolves to the earliest pass at or after the previous arrival plus its
+ *   dwell — a printed timetable never says which pass it means. When neither pass is that late,
+ *   it resolves to the earlier pass as above, and the connection is missed. A skipped hour, and
+ *   the first leg, which has no arrival to wait for, keep the rule above.
+ * - `duration` follows `transitTime`: time units are elapsed time, a day is exactly 24 hours,
+ *   and calendar units (years, months, weeks) return `null`. `transitTime` accepts a negative
+ *   duration (to recover a departure from an arrival), but a leg cannot arrive before it
+ *   departs, so a negative leg is invalid input here and returns `null` (`-PT0S` is zero).
+ * - `mode`, `origin` and `destination` are opaque string tags echoed onto each `LegTime` and
+ *   absent when not supplied; GMT does not resolve them to zones — `timeZone` is the caller's
+ *   fact.
+ * - `eta` is the last leg's `localArrival`, so a single-leg schedule is exactly `transitTime`
+ *   composed with `etaAtZone`.
+ * - An empty legs array is valid vacuous input and returns `{ eta: "", legTimes: [] }`;
+ *   malformed input (a non-array, a non-object leg, an invalid field) returns `null`.
+ * - Returns `null` on invalid input.
+ *
+ * @param legs the journey's legs, in travel order
+ * @param options The zone a zoneless first-leg departure is read in
+ * @returns the final local ETA and each leg's arrival, local arrival and dwell, or null on invalid input
+ *
+ * @example scheduleDelivery([{ departure: "2024-06-15T10:00:00Z", duration: "PT36H", timeZone: "Asia/Tokyo" }]) // { eta: "2024-06-17T07:00:00+09:00[Asia/Tokyo]", legTimes: [{ arrival: "2024-06-16T22:00:00Z", localArrival: "2024-06-17T07:00:00+09:00[Asia/Tokyo]", dwellAfter: "PT0S" }] }
+ * @example scheduleDelivery([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { duration: "PT5H", timeZone: "Asia/Tokyo" }]) // { eta: "2024-06-16T02:00:00+09:00[Asia/Tokyo]", legTimes: [{ arrival: "2024-06-15T10:00:00Z", localArrival: "2024-06-15T10:00:00+00:00[UTC]", dwellAfter: "PT2H" }, { arrival: "2024-06-15T17:00:00Z", localArrival: "2024-06-16T02:00:00+09:00[Asia/Tokyo]", dwellAfter: "PT0S" }] } (the second leg leaves at 12:00Z, after the dwell)
+ * @example scheduleDelivery([{ departure: "2024-06-15T10:00:00Z", duration: "PT1H", timeZone: "UTC", mode: "ship" }]) // { eta: "2024-06-15T11:00:00+00:00[UTC]", legTimes: [{ arrival: "2024-06-15T11:00:00Z", localArrival: "2024-06-15T11:00:00+00:00[UTC]", dwellAfter: "PT0S", mode: "ship" }] } (tags echo back; unsupplied tag keys stay absent)
+ * @example scheduleDelivery([{ departure: "2024-06-15T10:00:00", duration: "PT1H", timeZone: "UTC" }], { startTimeZone: "America/New_York" }) // { eta: "2024-06-15T15:00:00+00:00[UTC]", legTimes: [{ arrival: "2024-06-15T15:00:00Z", localArrival: "2024-06-15T15:00:00+00:00[UTC]", dwellAfter: "PT0S" }] } (a published 10:00 wall time, read in New York)
+ * @example scheduleDelivery([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { departure: "2024-06-15T13:00:00", duration: "PT1H", timeZone: "UTC" }]) // { eta: "2024-06-15T14:00:00+00:00[UTC]", legTimes: [{ arrival: "2024-06-15T10:00:00Z", localArrival: "2024-06-15T10:00:00+00:00[UTC]", dwellAfter: "PT2H" }, { arrival: "2024-06-15T14:00:00Z", localArrival: "2024-06-15T14:00:00+00:00[UTC]", dwellAfter: "PT0S" }] } (leg 2's zoneless 13:00 is read in leg 1's UTC destination zone, not startTimeZone, since none was supplied)
+ * @example scheduleDelivery([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { departure: "2024-06-15T11:00:00", duration: "PT1H", timeZone: "UTC" }]) // null (leg 2's zoneless 11:00, read in UTC, falls inside leg 1's dwell: a missed connection)
+ * @example scheduleDelivery([]) // { eta: "", legTimes: [] }
+ * @example scheduleDelivery([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { departure: "2024-06-15T11:00:00Z", duration: "PT1H", timeZone: "UTC" }]) // null (the scheduled connection leaves inside the dwell: a missed connection)
+ * @example scheduleDelivery([{ departure: "2024-06-15T10:00:00", duration: "PT1H", timeZone: "UTC" }]) // null (a zoneless departure without startTimeZone is not a moment)
+ * @example scheduleDelivery([{ departure: "2024-06-15T10:00:00Z", duration: "-PT1H", timeZone: "UTC" }]) // null (a leg cannot arrive before it departs)
+ * @example scheduleDelivery([{ duration: "PT1H", timeZone: "UTC" }]) // null (the first leg needs a departure)
+ * @example scheduleDelivery([{ departure: "2024-06-15T10:00:00Z", duration: "P1M", timeZone: "UTC" }]) // null (calendar units need a reference point)
+ * @example scheduleDelivery("legs") // null
+ */
+export function scheduleDelivery(legs, options) {
+    try {
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const startTimeZone = options?.startTimeZone;
+        if (startTimeZone !== undefined && !isValidTimeZone(startTimeZone)) {
+            return null;
+        }
+        if (!Array.isArray(legs)) {
+            return null;
+        }
+        const legTimes = chainLegs(legs, startTimeZone);
+        if (legTimes === null) {
+            return null;
+        }
+        // An empty legs array is the vacuous schedule: eta is "" only there.
+        const last = legTimes.at(-1);
+        return { eta: last === undefined ? "" : last.localArrival, legTimes };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/transport/calculate/transitTime.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Add a transit duration to a departure and return the arrival, in the departure's own zone.
+ *
+ * The first of the three shared transport operations: a leg is a departure plus how long it
+ * takes. Every mode publishes it that way, and every mode gets the same thing wrong — a leg
+ * that crosses a DST transition is a fixed number of *elapsed* hours, not a wall-clock
+ * interval, so the local arrival time reflects the shift.
+ *
+ * - **Transit time is exact time.** Hours, minutes, seconds and fractions are added as elapsed
+ *   time, and a day component means 24 hours, exactly. That is TC39 Temporal's rule:
+ *   `Duration.prototype.round` and `total` without a `relativeTo` treat a day as 24 hours and
+ *   require a `relativeTo` for weeks, months and years. A 26-hour leg that starts the evening
+ *   before a spring-forward arrives at a wall time one hour later than a wall-clock reading would
+ *   suggest, because that is when the vessel, train or aircraft actually gets there.
+ * - **Calendar units are refused.** A `duration` with years, months or weeks returns `""`: no
+ *   leg takes "a month" in a sense that time arithmetic can fix without a reference point, and
+ *   Temporal's `round` and `total` require a `relativeTo` for them. Scheduled connections that
+ *   are dated rather than timed belong to `scheduleDelivery`.
+ * - **The departure's zone is preserved.** A bracketed IANA zone (`…-05:00[America/New_York]`)
+ *   stays that zone, so the arrival's offset is whatever is in force there at arrival. A `Z`
+ *   instant returns a `Z` instant; an offset-only instant keeps its offset, written exactly as
+ *   the departure wrote it, sub-minute offsets such as `+05:30:15` included (an offset is not a
+ *   zone, so nothing else can be inferred from it — see `toOffsetInstant`). A bracketed zone
+ *   that does not exist, or that contradicts its offset, is rejected as `isValidZonedDateTime`
+ *   rejects it; it does not fall back to the offset. An offset written to the minute that is the
+ *   zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) agrees with the
+ *   zone, as Temporal writes and reads it, and names the instant the zone gives.
+ * - **One zoned departure in range is refused.** A zoned departure is read as
+ *   `Temporal.ZonedDateTime.from` reads it, which rejects a local date of −271821-04-19. A zone
+ *   west of Greenwich shows that date for the first hours of the instant range, so a departure
+ *   written there (`-271821-04-19T23:59:00-00:01[Europe/London]`) returns `""`, although
+ *   `etaAtZone` writes it and `scheduleDeviation` reads it. Pass the instant in `Z` form.
+ * - **Local-time resolution policy (`"compatible"`).** A departure written as a wall time with a
+ *   bracketed zone and no offset is resolved in that zone with the `"compatible"` policy,
+ *   Temporal's default and `resolveLocal`'s. An **ambiguous** wall time — a fall-back hour the
+ *   clock ran through twice — resolves to the **earlier** instant:
+ *   `2024-11-03T01:30:00[America/New_York]` is `01:30-04:00`. A **nonexistent** one — a
+ *   spring-forward hour the clock skipped — resolves to the **later** instant:
+ *   `2024-03-10T02:30:00[America/New_York]` is `03:30-04:00`. Write the offset to name the other
+ *   pass of a repeated hour; a departure that carries its offset is never re-resolved.
+ * - RFC 9557 annotations are read as `Temporal.Instant.from` reads them: a bracket without `=`
+ *   is a time zone, and a `key=value` bracket with an unknown key is ignored when elective and
+ *   rejected when critical (`[!…]`). A calendar on a departure without a zone is accepted and
+ *   changes nothing, since an instant has no calendar; a zoned departure's calendar must be ISO,
+ *   as `isValidZonedDateTime` requires.
+ * - A negative duration is allowed and moves backwards; that is how a departure is recovered
+ *   from an arrival.
+ * - Returns `""` when `departure` is not a zoned datetime or instant string, or `duration` is
+ *   not an ISO 8601 duration.
+ *
+ * @param departure ISO 8601 zoned datetime (bracketed zone) or instant string (`Z` or offset)
+ * @param duration ISO 8601 duration of the leg; time units and 24-hour days only
+ * @returns the arrival in the departure's zone or offset form, or "" on invalid input
+ *
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "PT2H30M") // "2024-06-15T12:30:00-04:00[America/New_York]"
+ * @example transitTime("2024-03-09T23:00:00-05:00[America/New_York]", "PT4H") // "2024-03-10T04:00:00-04:00[America/New_York]" (four elapsed hours across the spring-forward, so the wall clock reads 04:00, not 03:00)
+ * @example transitTime("2024-03-09T12:00:00-05:00[America/New_York]", "P1D") // "2024-03-10T13:00:00-04:00[America/New_York]" (a day is 24 elapsed hours, not "the same wall time tomorrow")
+ * @example transitTime("2024-06-15T10:00:00Z", "PT36H") // "2024-06-16T22:00:00Z"
+ * @example transitTime("2024-06-15T10:00:00+09:00", "PT1H") // "2024-06-15T11:00:00+09:00" (an offset stays an offset)
+ * @example transitTime("2024-06-15T10:00:00+05:30:15", "PT1H") // "2024-06-15T11:00:00+05:30:15" (a sub-minute offset is kept as written)
+ * @example transitTime("2024-06-15T10:00:00Z[foo=bar]", "PT1H") // "2024-06-15T11:00:00Z" (an elective unknown annotation is ignored)
+ * @example transitTime("2024-06-15T12:30:00-04:00[America/New_York]", "-PT2H30M") // "2024-06-15T10:00:00-04:00[America/New_York]"
+ * @example transitTime("2024-11-03T01:30:00[America/New_York]", "PT0S") // "2024-11-03T01:30:00-04:00[America/New_York]" (an ambiguous wall time resolves to the earlier instant)
+ * @example transitTime("2024-03-10T02:30:00[America/New_York]", "PT0S") // "2024-03-10T03:30:00-04:00[America/New_York]" (a nonexistent wall time resolves to the later instant)
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "P1M") // "" (calendar units need a reference point)
+ * @example transitTime("2024-06-15T10:00:00-05:00[America/New_York]", "PT2H") // "" (New York is -04:00 in June: the offset contradicts the zone)
+ * @example transitTime("-271821-04-19T23:59:00-00:01[Europe/London]", "PT0S") // "" (a zoned string on a local date before Temporal's date range)
+ * @example transitTime("2024-06-15T10:00:00", "PT2H") // "" (no zone and no offset: not a moment)
+ * @example transitTime("2024-06-15T10:00:00Z", "2 hours") // ""
+ */
+export declare function transitTime(departure: string, duration: string): string;

package/dist/transport/calculate/transitTime.js

@@ -0,0 +1,101 @@
+import { exactDurationNanoseconds, readExactMoment, writeExactMoment, } from "../../internal/index.js";
+/**
+ * Add a transit duration to a departure and return the arrival, in the departure's own zone.
+ *
+ * The first of the three shared transport operations: a leg is a departure plus how long it
+ * takes. Every mode publishes it that way, and every mode gets the same thing wrong — a leg
+ * that crosses a DST transition is a fixed number of *elapsed* hours, not a wall-clock
+ * interval, so the local arrival time reflects the shift.
+ *
+ * - **Transit time is exact time.** Hours, minutes, seconds and fractions are added as elapsed
+ *   time, and a day component means 24 hours, exactly. That is TC39 Temporal's rule:
+ *   `Duration.prototype.round` and `total` without a `relativeTo` treat a day as 24 hours and
+ *   require a `relativeTo` for weeks, months and years. A 26-hour leg that starts the evening
+ *   before a spring-forward arrives at a wall time one hour later than a wall-clock reading would
+ *   suggest, because that is when the vessel, train or aircraft actually gets there.
+ * - **Calendar units are refused.** A `duration` with years, months or weeks returns `""`: no
+ *   leg takes "a month" in a sense that time arithmetic can fix without a reference point, and
+ *   Temporal's `round` and `total` require a `relativeTo` for them. Scheduled connections that
+ *   are dated rather than timed belong to `scheduleDelivery`.
+ * - **The departure's zone is preserved.** A bracketed IANA zone (`…-05:00[America/New_York]`)
+ *   stays that zone, so the arrival's offset is whatever is in force there at arrival. A `Z`
+ *   instant returns a `Z` instant; an offset-only instant keeps its offset, written exactly as
+ *   the departure wrote it, sub-minute offsets such as `+05:30:15` included (an offset is not a
+ *   zone, so nothing else can be inferred from it — see `toOffsetInstant`). A bracketed zone
+ *   that does not exist, or that contradicts its offset, is rejected as `isValidZonedDateTime`
+ *   rejects it; it does not fall back to the offset. An offset written to the minute that is the
+ *   zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) agrees with the
+ *   zone, as Temporal writes and reads it, and names the instant the zone gives.
+ * - **One zoned departure in range is refused.** A zoned departure is read as
+ *   `Temporal.ZonedDateTime.from` reads it, which rejects a local date of −271821-04-19. A zone
+ *   west of Greenwich shows that date for the first hours of the instant range, so a departure
+ *   written there (`-271821-04-19T23:59:00-00:01[Europe/London]`) returns `""`, although
+ *   `etaAtZone` writes it and `scheduleDeviation` reads it. Pass the instant in `Z` form.
+ * - **Local-time resolution policy (`"compatible"`).** A departure written as a wall time with a
+ *   bracketed zone and no offset is resolved in that zone with the `"compatible"` policy,
+ *   Temporal's default and `resolveLocal`'s. An **ambiguous** wall time — a fall-back hour the
+ *   clock ran through twice — resolves to the **earlier** instant:
+ *   `2024-11-03T01:30:00[America/New_York]` is `01:30-04:00`. A **nonexistent** one — a
+ *   spring-forward hour the clock skipped — resolves to the **later** instant:
+ *   `2024-03-10T02:30:00[America/New_York]` is `03:30-04:00`. Write the offset to name the other
+ *   pass of a repeated hour; a departure that carries its offset is never re-resolved.
+ * - RFC 9557 annotations are read as `Temporal.Instant.from` reads them: a bracket without `=`
+ *   is a time zone, and a `key=value` bracket with an unknown key is ignored when elective and
+ *   rejected when critical (`[!…]`). A calendar on a departure without a zone is accepted and
+ *   changes nothing, since an instant has no calendar; a zoned departure's calendar must be ISO,
+ *   as `isValidZonedDateTime` requires.
+ * - A negative duration is allowed and moves backwards; that is how a departure is recovered
+ *   from an arrival.
+ * - Returns `""` when `departure` is not a zoned datetime or instant string, or `duration` is
+ *   not an ISO 8601 duration.
+ *
+ * @param departure ISO 8601 zoned datetime (bracketed zone) or instant string (`Z` or offset)
+ * @param duration ISO 8601 duration of the leg; time units and 24-hour days only
+ * @returns the arrival in the departure's zone or offset form, or "" on invalid input
+ *
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "PT2H30M") // "2024-06-15T12:30:00-04:00[America/New_York]"
+ * @example transitTime("2024-03-09T23:00:00-05:00[America/New_York]", "PT4H") // "2024-03-10T04:00:00-04:00[America/New_York]" (four elapsed hours across the spring-forward, so the wall clock reads 04:00, not 03:00)
+ * @example transitTime("2024-03-09T12:00:00-05:00[America/New_York]", "P1D") // "2024-03-10T13:00:00-04:00[America/New_York]" (a day is 24 elapsed hours, not "the same wall time tomorrow")
+ * @example transitTime("2024-06-15T10:00:00Z", "PT36H") // "2024-06-16T22:00:00Z"
+ * @example transitTime("2024-06-15T10:00:00+09:00", "PT1H") // "2024-06-15T11:00:00+09:00" (an offset stays an offset)
+ * @example transitTime("2024-06-15T10:00:00+05:30:15", "PT1H") // "2024-06-15T11:00:00+05:30:15" (a sub-minute offset is kept as written)
+ * @example transitTime("2024-06-15T10:00:00Z[foo=bar]", "PT1H") // "2024-06-15T11:00:00Z" (an elective unknown annotation is ignored)
+ * @example transitTime("2024-06-15T12:30:00-04:00[America/New_York]", "-PT2H30M") // "2024-06-15T10:00:00-04:00[America/New_York]"
+ * @example transitTime("2024-11-03T01:30:00[America/New_York]", "PT0S") // "2024-11-03T01:30:00-04:00[America/New_York]" (an ambiguous wall time resolves to the earlier instant)
+ * @example transitTime("2024-03-10T02:30:00[America/New_York]", "PT0S") // "2024-03-10T03:30:00-04:00[America/New_York]" (a nonexistent wall time resolves to the later instant)
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "P1M") // "" (calendar units need a reference point)
+ * @example transitTime("2024-06-15T10:00:00-05:00[America/New_York]", "PT2H") // "" (New York is -04:00 in June: the offset contradicts the zone)
+ * @example transitTime("-271821-04-19T23:59:00-00:01[Europe/London]", "PT0S") // "" (a zoned string on a local date before Temporal's date range)
+ * @example transitTime("2024-06-15T10:00:00", "PT2H") // "" (no zone and no offset: not a moment)
+ * @example transitTime("2024-06-15T10:00:00Z", "2 hours") // ""
+ */
+export function transitTime(departure, duration) {
+    // A non-string would reach the regex tests below, which coerce it: a throwing `toString`, a
+    // Symbol or a hostile Proxy would escape. Refuse it before any read.
+    if (typeof departure !== "string" || typeof duration !== "string") {
+        return "";
+    }
+    try {
+        return addLeg(departure, duration);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}
+/** `transitTime` for two strings, without the guard. */
+function addLeg(departure, duration) {
+    // Days are 24 exact hours; years, months and weeks are refused.
+    const amount = exactDurationNanoseconds(duration);
+    if (amount === null) {
+        return "";
+    }
+    // A string that names a zone must name a real one that agrees with its offset; only a string
+    // that names none is read as an instant, keeping its offset text.
+    const moment = readExactMoment(departure);
+    if (moment === null) {
+        return "";
+    }
+    return writeExactMoment(moment.nanoseconds + amount, moment.notation);
+}

package/dist/transport/compare/classifyPunctuality.d.ts

@@ -0,0 +1,46 @@
+import type { Punctuality, PunctualityTolerance } from "../../types/index.js";
+/**
+ * Classify an arrival as early, on time or late against the caller's tolerance.
+ *
+ * "On time" without a stated tolerance is not a measurement, and the tolerance differs by mode:
+ * a 15-minute tolerance (`{ late: "PT15M" }`), a 60/120-minute pair compared side by side, or a
+ * day-based one (`{ late: "P1D", early: "P1D" }`). GMT holds no default; the caller states it.
+ *
+ * - The deviation is `scheduleDeviation`'s: `actual` minus `planned` in exact elapsed time, so a
+ *   delay across a DST transition is measured in real minutes, never wall-clock ones.
+ * - **Late** when the deviation is `late` or more: exactly 15 minutes against `PT15M` is late.
+ * - **Early** when `early` is given and the deviation is `-early` or less: exactly 10 minutes
+ *   early against `PT10M` is early.
+ * - **On time** only strictly inside the tolerance: after `-early` (when given) and before
+ *   `late`. Both boundaries belong to the outside. This convention is GMT's own, stated here, not
+ *   a reading of any rule.
+ * - **Without `early`, every early arrival is on time.** `early: undefined` is the same as
+ *   leaving it out; `early: null` is invalid.
+ * - `late: "PT0S"` leaves no on-time window after the plan: an arrival exactly on the plan is
+ *   late. `early: "PT0S"` leaves none before it: an arrival exactly on the plan is early (with a
+ *   non-zero `late`), because both boundaries are outside the on-time window. With both at
+ *   `"PT0S"`, nothing is on time; late is checked first, so the plan itself is late.
+ * - Tolerances are exact durations: a day is 24 hours; years, months and weeks return `null`, as
+ *   does a negative tolerance (`-PT0S` is zero).
+ * - Both times are an instant (`Z`/offset) or a zoned string, read as `scheduleDeviation` reads
+ *   them: the offset fixes the instant, and an offset written to the minute that is the
+ *   bracketed zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names
+ *   the instant the zone gives. Otherwise the bracket is not checked.
+ * - Returns `null` on invalid input.
+ *
+ * @param planned ISO 8601 instant or zoned datetime string of the planned time
+ * @param actual ISO 8601 instant or zoned datetime string of the actual time
+ * @param tolerance late (required) and early (optional) tolerances as ISO 8601 durations of exact time
+ * @returns "early", "onTime" or "late", or null on invalid input
+ *
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:14:59Z", { late: "PT15M" }) // "onTime"
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:15:00Z", { late: "PT15M" }) // "late" (exactly the tolerance is late)
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T08:00:00Z", { late: "PT15M" }) // "onTime" (without early, an early arrival is on time)
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T09:49:00Z", { late: "PT15M", early: "PT10M" }) // "early"
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T11:30:00Z", { late: "PT120M" }) // "onTime" (a 90-minute delay under a 120-minute tolerance)
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:00:00Z", { late: "PT15M", early: "PT0S" }) // "early" (exactly on the plan is on the early boundary, which is outside)
+ * @example classifyPunctuality("2024-11-03T01:30:00-04:00[America/New_York]", "2024-11-03T01:30:00-05:00[America/New_York]", { late: "PT15M" }) // "late" (the same wall time an hour later, across the fall-back)
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:14:00Z", { late: "-PT15M" }) // null (a negative tolerance)
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:14:00Z", { late: "P1W" }) // null (weeks need a reference point)
+ */
+export declare function classifyPunctuality(planned: string, actual: string, tolerance: PunctualityTolerance): Punctuality | null;

package/dist/transport/compare/classifyPunctuality.js

@@ -0,0 +1,64 @@
+import { parseInstantNanoseconds, parsePunctualityTolerance, punctualityOf, } from "../../internal/index.js";
+/**
+ * Classify an arrival as early, on time or late against the caller's tolerance.
+ *
+ * "On time" without a stated tolerance is not a measurement, and the tolerance differs by mode:
+ * a 15-minute tolerance (`{ late: "PT15M" }`), a 60/120-minute pair compared side by side, or a
+ * day-based one (`{ late: "P1D", early: "P1D" }`). GMT holds no default; the caller states it.
+ *
+ * - The deviation is `scheduleDeviation`'s: `actual` minus `planned` in exact elapsed time, so a
+ *   delay across a DST transition is measured in real minutes, never wall-clock ones.
+ * - **Late** when the deviation is `late` or more: exactly 15 minutes against `PT15M` is late.
+ * - **Early** when `early` is given and the deviation is `-early` or less: exactly 10 minutes
+ *   early against `PT10M` is early.
+ * - **On time** only strictly inside the tolerance: after `-early` (when given) and before
+ *   `late`. Both boundaries belong to the outside. This convention is GMT's own, stated here, not
+ *   a reading of any rule.
+ * - **Without `early`, every early arrival is on time.** `early: undefined` is the same as
+ *   leaving it out; `early: null` is invalid.
+ * - `late: "PT0S"` leaves no on-time window after the plan: an arrival exactly on the plan is
+ *   late. `early: "PT0S"` leaves none before it: an arrival exactly on the plan is early (with a
+ *   non-zero `late`), because both boundaries are outside the on-time window. With both at
+ *   `"PT0S"`, nothing is on time; late is checked first, so the plan itself is late.
+ * - Tolerances are exact durations: a day is 24 hours; years, months and weeks return `null`, as
+ *   does a negative tolerance (`-PT0S` is zero).
+ * - Both times are an instant (`Z`/offset) or a zoned string, read as `scheduleDeviation` reads
+ *   them: the offset fixes the instant, and an offset written to the minute that is the
+ *   bracketed zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names
+ *   the instant the zone gives. Otherwise the bracket is not checked.
+ * - Returns `null` on invalid input.
+ *
+ * @param planned ISO 8601 instant or zoned datetime string of the planned time
+ * @param actual ISO 8601 instant or zoned datetime string of the actual time
+ * @param tolerance late (required) and early (optional) tolerances as ISO 8601 durations of exact time
+ * @returns "early", "onTime" or "late", or null on invalid input
+ *
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:14:59Z", { late: "PT15M" }) // "onTime"
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:15:00Z", { late: "PT15M" }) // "late" (exactly the tolerance is late)
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T08:00:00Z", { late: "PT15M" }) // "onTime" (without early, an early arrival is on time)
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T09:49:00Z", { late: "PT15M", early: "PT10M" }) // "early"
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T11:30:00Z", { late: "PT120M" }) // "onTime" (a 90-minute delay under a 120-minute tolerance)
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:00:00Z", { late: "PT15M", early: "PT0S" }) // "early" (exactly on the plan is on the early boundary, which is outside)
+ * @example classifyPunctuality("2024-11-03T01:30:00-04:00[America/New_York]", "2024-11-03T01:30:00-05:00[America/New_York]", { late: "PT15M" }) // "late" (the same wall time an hour later, across the fall-back)
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:14:00Z", { late: "-PT15M" }) // null (a negative tolerance)
+ * @example classifyPunctuality("2024-06-15T10:00:00Z", "2024-06-15T10:14:00Z", { late: "P1W" }) // null (weeks need a reference point)
+ */
+export function classifyPunctuality(planned, actual, tolerance) {
+    try {
+        const bounds = parsePunctualityTolerance(tolerance);
+        if (bounds === null) {
+            return null;
+        }
+        const plannedNanoseconds = parseInstantNanoseconds(planned);
+        const actualNanoseconds = parseInstantNanoseconds(actual);
+        if (plannedNanoseconds === null || actualNanoseconds === null) {
+            return null;
+        }
+        return punctualityOf(actualNanoseconds - plannedNanoseconds, bounds);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/transport/compare/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./classifyPunctuality.js";
+export * from "./isPastCutoff.js";
+export * from "./scheduleDeviation.js";
+export * from "./timeToCutoff.js";

package/dist/transport/compare/index.js

@@ -0,0 +1,4 @@
+export * from "./classifyPunctuality.js";
+export * from "./isPastCutoff.js";
+export * from "./scheduleDeviation.js";
+export * from "./timeToCutoff.js";

package/dist/transport/compare/isPastCutoff.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Report whether a cut-off has passed.
+ *
+ * The window to meet a cut-off is half-open, `[…, cutoff)`: at the cut-off instant itself it
+ * has closed, so `now` equal to `cutoff` is past. This matches the half-open rule GMT's
+ * intervals follow, and `timeToCutoff`, which is `PT0S` there.
+ *
+ * - Both arguments are exact: an instant (`Z`/offset) or a zoned string, as `cutoffAt`
+ *   returns one. They are compared as instants, so the zone each is written in does not
+ *   matter, and the two passes of a repeated hour are told apart by their offsets.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a cut-off `cutoffAt` wrote is the instant it
+ *   computed, except a wall time repeated inside a sub-minute offset change, which reads as
+ *   its first pass (see `isValidInstant`). Otherwise the bracket is not checked: a zone that does not exist, or that
+ *   disagrees with the offset, changes nothing.
+ * - `now` is the caller's: GMT does not read the clock here, so the answer is reproducible.
+ * - Returns `false` on invalid input, including `cutoffAt`'s `""` sentinel — which reads as
+ *   "not past". Check the cut-off is not `""` before trusting a `false`.
+ *
+ * @param now ISO 8601 instant or zoned datetime string of the moment asked about
+ * @param cutoff ISO 8601 instant or zoned datetime string of the cut-off
+ * @returns true when now is at or after the cut-off, false otherwise or on invalid input
+ *
+ * @example isPastCutoff("2024-06-12T16:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // true
+ * @example isPastCutoff("2024-06-12T14:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // false
+ * @example isPastCutoff("2024-06-12T15:00:00Z", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // true (at the cut-off, the window has closed)
+ * @example isPastCutoff("2024-11-03T01:30:00-05:00[America/New_York]", "2024-11-03T01:30:00-04:00[America/New_York]") // true (the second 01:30 is an hour after the first)
+ * @example isPastCutoff("2024-06-12T16:00:00", "2024-06-12T17:00:00+02:00[Europe/Amsterdam]") // false (a zoneless now is not a moment)
+ * @example isPastCutoff("2024-06-12T16:00:00Z", "") // false
+ */
+export declare function isPastCutoff(now: string, cutoff: string): boolean;