@northguild/gmt 1.17.0 → 1.18.0

package/dist/transport/calculate/cutoffAt.js

@@ -0,0 +1,209 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { rollDate } from "../../calendar/business/rollDate.js";
+import { isValidBusinessCalendar } from "../../calendar/validate/isValidBusinessCalendar.js";
+import { isValidRollConvention } from "../../calendar/validate/isValidRollConvention.js";
+import { isValidDuration } from "../../duration/validate/isValidDuration.js";
+import { classifyLocal } from "../../instant/convert/classifyLocal.js";
+import { resolveLocal } from "../../instant/convert/resolveLocal.js";
+import { instantFrom } from "../../internal/index.js";
+import { isObject } from "../../internal/isObject.js";
+import { isValidTime } from "../../plain/validate/isValidTime.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
+function resolveOptions(options) {
+    if (!isObject(options)) {
+        return null;
+    }
+    const { timeZone, atLocalTime, calendar, roll } = options;
+    if (typeof timeZone !== "string" || !isValidTimeZone(timeZone)) {
+        return null;
+    }
+    if (atLocalTime !== undefined && !isValidTime(atLocalTime)) {
+        return null;
+    }
+    if (calendar !== undefined && !isValidBusinessCalendar(calendar)) {
+        return null;
+    }
+    if (roll !== undefined && !isValidRollConvention(roll)) {
+        return null;
+    }
+    // Rolling needs both a calendar and a direction, and no standard supplies either one by
+    // default: a calendar without a roll, or a roll without a calendar, is a missing term.
+    if ((calendar === undefined) !== (roll === undefined)) {
+        return null;
+    }
+    return {
+        timeZone,
+        atLocalTime: atLocalTime === undefined ? null : Temporal.PlainTime.from(atLocalTime),
+        rolling: calendar === undefined || roll === undefined ? null : { calendar, roll },
+    };
+}
+/**
+ * The instant a local wall time names: the first occurrence of a repeated hour, as RFC 5545
+ * §3.3.5 reads a local time that "occurs more than once", and `null` for a skipped one, which
+ * is never shifted.
+ */
+function resolveWallTime(wall, timeZone) {
+    const local = wall.toString();
+    const kind = classifyLocal(local, timeZone);
+    if (kind === null || kind === "nonexistent") {
+        return null;
+    }
+    const instant = resolveLocal(local, timeZone, { disambiguation: "earlier" });
+    return instant === ""
+        ? null
+        : Temporal.Instant.from(instant).toZonedDateTimeISO(timeZone);
+}
+/** The calendar part of a duration — years, months, weeks and days. */
+function datePart(offset) {
+    return Temporal.Duration.from({
+        years: offset.years,
+        months: offset.months,
+        weeks: offset.weeks,
+        days: offset.days,
+    });
+}
+/** The exact part of a duration — hours and smaller. */
+function timePart(offset) {
+    return Temporal.Duration.from({
+        hours: offset.hours,
+        minutes: offset.minutes,
+        seconds: offset.seconds,
+        milliseconds: offset.milliseconds,
+        microseconds: offset.microseconds,
+        nanoseconds: offset.nanoseconds,
+    });
+}
+/**
+ * The offset taken off the anchor with no pinning: the calendar part moves the local wall
+ * clock, then the exact part comes off in exact time — Temporal's `ZonedDateTime#subtract`,
+ * except that a wall clock landing in a skipped hour is `null` rather than moved forward.
+ */
+function subtractOffset(anchor, offset) {
+    const calendarPart = datePart(offset);
+    if (calendarPart.blank) {
+        return anchor.subtract(timePart(offset));
+    }
+    const wall = resolveWallTime(anchor.toPlainDateTime().subtract(calendarPart), anchor.timeZoneId);
+    return wall === null ? null : wall.subtract(timePart(offset));
+}
+/**
+ * The local date the cut-off falls on after rolling, or `null` when the roll fails. With no
+ * calendar the date is left as it is.
+ */
+function rolledDate(date, options) {
+    if (options.rolling === null) {
+        return date;
+    }
+    const { calendar, roll } = options.rolling;
+    const rolled = rollDate(date.toString(), roll, calendar);
+    return rolled === "" ? null : Temporal.PlainDate.from(rolled);
+}
+/**
+ * Find a deadline stated as an offset before an anchor event, in the local time of the place
+ * that enforces it.
+ *
+ * Logistics deadlines are not fixed timestamps: they count back from an event — a vessel's
+ * departure, a flight's, a container's loading — and they move when that event moves. An ocean
+ * booking carries a stack of them (documentation, VGM, gate-in, customs); `cutoffSchedule`
+ * computes the whole stack at once.
+ *
+ * - **`atLocalTime` is what makes this more than subtracting a duration.** A cut-off "two days
+ *   before, 17:00" is 17:00 local on the date two days earlier — not 48 hours before, which
+ *   keeps the departure's time of day, and moves by an hour when a DST transition falls in
+ *   between. With `atLocalTime` only the day of the offset result matters: the offset's exact
+ *   part (hours and smaller) comes off the anchor's instant, its calendar part (years, months,
+ *   weeks, days) off that local date, and the cut-off is `atLocalTime` on the day it lands on.
+ *   Because the exact part is taken off before the day is found, it can change the day: from
+ *   midnight, `P2DT0.000000001S` lands a day earlier than `P2D`.
+ * - **Without `atLocalTime` the offset is taken off as Temporal's `ZonedDateTime#subtract`
+ *   takes it:** the calendar part moves the local wall clock — `P2D` from 18:00 is 18:00, 47,
+ *   48 or 49 hours earlier — and the exact part is exact elapsed time — `PT96H` is 96 hours,
+ *   whatever the clock does. This is the advance-filing shape.
+ * - **The anchor is the caller's event.** Loading, departure and arrival are different
+ *   instants, and the same offset from the wrong one is late by days. `cutoffAt` never guesses
+ *   which event a rule means. The anchor is exact: an instant (`Z`/offset) or a zoned string.
+ *   Its bracket never supplies the zone — `timeZone` alone is the local frame — and is not
+ *   checked, with one exception: 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. The anchor is not cached: a
+ *   rescheduled departure is a new call.
+ * - **Non-business days roll as the caller says.** With `calendar`, a cut-off on a weekend or
+ *   holiday moves by `roll`, as `rollDate` moves it. Every industry answers "what if it lands
+ *   on a non-working day" differently, so the convention is always explicit — there is no
+ *   default: `calendar` without `roll`, or `roll` without `calendar`, returns `""`. The rolled
+ *   day keeps the cut-off's local time of day. `calendar.timeZone` is not read; `timeZone` is
+ *   the local frame. `"endOfMonth"` is `rollDate`'s schedule tool, not a cut-off convention.
+ * - **The order is not checked.** `cutoffAt` does not check that the cut-off comes before the
+ *   anchor: a negative offset, `P0D` with a late `atLocalTime`, `"following"` or `"endOfMonth"`
+ *   can each put it after.
+ * - **Local-time resolution.** Every local wall time the cut-off lands on — `atLocalTime`, the
+ *   calendar part of an unpinned offset, a rolled day — is resolved as `resolveLocal` describes
+ *   it: an **ambiguous** wall time (a fall-back hour the clock ran through twice) takes the
+ *   **earlier** instant — RFC 5545 §3.3.5's "first occurrence of the referenced time" — and a
+ *   **nonexistent** one (a skipped hour, a deleted day) returns `""` rather than being
+ *   shifted. An exact result that is not re-resolved stays as it is.
+ * - Returns the cut-off as a zoned string in `timeZone`, or `""` on invalid input.
+ *
+ * @param anchor ISO 8601 instant or zoned datetime string of the event the deadline counts back from
+ * @param offset ISO 8601 duration before the anchor
+ * @param options The zone the cut-off is read in, the time of day it is pinned to, and how it rolls off a non-business day
+ * @returns ISO 8601 zoned datetime string of the cut-off, or "" on invalid input
+ *
+ * @example cutoffAt("2024-06-14T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00" }) // "2024-06-12T17:00:00+02:00[Europe/Amsterdam]"
+ * @example cutoffAt("2024-06-14T16:00:00Z", "PT48H", { timeZone: "Europe/Amsterdam" }) // "2024-06-12T18:00:00+02:00[Europe/Amsterdam]" (48 hours keeps the departure's 18:00)
+ * @example cutoffAt("2024-06-14T16:00:00Z", "P1D", { timeZone: "Europe/Amsterdam", atLocalTime: "10:00" }) // "2024-06-13T10:00:00+02:00[Europe/Amsterdam]"
+ * @example cutoffAt("2024-11-05T17:00:00Z", "PT96H", { timeZone: "America/New_York" }) // "2024-11-01T13:00:00-04:00[America/New_York]" (96 elapsed hours across the fall-back)
+ * @example cutoffAt("2024-03-11T22:00:00Z", "P2D", { timeZone: "America/New_York", atLocalTime: "17:00" }) // "2024-03-09T17:00:00-05:00[America/New_York]" (17:00 local, across the spring-forward)
+ * @example cutoffAt("2024-06-18T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00", calendar: { weekend: [6, 7], holidays: [], timeZone: "Europe/Amsterdam" }, roll: "preceding" }) // "2024-06-14T17:00:00+02:00[Europe/Amsterdam]" (Sunday rolls back to Friday)
+ * @example cutoffAt("2024-06-18T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", atLocalTime: "17:00", calendar: { weekend: [6, 7], holidays: [], timeZone: "Europe/Amsterdam" } }) // "" (a calendar needs a roll convention)
+ * @example cutoffAt("2024-11-04T23:00:00Z", "P1D", { timeZone: "America/New_York", atLocalTime: "01:30" }) // "2024-11-03T01:30:00-04:00[America/New_York]" (a repeated hour takes the earlier pass)
+ * @example cutoffAt("2024-03-11T22:00:00Z", "P1D", { timeZone: "America/New_York", atLocalTime: "02:30" }) // "" (02:30 on 10 March never happened)
+ * @example cutoffAt("2024-06-14T18:00:00", "P2D", { timeZone: "Europe/Amsterdam" }) // "" (a zoneless anchor is not a moment)
+ * @example cutoffAt("2024-06-14T16:00:00Z", "P2D", { timeZone: "Europe/Amsterdam", roll: "preceding" }) // "" (a roll needs a calendar)
+ */
+export function cutoffAt(anchor, offset, options) {
+    try {
+        const resolved = resolveOptions(options);
+        if (resolved === null ||
+            !isValidInstant(anchor) ||
+            !isValidDuration(offset)) {
+            return "";
+        }
+        try {
+            const start = instantFrom(anchor).toZonedDateTimeISO(resolved.timeZone);
+            const duration = Temporal.Duration.from(offset);
+            if (resolved.atLocalTime !== null) {
+                const day = rolledDate(start
+                    .subtract(timePart(duration))
+                    .toPlainDate()
+                    .subtract(datePart(duration)), resolved);
+                const pinned = day === null
+                    ? null
+                    : resolveWallTime(day.toPlainDateTime(resolved.atLocalTime), resolved.timeZone);
+                return pinned === null ? "" : pinned.toString();
+            }
+            const cutoff = subtractOffset(start, duration);
+            if (cutoff === null) {
+                return "";
+            }
+            const day = rolledDate(cutoff.toPlainDate(), resolved);
+            if (day === null) {
+                return "";
+            }
+            if (day.equals(cutoff.toPlainDate())) {
+                return cutoff.toString();
+            }
+            const rolled = resolveWallTime(day.toPlainDateTime(cutoff.toPlainTime()), resolved.timeZone);
+            return rolled === null ? "" : rolled.toString();
+        }
+        catch {
+            return "";
+        }
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,70 @@
+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. */
+    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 `[]`.
+ *
+ * @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,71 @@
+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 `[]`.
+ *
+ * @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

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
@@ -92,8 +96,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";