@northguild/gmt 1.17.0 → 1.19.0

package/dist/span/validate/isValidSpan.d.ts

@@ -8,9 +8,14 @@
  *   optionally followed by a bracketed IANA zone; no leap seconds. Calendar and elective
  *   annotations are ignored, as `Temporal.Instant.from` ignores them. The two endpoints need not
  *   share a zone.
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
- *   with the offset is not checked.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, except a wall time repeated inside a sub-minute offset
+ *   change, which reads as its first pass (see `isValidInstant`). Otherwise the bracket is not
+ *   checked: a zone that does not exist, or that disagrees with the offset, changes nothing. Validity never depends
+ *   on the bracket.
  * - Order does not matter. A span is signed, not invalid, when `start` is after `end`, so
  *   this is symmetric.
  * - **`spanMs` can still return `null` on a pair this accepts** — a span wider than

package/dist/span/validate/isValidSpan.js

@@ -9,9 +9,14 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  *   optionally followed by a bracketed IANA zone; no leap seconds. Calendar and elective
  *   annotations are ignored, as `Temporal.Instant.from` ignores them. The two endpoints need not
  *   share a zone.
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
- *   with the offset is not checked.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, except a wall time repeated inside a sub-minute offset
+ *   change, which reads as its first pass (see `isValidInstant`). Otherwise the bracket is not
+ *   checked: a zone that does not exist, or that disagrees with the offset, changes nothing. Validity never depends
+ *   on the bracket.
  * - Order does not matter. A span is signed, not invalid, when `start` is after `end`, so
  *   this is symmetric.
  * - **`spanMs` can still return `null` on a pair this accepts** — a span wider than

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

@@ -0,0 +1,47 @@
+import type { TimestampClass, TimestampEvent } from "../../types/index.js";
+/** What `bestAvailable` returns: the chosen timestamp and the class it carries. */
+export interface ClassifiedTimestamp {
+    /** The chosen event's `at`, exactly as it was written. */
+    at: string;
+    /** The class of the chosen event, so the value is never shown as something it is not. */
+    classifier: TimestampClass;
+}
+/**
+ * Pick the best available timestamp for an event from its planned, estimated, requested and
+ * actual records, and say which class it is.
+ *
+ * One field often carries four meanings — DCSA's `eventClassifierCode` vocabulary: `PLN`
+ * (planned), `EST` (estimated), `REQ` (requested) and `ACT` (actual). A dashboard that shows the
+ * latest-recorded value puts an estimate in the actual column the moment a late feed arrives.
+ * This returns the class with the value, so the consumer can label it.
+ *
+ * - **An `ACT` wins whenever there is one**, whatever was recorded after it: an estimate recorded
+ *   after the arrival is still only an estimate.
+ * - Otherwise `PLN`, then `REQ`, then `EST`. This `ACT` > `PLN` > `REQ` > `EST` selection is GMT's
+ *   own convention. DCSA's Port Call standard negotiates some port call services — a berth,
+ *   pilotage, towage — through an estimated, then requested, then planned timestamp, followed by
+ *   an actual; this order reads that pattern from its most settled end. DCSA defines the classes
+ *   and the pattern, not a rule for choosing among them. A plan is agreed; a request is asked
+ *   for; an estimate is only predicted. So an `EST` or `REQ` never replaces a `PLN`, however much later it was recorded,
+ *   and there is never an `EST` when a `REQ` exists. The order is fixed, not configurable.
+ * - Within the chosen class, the newest-recorded event wins (latest `recordedAt`), so a revised
+ *   plan or a corrected actual replaces the earlier one. Two records at the same instant go to
+ *   the later one in the array.
+ * - `at` is echoed exactly as written. `at` and `recordedAt` are instants (`Z`/offset) or zoned
+ *   strings, compared as instants and 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` for an empty list, or when any event is invalid — a `classifier` other than
+ *   exactly `PLN`, `EST`, `REQ` or `ACT` included.
+ *
+ * @param events the event's timestamp records, in any order
+ * @returns the chosen `at` and its class (null for an empty list), or null on invalid input
+ *
+ * @example bestAvailable([{ classifier: "ACT", at: "2024-06-15T12:52:00Z", recordedAt: "2024-06-15T12:53:00Z" }, { classifier: "EST", at: "2024-06-15T13:05:00Z", recordedAt: "2024-06-15T14:00:00Z" }]) // { at: "2024-06-15T12:52:00Z", classifier: "ACT" } (an estimate recorded after the actual never replaces it)
+ * @example bestAvailable([{ classifier: "PLN", at: "2024-06-15T12:00:00Z", recordedAt: "2024-06-01T00:00:00Z" }, { classifier: "PLN", at: "2024-06-15T13:00:00Z", recordedAt: "2024-06-10T00:00:00Z" }]) // { at: "2024-06-15T13:00:00Z", classifier: "PLN" } (the newest plan)
+ * @example bestAvailable([{ classifier: "EST", at: "2024-06-15T12:40:00Z", recordedAt: "2024-06-14T00:00:00Z" }, { classifier: "REQ", at: "2024-06-15T12:30:00Z", recordedAt: "2024-06-12T00:00:00Z" }]) // { at: "2024-06-15T12:30:00Z", classifier: "REQ" } (never an EST when a REQ exists)
+ * @example bestAvailable([]) // null
+ * @example bestAvailable([{ classifier: "ETA", at: "2024-06-15T12:40:00Z", recordedAt: "2024-06-14T00:00:00Z" }]) // null (not a timestamp class)
+ */
+export declare function bestAvailable(events: TimestampEvent[]): ClassifiedTimestamp | null;

