@northguild/gmt 1.17.0 → 1.19.0

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

@@ -0,0 +1,75 @@
+import { type CutoffOptions } from "./cutoffAt.js";
+/** One named deadline in a cut-off stack: how long before the anchor, and at what local time. */
+export interface Cutoff {
+    /** The caller's label, echoed back (`"document"`, `"VGM"`); GMT does not interpret it. */
+    name: string;
+    /** The ISO 8601 duration before the anchor, as `cutoffAt` takes it. */
+    offset: string;
+    /**
+     * The local time of day the cut-off is pinned to, as `cutoffAt` takes it.
+     *
+     * @defaultValue None. The cut-off is the offset taken off the anchor, with no time of day
+     * pinned.
+     */
+    atLocalTime?: string;
+}
+/** One computed deadline in a cut-off schedule. */
+export interface CutoffTime {
+    /** The entry's `name`, echoed back. */
+    name: string;
+    /** The cut-off as a zoned string in the options' `timeZone`. */
+    at: string;
+}
+/** Options for `cutoffSchedule`: `cutoffAt`'s, with `atLocalTime` read from each entry instead. */
+export interface CutoffScheduleOptions {
+    /**
+     * The time zone every cut-off is read in: an IANA name or a UTC offset to the minute (what
+     * `isValidTimeZone` accepts).
+     */
+    timeZone: string;
+    /**
+     * The working week and holidays every cut-off's local date is rolled against. Requires `roll`.
+     *
+     * @defaultValue None. No cut-off's date is rolled; a `roll` without it returns `[]`.
+     */
+    calendar?: CutoffOptions["calendar"];
+    /**
+     * How a cut-off on a non-business day moves, as `rollDate` moves it. Requires `calendar`.
+     *
+     * @defaultValue None. No cut-off's date is rolled; a `calendar` without it returns `[]`.
+     */
+    roll?: CutoffOptions["roll"];
+}
+/**
+ * Compute a whole stack of cut-offs against one anchor event, earliest first.
+ *
+ * An ocean booking carries several deadlines counted back from the same departure —
+ * documentation, VGM, gate-in, customs — and when the vessel is rescheduled all of them move.
+ * `cutoffSchedule` computes each entry with `cutoffAt` against the one anchor, so a new
+ * departure is one call and every deadline follows it.
+ *
+ * - Each entry is `cutoffAt(anchor, entry.offset, { ...options, atLocalTime: entry.atLocalTime })`:
+ *   the same local-time resolution, the same rolling, the same sentinel. `atLocalTime` belongs
+ *   to the entry; one in `options` is not read.
+ * - Sorted earliest first by instant, not by the text of the local time: on a fall-back day
+ *   01:30 on the first pass is before 01:15 on the second. Entries on the same instant keep the
+ *   order they were given in.
+ * - `name` is an opaque string echoed back; duplicates are kept.
+ * - Every entry must succeed: one invalid entry, or one cut-off in a skipped local hour,
+ *   returns `[]` rather than a stack with a deadline silently missing. An empty `cutoffs` array
+ *   returns `[]`.
+ * - An offset with seconds (`-00:44:30`) returns `[]`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name.
+ *
+ * @param anchor ISO 8601 instant or zoned datetime string of the event the deadlines count back from
+ * @param cutoffs the named deadlines, each with an offset and an optional local time of day
+ * @param options The zone every cut-off is read in, and how one rolls off a non-business day, as cutoffAt takes them
+ * @returns the named cut-offs, earliest first, or [] on invalid input
+ *
+ * @example cutoffSchedule("2024-06-14T16:00:00Z", [{ name: "gate-in", offset: "P1D" }, { name: "document", offset: "P2D", atLocalTime: "17:00" }, { name: "VGM", offset: "P1D", atLocalTime: "10:00" }], { timeZone: "Europe/Amsterdam" }) // [{ name: "document", at: "2024-06-12T17:00:00+02:00[Europe/Amsterdam]" }, { name: "VGM", at: "2024-06-13T10:00:00+02:00[Europe/Amsterdam]" }, { name: "gate-in", at: "2024-06-13T18:00:00+02:00[Europe/Amsterdam]" }]
+ * @example cutoffSchedule("2024-06-18T16:00:00Z", [{ name: "document", offset: "P2D", atLocalTime: "17:00" }, { name: "VGM", offset: "P1D", atLocalTime: "10:00" }], { timeZone: "Europe/Amsterdam", calendar: { weekend: [6, 7], holidays: [], timeZone: "Europe/Amsterdam" }, roll: "preceding" }) // [{ name: "document", at: "2024-06-14T17:00:00+02:00[Europe/Amsterdam]" }, { name: "VGM", at: "2024-06-17T10:00:00+02:00[Europe/Amsterdam]" }] (Sunday's document cut-off rolls back to Friday)
+ * @example cutoffSchedule("2024-06-14T16:00:00Z", [], { timeZone: "Europe/Amsterdam" }) // []
+ * @example cutoffSchedule("2024-06-14T16:00:00Z", [{ name: "document", offset: "2 days" }], { timeZone: "Europe/Amsterdam" }) // []
+ * @example cutoffSchedule("2024-03-11T22:00:00Z", [{ name: "gate-in", offset: "P1D" }, { name: "VGM", offset: "P1D", atLocalTime: "02:30" }], { timeZone: "America/New_York" }) // [] (02:30 on 10 March never happened)
+ */
+export declare function cutoffSchedule(anchor: string, cutoffs: Cutoff[], options: CutoffScheduleOptions): CutoffTime[];

