@northguild/gmt 1.16.0 → 1.18.0

package/dist/transport/calculate/estimateDrift.js

@@ -0,0 +1,75 @@
+import { formatHourDuration, isOptionsArgument, nonNegativeExactDurationNanoseconds, parseTimestampEvents, } from "../../internal/index.js";
+/**
+ * Measure how far an estimate moved between its first and last revision.
+ *
+ * Schedule-reliability reporting asks how much an estimated arrival slid while it was being
+ * revised, and a revision far enough from the first estimate means something must be redone:
+ * rebooked, re-planned, renotified. The threshold is the caller's; the consequence is the
+ * consumer's.
+ *
+ * - Only `EST` records are read, in the order they were recorded (`recordedAt`). Two records at
+ *   the same instant are ordered by their place in the array, the later one last — the same tie
+ *   rule as `bestAvailable`. `PLN`, `REQ` and `ACT` records are validated and otherwise ignored.
+ * - `revisions` is the number of EST records, the first included.
+ * - `drift` is the last EST's `at` minus the first's, in exact elapsed time with hours as the
+ *   largest unit: positive when the estimate moved later, negative when earlier. Across a
+ *   fall-back night, 01:30 EDT to 01:30 EST is `PT1H`.
+ * - With `tolerance`, `exceedsTolerance` is `true` when the drift, in either direction, is
+ *   **greater** than the tolerance; exactly the tolerance is `false`. Without it, `null`.
+ * - `first` and `last` echo `at` exactly as written; both are instants (`Z`/offset) or zoned
+ *   strings compared as instants, 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` with fewer than two EST records — there is no drift from one sample — and on
+ *   invalid input: any invalid event, of any class, or an invalid, negative or calendar-unit
+ *   `tolerance`.
+ *
+ * @param events the event's timestamp records, in any order
+ * @param options The threshold the absolute drift is compared with
+ * @returns the first and last estimates, the drift, the revision count and the tolerance check (null with fewer than two EST records), or null on invalid input
+ *
+ * @example estimateDrift([{ classifier: "EST", at: "2024-06-20T08:00:00Z", recordedAt: "2024-06-01T00:00:00Z" }, { classifier: "EST", at: "2024-06-20T12:00:00Z", recordedAt: "2024-06-05T00:00:00Z" }, { classifier: "EST", at: "2024-06-20T17:00:00Z", recordedAt: "2024-06-10T00:00:00Z" }]) // { first: "2024-06-20T08:00:00Z", last: "2024-06-20T17:00:00Z", drift: "PT9H", revisions: 3, exceedsTolerance: null }
+ * @example estimateDrift([{ classifier: "EST", at: "2024-06-20T17:00:00Z", recordedAt: "2024-06-01T00:00:00Z" }, { classifier: "EST", at: "2024-06-20T08:00:00Z", recordedAt: "2024-06-10T00:00:00Z" }], { tolerance: "PT8H" }) // { first: "2024-06-20T17:00:00Z", last: "2024-06-20T08:00:00Z", drift: "-PT9H", revisions: 2, exceedsTolerance: true } (nine hours earlier exceeds eight)
+ * @example estimateDrift([{ classifier: "EST", at: "2024-06-20T08:00:00Z", recordedAt: "2024-06-01T00:00:00Z" }, { classifier: "EST", at: "2024-06-20T15:00:00Z", recordedAt: "2024-06-10T00:00:00Z" }], { tolerance: "PT8H" }) // { first: "2024-06-20T08:00:00Z", last: "2024-06-20T15:00:00Z", drift: "PT7H", revisions: 2, exceedsTolerance: false }
+ * @example estimateDrift([{ classifier: "EST", at: "2024-06-20T08:00:00Z", recordedAt: "2024-06-01T00:00:00Z" }]) // null (no drift from one sample)
+ * @example estimateDrift([{ classifier: "EST", at: "2024-06-20T08:00:00Z", recordedAt: "2024-06-01T00:00:00Z" }, { classifier: "EST", at: "2024-06-20T15:00:00Z", recordedAt: "2024-06-10T00:00:00Z" }], { tolerance: "P1W" }) // null (weeks need a reference point)
+ */
+export function estimateDrift(events, options) {
+    try {
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const tolerance = options?.tolerance;
+        const toleranceNanoseconds = tolerance === undefined
+            ? null
+            : nonNegativeExactDurationNanoseconds(tolerance);
+        if (tolerance !== undefined && toleranceNanoseconds === null) {
+            return null;
+        }
+        const parsed = parseTimestampEvents(events);
+        if (parsed === null) {
+            return null;
+        }
+        const estimates = parsed.filter((event) => event.classifier === "EST");
+        const first = estimates[0];
+        const last = estimates[estimates.length - 1];
+        if (estimates.length < 2 || first === undefined || last === undefined) {
+            return null;
+        }
+        const drift = last.atNanoseconds - first.atNanoseconds;
+        const magnitude = drift < 0n ? -drift : drift;
+        return {
+            first: first.at,
+            last: last.at,
+            drift: `${drift < 0n ? "-" : ""}${formatHourDuration(magnitude)}`,
+            revisions: estimates.length,
+            exceedsTolerance: toleranceNanoseconds === null ? null : magnitude > toleranceNanoseconds,
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,10 @@
+export * from "./bestAvailable.js";
+export * from "./crossingTime.js";
+export * from "./cutoffAt.js";
+export * from "./cutoffSchedule.js";
+export * from "./dwellTime.js";
+export * from "./estimateDrift.js";
+export * from "./nextDeparture.js";
+export * from "./punctualityRate.js";
+export * from "./scheduleDelivery.js";
+export * from "./transitTime.js";

package/dist/transport/calculate/index.js

@@ -0,0 +1,10 @@
+export * from "./bestAvailable.js";
+export * from "./crossingTime.js";
+export * from "./cutoffAt.js";
+export * from "./cutoffSchedule.js";
+export * from "./dwellTime.js";
+export * from "./estimateDrift.js";
+export * from "./nextDeparture.js";
+export * from "./punctualityRate.js";
+export * from "./scheduleDelivery.js";
+export * from "./transitTime.js";

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

@@ -0,0 +1,78 @@
+/**
+ * A headway service: a departure every `headway` from `from`, up to (not including) `to` — the
+ * shape of a GTFS `frequencies.txt` row (`headway_secs`, `start_time`, `end_time`; GTFS Schedule
+ * Reference, https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#frequenciestxt).
+ *
+ * The departures are modelled as GTFS `exact_times=1` (schedule-based): each `from + k × headway`
+ * is a real departure. For a frequency-based service (`exact_times=0`, "a bus every 20 minutes"
+ * with no published times) the result is a nominal slot, not a timetabled departure.
+ */
+export interface Headway {
+    /**
+     * The ISO 8601 duration between departures: exact time (a day is 24 hours), greater than zero.
+     */
+    headway: string;
+    /** The first departure, an exact moment: an instant (`Z`/offset) or a zoned string. */
+    from: string;
+    /** The end of the service window, excluded: an exact moment after `from`. */
+    to: string;
+}
+/** Options for `nextDeparture`. */
+export interface NextDepartureOptions {
+    /**
+     * The ISO 8601 duration the connection needs after `after` before a departure can be made:
+     * exact time (a day is 24 hours), not negative.
+     *
+     * @defaultValue `"PT0S"`
+     */
+    minimumConnection?: string;
+}
+/**
+ * Find the next departure a connection can make: the first scheduled departure at or after
+ * `after` plus the minimum connection time.
+ *
+ * This is timetable lookup, not routing: it answers "which departure does this arrival make",
+ * the explicit `departure` a `scheduleDelivery` leg takes. Choosing among routes is the
+ * consumer's.
+ *
+ * - **The threshold is `after` plus `minimumConnection`, in exact time.** A departure exactly at
+ *   the threshold is made: a zero-slack connection is feasible, as in `scheduleDelivery`. The
+ *   connection follows `transitTime`'s duration rule (a day is 24 hours; years, months and weeks
+ *   return `""`) and may not be negative.
+ * - **List form** (`string[]`): the earliest entry at or after the threshold, in any order. Two
+ *   entries at the same instant go to the first in the list. The entry is returned **exactly as
+ *   written**, so it can be passed straight to `scheduleDelivery` as a leg's `departure`. An empty
+ *   list, or no entry late enough, returns `""`.
+ * - **Headway form** (`{ headway, from, to }`): departures every `headway` from `from`, in the
+ *   half-open window `[from, to)` — `to` itself is never a departure, as a GTFS
+ *   `frequencies.txt` `end_time` is not. Departures are `from + k × headway` in exact time, so
+ *   across a DST transition they keep their spacing and the wall clock shifts. The result is
+ *   written the way `from` was written: in its zone, at its offset exactly as written, or as a
+ *   `Z` instant. A headway that is not greater than zero, or `to` at or before `from`, returns
+ *   `""`, as does a threshold past the last departure. This models GTFS `exact_times=1`
+ *   (schedule-based) service; for frequency-based service (`exact_times=0`) the result is a
+ *   nominal slot, not a timetabled departure.
+ * - **Every moment must carry its offset** — `after`, each entry, `from` and `to`: an instant
+ *   (`Z`/offset), or a zoned string with its offset, whose bracketed zone must be real and agree
+ *   with that offset, as `transitTime` reads a departure. A zoned wall time without an offset is
+ *   refused, since in a repeated fall-back hour it names two departures, and a zoneless wall time
+ *   names none; both return `""`. One invalid entry invalidates the whole list, never a partial
+ *   answer.
+ * - Returns `""` on invalid input or when no departure qualifies.
+ *
+ * @param after ISO 8601 instant or zoned datetime string of the arrival that must connect
+ * @param timetable the departures as exact moments, or a headway service `{ headway, from, to }`
+ * @param options The connection time needed before a departure can be made
+ * @returns the departure (a list entry as written, or a headway departure in from's notation; "" when none qualifies), or "" on invalid input
+ *
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T08:00:00Z", "2024-06-15T09:30:00Z", "2024-06-15T11:00:00Z"]) // "2024-06-15T09:30:00Z"
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T08:00:00Z", "2024-06-15T09:30:00Z", "2024-06-15T11:00:00Z"], { minimumConnection: "PT45M" }) // "2024-06-15T11:00:00Z" (a 45-minute connection misses the 09:30)
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T05:30:00-04:00[America/New_York]"]) // "2024-06-15T05:30:00-04:00[America/New_York]" (echoed as written)
+ * @example nextDeparture("2024-06-15T06:05:00+02:00", { headway: "PT20M", from: "2024-06-15T06:00:00+02:00", to: "2024-06-15T09:00:00+02:00" }) // "2024-06-15T06:20:00+02:00"
+ * @example nextDeparture("2024-06-15T09:00:00+02:00", { headway: "PT20M", from: "2024-06-15T06:00:00+02:00", to: "2024-06-15T09:00:00+02:00" }) // "" (to is excluded)
+ * @example nextDeparture("2024-11-03T01:30:00-04:00[America/New_York]", { headway: "PT1H", from: "2024-11-03T00:00:00-04:00[America/New_York]", to: "2024-11-03T04:00:00-05:00[America/New_York]" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (hourly in exact time: the repeated hour's second pass)
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T09:30:00"]) // "" (a timetable entry needs an offset)
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T09:30:00[Europe/London]"]) // "" (a zoned entry needs its offset too)
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T09:30:00Z"], { minimumConnection: "-PT5M" }) // "" (a negative connection)
+ */
+export declare function nextDeparture(after: string, timetable: readonly string[] | Headway, options?: NextDepartureOptions): string;

package/dist/transport/calculate/nextDeparture.js

@@ -0,0 +1,131 @@
+import { exactDurationNanoseconds, isObject, isOptionsArgument, nonNegativeExactDurationNanoseconds, readExactMoment, writeExactMoment, } from "../../internal/index.js";
+import { hasInstantShape } from "../../internal/isoStringBody.js";
+/**
+ * A moment that carries its own offset (`Z`, `±HH:MM`, or a zoned string with one), read as
+ * `transitTime` reads a departure, or `null`. A zoned wall time without an offset is refused: in
+ * a repeated hour it names two instants, and a timetable must say which.
+ */
+function readTimetableMoment(value) {
+    return typeof value === "string" && hasInstantShape(value)
+        ? readExactMoment(value)
+        : null;
+}
+/** The earliest entry at or after `threshold`, echoed as written; `""` when none, or one is invalid. */
+function listDeparture(threshold, entries) {
+    let best = null;
+    for (const entry of entries) {
+        const moment = readTimetableMoment(entry);
+        if (moment === null) {
+            return "";
+        }
+        // Strictly earlier replaces, so of two entries at the same instant the first is kept.
+        if (moment.nanoseconds >= threshold &&
+            (best === null || moment.nanoseconds < best.nanoseconds)) {
+            best = { entry: entry, nanoseconds: moment.nanoseconds };
+        }
+    }
+    return best === null ? "" : best.entry;
+}
+/**
+ * The first `from + k × headway` at or after `threshold` and before `to`, written the way `from`
+ * was written; `""` when none. Computed, never stepped: `k` is the ceiling of the distance over
+ * the headway, in bigint nanoseconds, so a long window costs nothing and every candidate is
+ * before `to`, inside the instant range.
+ */
+function headwayDeparture(threshold, service) {
+    const { headway, from, to } = service;
+    const step = exactDurationNanoseconds(headway);
+    const start = readTimetableMoment(from);
+    const end = readTimetableMoment(to);
+    if (step === null ||
+        step <= 0n ||
+        start === null ||
+        end === null ||
+        start.nanoseconds >= end.nanoseconds) {
+        return "";
+    }
+    const behind = threshold - start.nanoseconds;
+    const steps = behind <= 0n ? 0n : (behind + step - 1n) / step;
+    const departure = start.nanoseconds + steps * step;
+    return departure < end.nanoseconds
+        ? writeExactMoment(departure, start.notation)
+        : "";
+}
+/**
+ * Find the next departure a connection can make: the first scheduled departure at or after
+ * `after` plus the minimum connection time.
+ *
+ * This is timetable lookup, not routing: it answers "which departure does this arrival make",
+ * the explicit `departure` a `scheduleDelivery` leg takes. Choosing among routes is the
+ * consumer's.
+ *
+ * - **The threshold is `after` plus `minimumConnection`, in exact time.** A departure exactly at
+ *   the threshold is made: a zero-slack connection is feasible, as in `scheduleDelivery`. The
+ *   connection follows `transitTime`'s duration rule (a day is 24 hours; years, months and weeks
+ *   return `""`) and may not be negative.
+ * - **List form** (`string[]`): the earliest entry at or after the threshold, in any order. Two
+ *   entries at the same instant go to the first in the list. The entry is returned **exactly as
+ *   written**, so it can be passed straight to `scheduleDelivery` as a leg's `departure`. An empty
+ *   list, or no entry late enough, returns `""`.
+ * - **Headway form** (`{ headway, from, to }`): departures every `headway` from `from`, in the
+ *   half-open window `[from, to)` — `to` itself is never a departure, as a GTFS
+ *   `frequencies.txt` `end_time` is not. Departures are `from + k × headway` in exact time, so
+ *   across a DST transition they keep their spacing and the wall clock shifts. The result is
+ *   written the way `from` was written: in its zone, at its offset exactly as written, or as a
+ *   `Z` instant. A headway that is not greater than zero, or `to` at or before `from`, returns
+ *   `""`, as does a threshold past the last departure. This models GTFS `exact_times=1`
+ *   (schedule-based) service; for frequency-based service (`exact_times=0`) the result is a
+ *   nominal slot, not a timetabled departure.
+ * - **Every moment must carry its offset** — `after`, each entry, `from` and `to`: an instant
+ *   (`Z`/offset), or a zoned string with its offset, whose bracketed zone must be real and agree
+ *   with that offset, as `transitTime` reads a departure. A zoned wall time without an offset is
+ *   refused, since in a repeated fall-back hour it names two departures, and a zoneless wall time
+ *   names none; both return `""`. One invalid entry invalidates the whole list, never a partial
+ *   answer.
+ * - Returns `""` on invalid input or when no departure qualifies.
+ *
+ * @param after ISO 8601 instant or zoned datetime string of the arrival that must connect
+ * @param timetable the departures as exact moments, or a headway service `{ headway, from, to }`
+ * @param options The connection time needed before a departure can be made
+ * @returns the departure (a list entry as written, or a headway departure in from's notation; "" when none qualifies), or "" on invalid input
+ *
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T08:00:00Z", "2024-06-15T09:30:00Z", "2024-06-15T11:00:00Z"]) // "2024-06-15T09:30:00Z"
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T08:00:00Z", "2024-06-15T09:30:00Z", "2024-06-15T11:00:00Z"], { minimumConnection: "PT45M" }) // "2024-06-15T11:00:00Z" (a 45-minute connection misses the 09:30)
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T05:30:00-04:00[America/New_York]"]) // "2024-06-15T05:30:00-04:00[America/New_York]" (echoed as written)
+ * @example nextDeparture("2024-06-15T06:05:00+02:00", { headway: "PT20M", from: "2024-06-15T06:00:00+02:00", to: "2024-06-15T09:00:00+02:00" }) // "2024-06-15T06:20:00+02:00"
+ * @example nextDeparture("2024-06-15T09:00:00+02:00", { headway: "PT20M", from: "2024-06-15T06:00:00+02:00", to: "2024-06-15T09:00:00+02:00" }) // "" (to is excluded)
+ * @example nextDeparture("2024-11-03T01:30:00-04:00[America/New_York]", { headway: "PT1H", from: "2024-11-03T00:00:00-04:00[America/New_York]", to: "2024-11-03T04:00:00-05:00[America/New_York]" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (hourly in exact time: the repeated hour's second pass)
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T09:30:00"]) // "" (a timetable entry needs an offset)
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T09:30:00[Europe/London]"]) // "" (a zoned entry needs its offset too)
+ * @example nextDeparture("2024-06-15T09:00:00Z", ["2024-06-15T09:30:00Z"], { minimumConnection: "-PT5M" }) // "" (a negative connection)
+ */
+export function nextDeparture(after, timetable, options) {
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const connection = options?.minimumConnection;
+        const connectionNanoseconds = connection === undefined
+            ? 0n
+            : nonNegativeExactDurationNanoseconds(connection);
+        if (connectionNanoseconds === null) {
+            return "";
+        }
+        const arrival = readTimetableMoment(after);
+        if (arrival === null) {
+            return "";
+        }
+        const threshold = arrival.nanoseconds + connectionNanoseconds;
+        if (Array.isArray(timetable)) {
+            return listDeparture(threshold, timetable);
+        }
+        return isObject(timetable)
+            ? headwayDeparture(threshold, timetable)
+            : "";
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,42 @@
+import type { PunctualityTolerance } from "../../types/index.js";
+/** One planned/actual pair for `punctualityRate`. */
+export interface PlannedActual {
+    /** The planned time, as an ISO 8601 instant or zoned datetime string. */
+    planned: string;
+    /** The actual time, as an ISO 8601 instant or zoned datetime string. */
+    actual: string;
+}
+/** What `punctualityRate` returns: the on-time count, the total, and their ratio. */
+export interface OnTimeRate {
+    /** The number of pairs `classifyPunctuality` calls `"onTime"`. */
+    onTime: number;
+    /** Every pair counted. */
+    total: number;
+    /** The on-time share, `onTime / total`, from 0 to 1. */
+    rate: number;
+}
+/**
+ * The share of planned/actual pairs that were on time under one tolerance.
+ *
+ * A rate is a count under a stated tolerance: the same arrivals give a different rate under a
+ * 60-minute tolerance than under a 120-minute one, so the tolerance travels with the number.
+ *
+ * - Each pair is classified by `classifyPunctuality`'s rule under the same tolerance: `late` and
+ *   `early` are read once, before any pair, so the whole list is judged under one tolerance.
+ *   Only `"onTime"` counts: with an `early` tolerance, an early arrival is **not** on time;
+ *   without one, it is.
+ * - `rate` is `onTime / total` as a plain number (`0.75`), not rounded.
+ * - Every pair must be valid: one invalid pair returns `null`, never a rate over the rest.
+ * - An empty list returns `null`: no arrivals have no rate.
+ * - Anything beyond a rate — percentiles, causes — is the consumer's.
+ *
+ * @param pairs the planned and actual time of each arrival
+ * @param tolerance late (required) and early (optional) tolerances, as classifyPunctuality takes them
+ * @returns the on-time count, the total and the rate (null for an empty list), or null on invalid input
+ *
+ * @example punctualityRate([{ planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:05:00Z" }, { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:14:00Z" }, { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:16:00Z" }, { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T09:57:00Z" }], { late: "PT15M" }) // { onTime: 3, total: 4, rate: 0.75 }
+ * @example punctualityRate([{ planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T09:48:00Z" }, { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:01:00Z" }], { late: "PT15M", early: "PT10M" }) // { onTime: 1, total: 2, rate: 0.5 } (12 minutes early is not on time under a 10-minute early tolerance)
+ * @example punctualityRate([], { late: "PT15M" }) // null
+ * @example punctualityRate([{ planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:05:00" }], { late: "PT15M" }) // null (a zoneless actual is not a moment)
+ */
+export declare function punctualityRate(pairs: PlannedActual[], tolerance: PunctualityTolerance): OnTimeRate | null;

package/dist/transport/calculate/punctualityRate.js

@@ -0,0 +1,59 @@
+import { isObject, parseInstantNanoseconds, parsePunctualityTolerance, punctualityOf, } from "../../internal/index.js";
+/**
+ * The share of planned/actual pairs that were on time under one tolerance.
+ *
+ * A rate is a count under a stated tolerance: the same arrivals give a different rate under a
+ * 60-minute tolerance than under a 120-minute one, so the tolerance travels with the number.
+ *
+ * - Each pair is classified by `classifyPunctuality`'s rule under the same tolerance: `late` and
+ *   `early` are read once, before any pair, so the whole list is judged under one tolerance.
+ *   Only `"onTime"` counts: with an `early` tolerance, an early arrival is **not** on time;
+ *   without one, it is.
+ * - `rate` is `onTime / total` as a plain number (`0.75`), not rounded.
+ * - Every pair must be valid: one invalid pair returns `null`, never a rate over the rest.
+ * - An empty list returns `null`: no arrivals have no rate.
+ * - Anything beyond a rate — percentiles, causes — is the consumer's.
+ *
+ * @param pairs the planned and actual time of each arrival
+ * @param tolerance late (required) and early (optional) tolerances, as classifyPunctuality takes them
+ * @returns the on-time count, the total and the rate (null for an empty list), or null on invalid input
+ *
+ * @example punctualityRate([{ planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:05:00Z" }, { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:14:00Z" }, { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:16:00Z" }, { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T09:57:00Z" }], { late: "PT15M" }) // { onTime: 3, total: 4, rate: 0.75 }
+ * @example punctualityRate([{ planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T09:48:00Z" }, { planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:01:00Z" }], { late: "PT15M", early: "PT10M" }) // { onTime: 1, total: 2, rate: 0.5 } (12 minutes early is not on time under a 10-minute early tolerance)
+ * @example punctualityRate([], { late: "PT15M" }) // null
+ * @example punctualityRate([{ planned: "2024-06-15T10:00:00Z", actual: "2024-06-15T10:05:00" }], { late: "PT15M" }) // null (a zoneless actual is not a moment)
+ */
+export function punctualityRate(pairs, tolerance) {
+    try {
+        if (!Array.isArray(pairs) || pairs.length === 0) {
+            return null;
+        }
+        // Read once: every pair is judged under the same tolerance, whatever a getter returns later.
+        const bounds = parsePunctualityTolerance(tolerance);
+        if (bounds === null) {
+            return null;
+        }
+        let onTime = 0;
+        for (const pair of pairs) {
+            if (!isObject(pair)) {
+                return null;
+            }
+            const { planned, actual } = pair;
+            const plannedNanoseconds = parseInstantNanoseconds(planned);
+            const actualNanoseconds = parseInstantNanoseconds(actual);
+            if (plannedNanoseconds === null || actualNanoseconds === null) {
+                return null;
+            }
+            if (punctualityOf(actualNanoseconds - plannedNanoseconds, bounds) ===
+                "onTime") {
+                onTime += 1;
+            }
+        }
+        return { onTime, total: pairs.length, rate: onTime / pairs.length };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,150 @@
+/** One leg of a multi-modal journey: a departure, how long it takes, and where it lands. */
+export interface Leg {
+    /**
+     * The departure: an instant (`Z`/offset) or a zoned string, always exact; on any leg but the
+     * first, a zoneless wall time is also accepted and is read in the previous leg's `timeZone`
+     * (the first leg's equivalent is `ScheduleDeliveryOptions.startTimeZone`). Required on the
+     * first leg; on later legs it is the scheduled connection the cargo waits for.
+     *
+     * @defaultValue None. The leg leaves as soon as the previous leg's arrival plus its
+     * `dwellAfter` allows; a first leg without it is invalid input.
+     */
+    departure?: string;
+    /** The ISO 8601 duration of the leg; time units and 24-hour days only (`transitTime`'s rule). */
+    duration: string;
+    /** The time zone of the destination, the caller's fact: an IANA name or a UTC offset. */
+    timeZone: string;
+    /**
+     * The handling time at the handoff after this leg; the minimum connect time.
+     *
+     * @defaultValue `"PT0S"`
+     */
+    dwellAfter?: string;
+    /**
+     * An opaque tag echoed back on the LegTime; GMT does not interpret transport modes.
+     *
+     * @defaultValue None. The LegTime carries no `mode`.
+     */
+    mode?: string;
+    /**
+     * An opaque tag echoed back on the LegTime; never resolved to a zone.
+     *
+     * @defaultValue None. The LegTime carries no `origin`.
+     */
+    origin?: string;
+    /**
+     * An opaque tag echoed back on the LegTime; never resolved to a zone.
+     *
+     * @defaultValue None. The LegTime carries no `destination`.
+     */
+    destination?: string;
+}
+/** One leg's computed times, with the leg's own tags echoed back. */
+export interface LegTime {
+    /** The arrival as a UTC instant (`Z` form) — every leg boundary is an exact instant. */
+    arrival: string;
+    /** The arrival rendered in the leg's `timeZone`, as `etaAtZone` renders it. */
+    localArrival: string;
+    /** The leg's `dwellAfter` echoed as written, `"PT0S"` when omitted. */
+    dwellAfter: string;
+    /** The leg's `mode`, echoed back; absent when the leg did not supply it. */
+    mode?: string;
+    /** The leg's `origin`, echoed back; absent when the leg did not supply it. */
+    origin?: string;
+    /** The leg's `destination`, echoed back; absent when the leg did not supply it. */
+    destination?: string;
+}
+/** Options for `scheduleDelivery`. */
+export interface ScheduleDeliveryOptions {
+    /**
+     * The time zone a zoneless first-leg departure is read in, an IANA name or a UTC offset, for
+     * schedules published as local wall times. An ambiguous wall time resolves to the earlier instant
+     * and a nonexistent one to the later instant (`"compatible"`). Ignored when the first departure
+     * is already exact; never applied to later legs.
+     *
+     * @defaultValue None. A zoneless first-leg departure is invalid input.
+     */
+    startTimeZone?: string;
+}
+/** What `scheduleDelivery` returns: the final local ETA and every leg's times. */
+export interface DeliverySchedule {
+    /** The last leg's `localArrival`. `""` only for an empty legs array. */
+    eta: string;
+    /** One `LegTime` per leg, in order. */
+    legTimes: LegTime[];
+}
+/**
+ * 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 declare function scheduleDelivery(legs: Leg[], options?: ScheduleDeliveryOptions): DeliverySchedule | null;