package/dist/transport/calculate/bestAvailable.js

@@ -0,0 +1,76 @@
+import { parseTimestampEvents } from "../../internal/index.js";
+/**
+ * GMT's selection order: an actual, else a plan, else a request, else an estimate.
+ *
+ * GMT rule. DCSA defines the four classes (`eventClassifierCode`) and, in its Port Call
+ * standard, the pattern some port call services are negotiated through: "an (Estimated,
+ * Requested, Planned) ERP-pattern, including an (Actual) A" (DCSA Port Call 2.0.0, Use Cases,
+ * "Port Call Services Summary":
+ * https://reference.dcsa.org/content/standards/releases/port-call/v2-0-0/port-call-v2-0-0-use-cases).
+ * DCSA gives no rule for choosing among the classes; this order reads that pattern from its most
+ * settled end.
+ */
+const PRECEDENCE = ["ACT", "PLN", "REQ", "EST"];
+/**
+ * Pick the best available timestamp for an event from its planned, estimated, requested and
+ * actual records, and say which class it is.
+ *
+ * One field often carries four meanings — DCSA's `eventClassifierCode` vocabulary: `PLN`
+ * (planned), `EST` (estimated), `REQ` (requested) and `ACT` (actual). A dashboard that shows the
+ * latest-recorded value puts an estimate in the actual column the moment a late feed arrives.
+ * This returns the class with the value, so the consumer can label it.
+ *
+ * - **An `ACT` wins whenever there is one**, whatever was recorded after it: an estimate recorded
+ *   after the arrival is still only an estimate.
+ * - Otherwise `PLN`, then `REQ`, then `EST`. This `ACT` > `PLN` > `REQ` > `EST` selection is GMT's
+ *   own convention. DCSA's Port Call standard negotiates some port call services — a berth,
+ *   pilotage, towage — through an estimated, then requested, then planned timestamp, followed by
+ *   an actual; this order reads that pattern from its most settled end. DCSA defines the classes
+ *   and the pattern, not a rule for choosing among them. A plan is agreed; a request is asked
+ *   for; an estimate is only predicted. So an `EST` or `REQ` never replaces a `PLN`, however much later it was recorded,
+ *   and there is never an `EST` when a `REQ` exists. The order is fixed, not configurable.
+ * - Within the chosen class, the newest-recorded event wins (latest `recordedAt`), so a revised
+ *   plan or a corrected actual replaces the earlier one. Two records at the same instant go to
+ *   the later one in the array.
+ * - `at` is echoed exactly as written. `at` and `recordedAt` are instants (`Z`/offset) or zoned
+ *   strings, compared as instants and 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` for an empty list, or when any event is invalid — a `classifier` other than
+ *   exactly `PLN`, `EST`, `REQ` or `ACT` included.
+ *
+ * @param events the event's timestamp records, in any order
+ * @returns the chosen `at` and its class (null for an empty list), or null on invalid input
+ *
+ * @example bestAvailable([{ classifier: "ACT", at: "2024-06-15T12:52:00Z", recordedAt: "2024-06-15T12:53:00Z" }, { classifier: "EST", at: "2024-06-15T13:05:00Z", recordedAt: "2024-06-15T14:00:00Z" }]) // { at: "2024-06-15T12:52:00Z", classifier: "ACT" } (an estimate recorded after the actual never replaces it)
+ * @example bestAvailable([{ classifier: "PLN", at: "2024-06-15T12:00:00Z", recordedAt: "2024-06-01T00:00:00Z" }, { classifier: "PLN", at: "2024-06-15T13:00:00Z", recordedAt: "2024-06-10T00:00:00Z" }]) // { at: "2024-06-15T13:00:00Z", classifier: "PLN" } (the newest plan)
+ * @example bestAvailable([{ classifier: "EST", at: "2024-06-15T12:40:00Z", recordedAt: "2024-06-14T00:00:00Z" }, { classifier: "REQ", at: "2024-06-15T12:30:00Z", recordedAt: "2024-06-12T00:00:00Z" }]) // { at: "2024-06-15T12:30:00Z", classifier: "REQ" } (never an EST when a REQ exists)
+ * @example bestAvailable([]) // null
+ * @example bestAvailable([{ classifier: "ETA", at: "2024-06-15T12:40:00Z", recordedAt: "2024-06-14T00:00:00Z" }]) // null (not a timestamp class)
+ */
+export function bestAvailable(events) {
+    try {
+        const parsed = parseTimestampEvents(events);
+        if (parsed === null) {
+            return null;
+        }
+        // `parsed` is in recording order, so the last event of a class is its newest record.
+        const newest = new Map();
+        for (const event of parsed) {
+            newest.set(event.classifier, event.at);
+        }
+        for (const classifier of PRECEDENCE) {
+            const at = newest.get(classifier);
+            if (at !== undefined) {
+                return { at, classifier };
+            }
+        }
+        return null;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,63 @@
+/** What `crossingTime` returns: exact elapsed time plus the local view at either end. */
+export interface Crossing {
+    /**
+     * 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 target zone. */
+    enter: string;
+    /** The exit, rendered in the target zone. */
+    exit: string;
+}
+/**
+ * Measure a crossing — a canal transit, a strait passage, a border queue — and render both ends
+ * in the zone the crossing is administered in.
+ *
+ * A crossing is logged as two instants, and the authority that schedules it reads both on its
+ * own clock. `crossingTime` returns the exact elapsed time between them plus the zone-local
+ * entry and exit. It deliberately counts no calendar days: dwell charged by local days
+ * (`calendarDays`) is `dwellTime`'s job, and a crossing that needs a day count is a dwell.
+ *
+ * - **`duration` is exact elapsed time.** A crossing spanning a DST transition reports the hours
+ *   that actually elapsed; the local wall clocks at either end can be an hour apart from that.
+ *   Hours is the largest unit, so the value never depends on a calendar.
+ * - **`targetZone` is always the rendering zone.** `entry` and `exit` are anything
+ *   `isValidInstant` accepts — `Z`, an offset, or an offset with a bracketed zone — and only the
+ *   instant is read: a bracketed zone in the input is never the zone the result is rendered
+ *   in. That is the one contract difference from `dwellTime`, whose zone may come from its
+ *   entry's bracket.
+ * - **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. A zone that does not exist, or that disagrees with
+ *   the offset, is not checked and changes nothing.
+ * - `targetZone` is whatever `isValidTimeZone` accepts, which is what Temporal accepts: an IANA
+ *   identifier, or a fixed offset such as `"+02:00"`, which observes no DST.
+ * - GMT does not resolve a canal, lock or checkpoint code to a zone; the caller supplies the
+ *   identifier.
+ * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
+ *   crossing is a data error, not a negative transit), or when the zone is invalid. A zero-length
+ *   crossing is `PT0S`.
+ * - 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 entering the crossing
+ * @param exit ISO 8601 zoned datetime or instant string of leaving it
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts) the
+ *   crossing is read in
+ * @returns exact duration and zone-local entry and exit, or null on invalid input
+ *
+ * @example crossingTime("2024-06-15T08:00:00Z", "2024-06-15T17:30:00Z", "Europe/Berlin") // { duration: "PT9H30M", enter: "2024-06-15T10:00:00+02:00[Europe/Berlin]", exit: "2024-06-15T19:30:00+02:00[Europe/Berlin]" }
+ * @example crossingTime("2024-06-15T10:00:00+09:00", "2024-06-15T12:00:00+09:00", "Asia/Tokyo") // { duration: "PT2H", enter: "2024-06-15T10:00:00+09:00[Asia/Tokyo]", exit: "2024-06-15T12:00:00+09:00[Asia/Tokyo]" }
+ * @example crossingTime("2024-03-10T05:00:00Z", "2024-03-10T12:00:00Z", "America/New_York") // { duration: "PT7H", enter: "2024-03-10T00:00:00-05:00[America/New_York]", exit: "2024-03-10T08:00:00-04:00[America/New_York]" } (seven elapsed hours across the spring-forward)
+ * @example crossingTime("2024-11-03T05:30:00Z", "2024-11-03T06:30:00Z", "America/New_York") // { duration: "PT1H", enter: "2024-11-03T01:30:00-04:00[America/New_York]", exit: "2024-11-03T01:30:00-05:00[America/New_York]" } (both ends read 01:30; the offsets tell them apart)
+ * @example crossingTime("2024-06-15T10:00:00Z", "2024-06-15T10:00:00Z", "Asia/Tokyo") // { duration: "PT0S", enter: "2024-06-15T19:00:00+09:00[Asia/Tokyo]", exit: "2024-06-15T19:00:00+09:00[Asia/Tokyo]" }
+ * @example crossingTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "+02:00") // { duration: "PT2H30M", enter: "2024-06-16T00:30:00+02:00[+02:00]", exit: "2024-06-16T03:00:00+02:00[+02:00]" } (a fixed offset renders with no DST)
+ * @example crossingTime("2024-06-16T01:00:00Z", "2024-06-15T22:30:00Z", "Europe/London") // null (exit before entry)
+ * @example crossingTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "Europe/Londres") // null
+ * @example crossingTime("2024-06-15T22:30:00", "2024-06-16T01:00:00Z", "Europe/London") // null (no offset designator: not a moment)
+ */
+export declare function crossingTime(entry: string, exit: string, targetZone: string): Crossing | null;

package/dist/transport/calculate/crossingTime.js

@@ -0,0 +1,81 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { instantFrom } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
+/**
+ * Measure a crossing — a canal transit, a strait passage, a border queue — and render both ends
+ * in the zone the crossing is administered in.
+ *
+ * A crossing is logged as two instants, and the authority that schedules it reads both on its
+ * own clock. `crossingTime` returns the exact elapsed time between them plus the zone-local
+ * entry and exit. It deliberately counts no calendar days: dwell charged by local days
+ * (`calendarDays`) is `dwellTime`'s job, and a crossing that needs a day count is a dwell.
+ *
+ * - **`duration` is exact elapsed time.** A crossing spanning a DST transition reports the hours
+ *   that actually elapsed; the local wall clocks at either end can be an hour apart from that.
+ *   Hours is the largest unit, so the value never depends on a calendar.
+ * - **`targetZone` is always the rendering zone.** `entry` and `exit` are anything
+ *   `isValidInstant` accepts — `Z`, an offset, or an offset with a bracketed zone — and only the
+ *   instant is read: a bracketed zone in the input is never the zone the result is rendered
+ *   in. That is the one contract difference from `dwellTime`, whose zone may come from its
+ *   entry's bracket.
+ * - **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. A zone that does not exist, or that disagrees with
+ *   the offset, is not checked and changes nothing.
+ * - `targetZone` is whatever `isValidTimeZone` accepts, which is what Temporal accepts: an IANA
+ *   identifier, or a fixed offset such as `"+02:00"`, which observes no DST.
+ * - GMT does not resolve a canal, lock or checkpoint code to a zone; the caller supplies the
+ *   identifier.
+ * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
+ *   crossing is a data error, not a negative transit), or when the zone is invalid. A zero-length
+ *   crossing is `PT0S`.
+ * - 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 entering the crossing
+ * @param exit ISO 8601 zoned datetime or instant string of leaving it
+ * @param targetZone IANA name or a UTC offset to the minute (what `isValidTimeZone` accepts) the
+ *   crossing is read in
+ * @returns exact duration and zone-local entry and exit, or null on invalid input
+ *
+ * @example crossingTime("2024-06-15T08:00:00Z", "2024-06-15T17:30:00Z", "Europe/Berlin") // { duration: "PT9H30M", enter: "2024-06-15T10:00:00+02:00[Europe/Berlin]", exit: "2024-06-15T19:30:00+02:00[Europe/Berlin]" }
+ * @example crossingTime("2024-06-15T10:00:00+09:00", "2024-06-15T12:00:00+09:00", "Asia/Tokyo") // { duration: "PT2H", enter: "2024-06-15T10:00:00+09:00[Asia/Tokyo]", exit: "2024-06-15T12:00:00+09:00[Asia/Tokyo]" }
+ * @example crossingTime("2024-03-10T05:00:00Z", "2024-03-10T12:00:00Z", "America/New_York") // { duration: "PT7H", enter: "2024-03-10T00:00:00-05:00[America/New_York]", exit: "2024-03-10T08:00:00-04:00[America/New_York]" } (seven elapsed hours across the spring-forward)
+ * @example crossingTime("2024-11-03T05:30:00Z", "2024-11-03T06:30:00Z", "America/New_York") // { duration: "PT1H", enter: "2024-11-03T01:30:00-04:00[America/New_York]", exit: "2024-11-03T01:30:00-05:00[America/New_York]" } (both ends read 01:30; the offsets tell them apart)
+ * @example crossingTime("2024-06-15T10:00:00Z", "2024-06-15T10:00:00Z", "Asia/Tokyo") // { duration: "PT0S", enter: "2024-06-15T19:00:00+09:00[Asia/Tokyo]", exit: "2024-06-15T19:00:00+09:00[Asia/Tokyo]" }
+ * @example crossingTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "+02:00") // { duration: "PT2H30M", enter: "2024-06-16T00:30:00+02:00[+02:00]", exit: "2024-06-16T03:00:00+02:00[+02:00]" } (a fixed offset renders with no DST)
+ * @example crossingTime("2024-06-16T01:00:00Z", "2024-06-15T22:30:00Z", "Europe/London") // null (exit before entry)
+ * @example crossingTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "Europe/Londres") // null
+ * @example crossingTime("2024-06-15T22:30:00", "2024-06-16T01:00:00Z", "Europe/London") // null (no offset designator: not a moment)
+ */
+export function crossingTime(entry, exit, targetZone) {
+    try {
+        // fallow-ignore-next-line code-duplication -- not delegated to dwellTime: its transition walk returns null past 10,000 transitions, a false null for a long crossing, and its calendar-day count is work crossingTime does not use
+        if (!isValidInstant(entry) ||
+            !isValidInstant(exit) ||
+            !isValidTimeZone(targetZone)) {
+            return null;
+        }
+        const entryInstant = instantFrom(entry);
+        const exitInstant = instantFrom(exit);
+        if (Temporal.Instant.compare(entryInstant, exitInstant) > 0) {
+            return null;
+        }
+        return {
+            duration: entryInstant
+                .until(exitInstant, { largestUnit: "hours" })
+                .toString(),
+            enter: entryInstant.toZonedDateTimeISO(targetZone).toString(),
+            exit: exitInstant.toZonedDateTimeISO(targetZone).toString(),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,95 @@
+import type { BusinessCalendar, RollConvention } from "../../types/index.js";
+/** Options for `cutoffAt`. */
+export interface CutoffOptions {
+    /**
+     * The time zone the cut-off is read in, the terminal's clock: an IANA name or a UTC offset to the
+     * minute (what `isValidTimeZone` accepts).
+     */
+    timeZone: string;
+    /**
+     * The local time of day the cut-off is pinned to (`"17:00"`), as `isValidTime` accepts.
+     *
+     * @defaultValue None. The cut-off is the offset taken off the anchor, with no time of day
+     * pinned.
+     */
+    atLocalTime?: string;
+    /**
+     * The working week and holidays the cut-off's local date is rolled against. Its `timeZone` is
+     * not read: `timeZone` above is the local frame. Requires `roll`.
+     *
+     * @defaultValue None. The cut-off's date is not rolled; a `roll` without it returns `""`.
+     */
+    calendar?: BusinessCalendar;
+    /**
+     * How a cut-off on a non-business day moves, as `rollDate` moves it. Requires `calendar`.
+     *
+     * @defaultValue None. The cut-off's date is not rolled; a `calendar` without it returns `""`.
+     */
+    roll?: RollConvention;
+}
+/**
+ * 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.
+ * - 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 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 declare function cutoffAt(anchor: string, offset: string, options: CutoffOptions): string;

package/dist/transport/calculate/cutoffAt.js

@@ -0,0 +1,211 @@
+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.
+ * - 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 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 "";
+    }
+}