package/dist/transport/calculate/cutoffSchedule.js

@@ -0,0 +1,73 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { instantFrom } from "../../internal/index.js";
+import { isObject } from "../../internal/isObject.js";
+import { cutoffAt } from "./cutoffAt.js";
+/**
+ * Compute a whole stack of cut-offs against one anchor event, earliest first.
+ *
+ * An ocean booking carries several deadlines counted back from the same departure —
+ * documentation, VGM, gate-in, customs — and when the vessel is rescheduled all of them move.
+ * `cutoffSchedule` computes each entry with `cutoffAt` against the one anchor, so a new
+ * departure is one call and every deadline follows it.
+ *
+ * - Each entry is `cutoffAt(anchor, entry.offset, { ...options, atLocalTime: entry.atLocalTime })`:
+ *   the same local-time resolution, the same rolling, the same sentinel. `atLocalTime` belongs
+ *   to the entry; one in `options` is not read.
+ * - Sorted earliest first by instant, not by the text of the local time: on a fall-back day
+ *   01:30 on the first pass is before 01:15 on the second. Entries on the same instant keep the
+ *   order they were given in.
+ * - `name` is an opaque string echoed back; duplicates are kept.
+ * - Every entry must succeed: one invalid entry, or one cut-off in a skipped local hour,
+ *   returns `[]` rather than a stack with a deadline silently missing. An empty `cutoffs` array
+ *   returns `[]`.
+ * - An offset with seconds (`-00:44:30`) returns `[]`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name.
+ *
+ * @param anchor ISO 8601 instant or zoned datetime string of the event the deadlines count back from
+ * @param cutoffs the named deadlines, each with an offset and an optional local time of day
+ * @param options The zone every cut-off is read in, and how one rolls off a non-business day, as cutoffAt takes them
+ * @returns the named cut-offs, earliest first, or [] on invalid input
+ *
+ * @example cutoffSchedule("2024-06-14T16:00:00Z", [{ name: "gate-in", offset: "P1D" }, { name: "document", offset: "P2D", atLocalTime: "17:00" }, { name: "VGM", offset: "P1D", atLocalTime: "10:00" }], { timeZone: "Europe/Amsterdam" }) // [{ name: "document", at: "2024-06-12T17:00:00+02:00[Europe/Amsterdam]" }, { name: "VGM", at: "2024-06-13T10:00:00+02:00[Europe/Amsterdam]" }, { name: "gate-in", at: "2024-06-13T18:00:00+02:00[Europe/Amsterdam]" }]
+ * @example cutoffSchedule("2024-06-18T16:00:00Z", [{ name: "document", offset: "P2D", atLocalTime: "17:00" }, { name: "VGM", offset: "P1D", atLocalTime: "10:00" }], { timeZone: "Europe/Amsterdam", calendar: { weekend: [6, 7], holidays: [], timeZone: "Europe/Amsterdam" }, roll: "preceding" }) // [{ name: "document", at: "2024-06-14T17:00:00+02:00[Europe/Amsterdam]" }, { name: "VGM", at: "2024-06-17T10:00:00+02:00[Europe/Amsterdam]" }] (Sunday's document cut-off rolls back to Friday)
+ * @example cutoffSchedule("2024-06-14T16:00:00Z", [], { timeZone: "Europe/Amsterdam" }) // []
+ * @example cutoffSchedule("2024-06-14T16:00:00Z", [{ name: "document", offset: "2 days" }], { timeZone: "Europe/Amsterdam" }) // []
+ * @example cutoffSchedule("2024-03-11T22:00:00Z", [{ name: "gate-in", offset: "P1D" }, { name: "VGM", offset: "P1D", atLocalTime: "02:30" }], { timeZone: "America/New_York" }) // [] (02:30 on 10 March never happened)
+ */
+export function cutoffSchedule(anchor, cutoffs, options) {
+    try {
+        if (!Array.isArray(cutoffs) || !isObject(options)) {
+            return [];
+        }
+        const { timeZone, calendar, roll } = options;
+        const schedule = [];
+        for (const cutoff of cutoffs) {
+            if (!isObject(cutoff)) {
+                return [];
+            }
+            const { name, offset, atLocalTime } = cutoff;
+            if (typeof name !== "string") {
+                return [];
+            }
+            const at = cutoffAt(anchor, offset, {
+                timeZone,
+                atLocalTime,
+                calendar,
+                roll,
+            });
+            if (at === "") {
+                return [];
+            }
+            schedule.push({ name, at, instant: instantFrom(at) });
+        }
+        // Array.prototype.sort is stable, so entries on the same instant keep their input order.
+        return schedule
+            .sort((a, b) => Temporal.Instant.compare(a.instant, b.instant))
+            .map(({ name, at }) => ({ name, at }));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
+    }
+}

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

