@northguild/gmt 1.17.0 → 1.18.0

package/dist/span/calculate/spanMs.d.ts

@@ -16,9 +16,14 @@
  *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
  *   which is the one string shape `spanWallClock` accepts and these two do not. The
  *   endpoints need not share a zone; an instant is an instant.
- * - **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. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - **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. `spanWallClock`, by
+ *   contrast, rejects a mismatched offset.
  * - Returns `null` on invalid input, not `0` — `0` is the span between an instant and itself.
  *   `null`, not `NaN`, because that is GMT's sentinel for every number-returning function:
  *   it is the one a caller already checks for, and the only one `strictNullChecks` forces
@@ -45,7 +50,8 @@
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00.123456789Z") // 123.456789
  * @example spanMs("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 82800000 — 23 hours, not 24
- * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is ignored
+ * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is not checked
+ * @example spanMs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0 — the zone's −00:44:30, which `-00:45` rounds
  * @example spanMs("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // null — past the safe integer range, use spanNs
  * @example spanMs("2024-03-10T12:00:00Z", "invalid") // null
  */

package/dist/span/calculate/spanMs.js

@@ -28,9 +28,14 @@ const MAX_SAFE_NANOSECONDS = BigInt(Number.MAX_SAFE_INTEGER) * NANOSECONDS_PER_M
  *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
  *   which is the one string shape `spanWallClock` accepts and these two do not. The
  *   endpoints need not share a zone; an instant is an instant.
- * - **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. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - **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. `spanWallClock`, by
+ *   contrast, rejects a mismatched offset.
  * - Returns `null` on invalid input, not `0` — `0` is the span between an instant and itself.
  *   `null`, not `NaN`, because that is GMT's sentinel for every number-returning function:
  *   it is the one a caller already checks for, and the only one `strictNullChecks` forces
@@ -57,7 +62,8 @@ const MAX_SAFE_NANOSECONDS = BigInt(Number.MAX_SAFE_INTEGER) * NANOSECONDS_PER_M
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00.123456789Z") // 123.456789
  * @example spanMs("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 82800000 — 23 hours, not 24
- * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is ignored
+ * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is not checked
+ * @example spanMs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0 — the zone's −00:44:30, which `-00:45` rounds
  * @example spanMs("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // null — past the safe integer range, use spanNs
  * @example spanMs("2024-03-10T12:00:00Z", "invalid") // null
  */

package/dist/span/calculate/spanNs.d.ts

@@ -14,9 +14,14 @@
  *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
  *   which is the one string shape `spanWallClock` accepts and these two do not. The
  *   endpoints need not share a zone; an instant is an instant.
- * - **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. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - **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. `spanWallClock`, by
+ *   contrast, rejects a mismatched offset.
  * - Returns `null` on invalid input, not `0n` — `0n` is the span between an instant and
  *   itself. This is why it does not simply subtract two `toNanoseconds` results, which
  *   return `0n` for both the epoch and a rejected string.
@@ -37,7 +42,8 @@
  * @example spanNs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0n
  * @example spanNs("2024-03-10T12:00:00.123456789Z", "2024-03-10T12:00:00.123456790Z") // 1n
  * @example spanNs("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // 0n — same instant, different zones
- * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is ignored
+ * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is not checked
+ * @example spanNs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0n — the zone's −00:44:30, which `-00:45` rounds
  * @example spanNs("2024-03-10T12:00:00Z", "invalid") // null
  */
 export declare function spanNs(start: string, end: string): bigint | null;

package/dist/span/calculate/spanNs.js

@@ -15,9 +15,14 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
  *   which is the one string shape `spanWallClock` accepts and these two do not. The
  *   endpoints need not share a zone; an instant is an instant.
- * - **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. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - **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. `spanWallClock`, by
+ *   contrast, rejects a mismatched offset.
  * - Returns `null` on invalid input, not `0n` — `0n` is the span between an instant and
  *   itself. This is why it does not simply subtract two `toNanoseconds` results, which
  *   return `0n` for both the epoch and a rejected string.
@@ -38,7 +43,8 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  * @example spanNs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0n
  * @example spanNs("2024-03-10T12:00:00.123456789Z", "2024-03-10T12:00:00.123456790Z") // 1n
  * @example spanNs("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // 0n — same instant, different zones
- * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is ignored
+ * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is not checked
+ * @example spanNs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0n — the zone's −00:44:30, which `-00:45` rounds
  * @example spanNs("2024-03-10T12:00:00Z", "invalid") // null
  */
 export function spanNs(start, end) {

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,58 @@
+/** 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`.
+ *
+ * @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 timeZone identifier or fixed offset 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,76 @@
+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`.
+ *
+ * @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 timeZone identifier or fixed offset 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,90 @@
+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. */
+    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.
+ *
+ * @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;