@@ -1,12 +1,17 @@
 /** What `dwellTime` returns: exact elapsed time plus the local view every charging regime counts in. */
 export interface Dwell {
-    /** Exact elapsed time from entry to exit, as an ISO 8601 duration with hours as the largest unit. */
+    /**
+     * The exact elapsed time from entry to exit, as an ISO 8601 duration with hours as the largest
+     * unit.
+     */
     duration: string;
     /** The entry, rendered in the dwell zone. */
     enter: string;
     /** The exit, rendered in the dwell zone. */
     exit: string;
-    /** Distinct local calendar dates the dwell touched, counted half-open at the exit. */
+    /**
+     * The number of distinct local calendar dates the dwell touched, counted half-open at the exit.
+     */
     calendarDays: number;
 }
 /**
@@ -34,12 +39,16 @@ export interface Dwell {
  *   touched (`Pacific/Apia` skipped 2011-12-30); and a date the clock falls back into is still
  *   one date (`America/Goose_Bay` fell back from 00:01 on 7 November 2010 into the 6th).
  * - **The zone decides the count, so it has to be stated.** `targetZone` is used when given.
- *   Without it, the entry's bracketed IANA zone is used. As in `Temporal.Instant.from`, a
- *   bracketed zone is otherwise not read, so it is not validated either: the entry's is read
- *   (and must exist and agree with its offset) only when it supplies the dwell zone, because
- *   `targetZone` is omitted, and the exit's is never read. If the entry and exit are bare
- *   instants — `Z` or an offset — and no `targetZone` is given, the result is `null`: an
+ *   Without it, the entry's bracketed IANA zone is used. A bracketed zone is otherwise not
+ *   validated: the entry's must exist and agree with its offset only when it supplies the dwell
+ *   zone, because `targetZone` is omitted, and the exit's never supplies it. If the entry and
+ *   exit are bare instants — `Z` or an offset — and no `targetZone` is given, the result is `null`: an
  *   offset is not a zone (CORE-4), and a day count in an unstated locality would be a guess.
+ * - **The offset fixes each 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, on the entry and the exit alike. A zone that does
+ *   not exist, or that disagrees with the offset, changes nothing.
  * - `enter` and `exit` are the two instants rendered in the dwell zone, so a charging record
  *   shows the local times the terminal's own clock showed.
  * - `targetZone` is whatever `isValidTimeZone` accepts, which is what Temporal accepts: an IANA
@@ -51,10 +60,15 @@ export interface Dwell {
  *   more than 10,000 transitions (about 5,000 years of twice-yearly DST) returns `null`.
  * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
  *   dwell is a data error, not a negative stay), or when no zone can be determined.
+ * - An offset with seconds (`-00:44:30`) returns `null`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param entry ISO 8601 zoned datetime or instant string of the gate-in, arrival or admission
  * @param exit ISO 8601 zoned datetime or instant string of the gate-out, departure or discharge
- * @param targetZone IANA timeZone identifier or fixed offset the days are counted in; defaults to `entry`'s bracketed zone
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts) the
+ *   days are counted in; defaults to `entry`'s bracketed zone
  * @returns exact duration, zone-local entry and exit, and the local calendar days touched, or null on invalid input
  *
  * @example dwellTime("2024-06-15T23:00:00-04:00[America/New_York]", "2024-06-16T01:00:00-04:00[America/New_York]") // { duration: "PT2H", enter: "2024-06-15T23:00:00-04:00[America/New_York]", exit: "2024-06-16T01:00:00-04:00[America/New_York]", calendarDays: 2 }

package/dist/transport/calculate/dwellTime.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { countZonedLocalDates, zonedDateTimeFrom } from "../../internal/index.js";
+import { countZonedLocalDates, instantFrom, zonedDateTimeFrom, } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
 import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
 import { isValidZonedDateTime } from "../../zoned/validate/isValidZonedDateTime.js";
@@ -48,12 +48,16 @@ function dwellZone(entry, targetZone) {
  *   touched (`Pacific/Apia` skipped 2011-12-30); and a date the clock falls back into is still
  *   one date (`America/Goose_Bay` fell back from 00:01 on 7 November 2010 into the 6th).
  * - **The zone decides the count, so it has to be stated.** `targetZone` is used when given.
- *   Without it, the entry's bracketed IANA zone is used. As in `Temporal.Instant.from`, a
- *   bracketed zone is otherwise not read, so it is not validated either: the entry's is read
- *   (and must exist and agree with its offset) only when it supplies the dwell zone, because
- *   `targetZone` is omitted, and the exit's is never read. If the entry and exit are bare
- *   instants — `Z` or an offset — and no `targetZone` is given, the result is `null`: an
+ *   Without it, the entry's bracketed IANA zone is used. A bracketed zone is otherwise not
+ *   validated: the entry's must exist and agree with its offset only when it supplies the dwell
+ *   zone, because `targetZone` is omitted, and the exit's never supplies it. If the entry and
+ *   exit are bare instants — `Z` or an offset — and no `targetZone` is given, the result is `null`: an
  *   offset is not a zone (CORE-4), and a day count in an unstated locality would be a guess.
+ * - **The offset fixes each 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, on the entry and the exit alike. A zone that does
+ *   not exist, or that disagrees with the offset, changes nothing.
  * - `enter` and `exit` are the two instants rendered in the dwell zone, so a charging record
  *   shows the local times the terminal's own clock showed.
  * - `targetZone` is whatever `isValidTimeZone` accepts, which is what Temporal accepts: an IANA
@@ -65,10 +69,15 @@ function dwellZone(entry, targetZone) {
  *   more than 10,000 transitions (about 5,000 years of twice-yearly DST) returns `null`.
  * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
  *   dwell is a data error, not a negative stay), or when no zone can be determined.
+ * - An offset with seconds (`-00:44:30`) returns `null`. A written zone cannot carry seconds (RFC
+ *   9557 §4.1), so the result could not name it. Pass the IANA name, or call
+ *   `fromOffsetInstant({ instant, offset })` for the local time with its full offset and no
+ *   bracket.
  *
  * @param entry ISO 8601 zoned datetime or instant string of the gate-in, arrival or admission
  * @param exit ISO 8601 zoned datetime or instant string of the gate-out, departure or discharge
- * @param targetZone IANA timeZone identifier or fixed offset the days are counted in; defaults to `entry`'s bracketed zone
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts) the
+ *   days are counted in; defaults to `entry`'s bracketed zone
  * @returns exact duration, zone-local entry and exit, and the local calendar days touched, or null on invalid input
  *
  * @example dwellTime("2024-06-15T23:00:00-04:00[America/New_York]", "2024-06-16T01:00:00-04:00[America/New_York]") // { duration: "PT2H", enter: "2024-06-15T23:00:00-04:00[America/New_York]", exit: "2024-06-16T01:00:00-04:00[America/New_York]", calendarDays: 2 }
@@ -92,8 +101,8 @@ export function dwellTime(entry, exit, targetZone) {
         if (zone === null) {
             return null;
         }
-        const entryInstant = Temporal.Instant.from(entry);
-        const exitInstant = Temporal.Instant.from(exit);
+        const entryInstant = instantFrom(entry);
+        const exitInstant = instantFrom(exit);
         if (Temporal.Instant.compare(entryInstant, exitInstant) > 0) {
             return null;
         }

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

@@ -0,0 +1,65 @@
+import type { TimestampEvent } from "../../types/index.js";
+/** Options for `estimateDrift`. */
+export interface EstimateDriftOptions {
+    /**
+     * The drift allowed, as an ISO 8601 duration of exact time (a day is 24 hours; years, months and
+     * weeks are refused; not negative). With it, `exceedsTolerance` says whether the drift is greater
+     * than it.
+     *
+     * @defaultValue None. `exceedsTolerance` is `null`.
+     */
+    tolerance?: string;
+}
+/** What `estimateDrift` returns. */
+export interface DriftReport {
+    /** The earliest-recorded EST's `at`, exactly as written. */
+    first: string;
+    /** The latest-recorded EST's `at`, exactly as written. */
+    last: string;
+    /**
+     * The drift: `last` minus `first` in exact time, hours as the largest unit; negative when it
+     * moved earlier.
+     */
+    drift: string;
+    /** The number of EST records, the first included. */
+    revisions: number;
+    /** Whether the absolute drift is greater than `tolerance`; `null` without a tolerance. */
+    exceedsTolerance: boolean | null;
+}
+/**
+ * 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 declare function estimateDrift(events: TimestampEvent[], options?: EstimateDriftOptions): DriftReport | null;

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

@@ -1,2 +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

@@ -1,2 +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;