@northguild/gmt 1.18.0 → 1.20.0

package/dist/intermodal/calculate/demurrageClock.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import { instantFrom, isObject } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
 import { optionOrDefault } from "../../internal/optionOrDefault.js";
@@ -77,7 +77,7 @@ const EXPORT_CLOCKS = {
  * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "demurrage", { direction: "export" }) // { start: "2024-07-05T16:00:00Z", end: "2024-07-09T03:00:00Z" } (gate-in full to loaded on board)
  * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "detention", { direction: "export" }) // { start: "2024-07-01T08:00:00Z", end: "2024-07-05T16:00:00Z" } (empty picked up to gate-in full)
  * @example demurrageClock([{ type: "emptyReleased", at: "2024-07-01T08:00:00Z" }, { type: "gatedIn", at: "2024-07-05T16:00:00Z" }, { type: "loaded", at: "2024-07-09T03:00:00Z" }], "combined", { direction: "export" }) // { start: "2024-07-01T08:00:00Z", end: "2024-07-09T03:00:00Z" }
- * @example demurrageClock([{ type: "gatedOut", at: "2024-06-20T10:30:00-04:00[America/New_York]" }, { type: "emptyReturned", at: "2024-06-27T09:00:00Z" }], "detention", { direction: "import", startEvent: "available" }) // { start: "2024-06-20T10:30:00-04:00[America/New_York]", end: "2024-06-27T09:00:00Z" } (startEvent is not read for detention; strings are echoed as given)
+ * @example demurrageClock([{ type: "gatedOut", at: "2024-06-20T10:30:00+02:00[Africa/Johannesburg]" }, { type: "emptyReturned", at: "2024-06-27T09:00:00Z" }], "detention", { direction: "import", startEvent: "available" }) // { start: "2024-06-20T10:30:00+02:00[Africa/Johannesburg]", end: "2024-06-27T09:00:00Z" } (startEvent is not read for detention; strings are echoed as given)
  * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage") // null (direction has no default)
  * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import", startEvent: "available" }) // null (no availability event)
  * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }], "demurrage", { direction: "import" }) // null (still in the terminal: no gate-out)

package/dist/intermodal/calculate/freeTimeExpiry.d.ts

@@ -46,22 +46,29 @@ export interface FreeTime {
  *   least `1`, `options` is not an object, `basis` or `firstDay` is missing or unknown,
  *   `timeZone` is invalid, `basis` is `"working"` without a valid `BusinessCalendar`, or the walk
  *   would pass 10,000 local days.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param clockStart ISO 8601 instant string of the event that starts the clock (discharge, availability or gate-out)
  * @param freeDays whole number of free days the tariff allows, at least 1
  * @param options The tariff's counting terms: which days count, in which zone, and where day one starts
  * @returns the free-time start and last free day as local dates, and the expiry instant, or null on invalid input
  *
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-16", expiresAt: "2024-06-17T04:00:00Z" } (a Friday discharge: the weekend is consumed)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeTimeStart: "2024-06-15", lastFreeDay: "2024-06-17", expiresAt: "2024-06-18T04:00:00Z" } (the same tariff read the other way: one more day)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (Friday, Monday, Tuesday: the weekend does not count)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-17"], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-19", expiresAt: "2024-06-20T04:00:00Z" } (a terminal holiday on the Monday moves expiry a day)
- * @example freeTimeExpiry("2024-06-15T14:00:00Z", 2, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-17", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (a Saturday discharge: free time starts Monday)
- * @example freeTimeExpiry("2024-06-15T03:00:00Z", 1, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-14", expiresAt: "2024-06-15T04:00:00Z" } (23:00 local on the 14th: the free day is over an hour later)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-16", expiresAt: "2024-06-17T04:00:00Z" } (a Friday discharge: the weekend is consumed)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "nextDay" }) // { freeTimeStart: "2024-06-15", lastFreeDay: "2024-06-17", expiresAt: "2024-06-18T04:00:00Z" } (the same tariff read the other way: one more day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/Port_of_Spain", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/Port_of_Spain" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (Friday, Monday, Tuesday: the weekend does not count)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/Port_of_Spain", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-17"], timeZone: "America/Port_of_Spain" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-19", expiresAt: "2024-06-20T04:00:00Z" } (a terminal holiday on the Monday moves expiry a day)
+ * @example freeTimeExpiry("2024-06-15T14:00:00Z", 2, { basis: "working", timeZone: "America/Port_of_Spain", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/Port_of_Spain" } }) // { freeTimeStart: "2024-06-17", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (a Saturday discharge: free time starts Monday)
+ * @example freeTimeExpiry("2024-06-15T03:00:00Z", 1, { basis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-14", expiresAt: "2024-06-15T04:00:00Z" } (23:00 local on the 14th: the free day is over an hour later)
  * @example freeTimeExpiry("2024-09-07T15:00:00Z", 1, { basis: "calendar", timeZone: "America/Santiago", firstDay: "eventDay" }) // { freeTimeStart: "2024-09-07", lastFreeDay: "2024-09-07", expiresAt: "2024-09-08T04:00:00Z" } (Santiago skipped midnight on the 8th, so the day starts at 01:00)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay" }) // null (a working-day count needs the terminal's calendar)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 0, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no free days means no last free day)
- * @example freeTimeExpiry("2024-06-14T19:00:00", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no offset: not an instant)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "Europe/London" }) // null (firstDay has no default)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "Asia/Tokyo", firstDay: "eventDay" }) // null (a working-day count needs the terminal's calendar)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 0, { basis: "calendar", timeZone: "Australia/Sydney", firstDay: "eventDay" }) // null (no free days means no last free day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00", 3, { basis: "calendar", timeZone: "Asia/Kolkata", firstDay: "eventDay" }) // null (no offset: not an instant)
+ * @example freeTimeExpiry("1970-01-01T00:30:00Z", 3, { basis: "calendar", firstDay: "eventDay", timeZone: "-00:44:30" }) // { freeTimeStart: "1969-12-31", lastFreeDay: "1970-01-02", expiresAt: "1970-01-03T00:44:30Z" }
  */
 export declare function freeTimeExpiry(clockStart: string, freeDays: number, options: FreeTimeOptions): FreeTime | null;

package/dist/intermodal/calculate/freeTimeExpiry.js

@@ -1,4 +1,6 @@
-import { instantFrom, parseFreeDays, parseFreeTimeTerms, walkFreeTime, } from "../../internal/index.js";
+import { isoDateString } from "../../internal/epochDay.js";
+import { Temporal } from "../../internal/temporal.js";
+import { frameZoned, instantFrom, parseFreeDays, parseFreeTimeTerms, walkFreeTime, zoneFrame, } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
 /**
  * Lay out a container's free time from the instant its clock started, and say when it ends.
@@ -38,40 +40,53 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  *   least `1`, `options` is not an object, `basis` or `firstDay` is missing or unknown,
  *   `timeZone` is invalid, `basis` is `"working"` without a valid `BusinessCalendar`, or the walk
  *   would pass 10,000 local days.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param clockStart ISO 8601 instant string of the event that starts the clock (discharge, availability or gate-out)
  * @param freeDays whole number of free days the tariff allows, at least 1
  * @param options The tariff's counting terms: which days count, in which zone, and where day one starts
  * @returns the free-time start and last free day as local dates, and the expiry instant, or null on invalid input
  *
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-16", expiresAt: "2024-06-17T04:00:00Z" } (a Friday discharge: the weekend is consumed)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "nextDay" }) // { freeTimeStart: "2024-06-15", lastFreeDay: "2024-06-17", expiresAt: "2024-06-18T04:00:00Z" } (the same tariff read the other way: one more day)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (Friday, Monday, Tuesday: the weekend does not count)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-17"], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-19", expiresAt: "2024-06-20T04:00:00Z" } (a terminal holiday on the Monday moves expiry a day)
- * @example freeTimeExpiry("2024-06-15T14:00:00Z", 2, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/New_York" } }) // { freeTimeStart: "2024-06-17", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (a Saturday discharge: free time starts Monday)
- * @example freeTimeExpiry("2024-06-15T03:00:00Z", 1, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-14", expiresAt: "2024-06-15T04:00:00Z" } (23:00 local on the 14th: the free day is over an hour later)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-16", expiresAt: "2024-06-17T04:00:00Z" } (a Friday discharge: the weekend is consumed)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "nextDay" }) // { freeTimeStart: "2024-06-15", lastFreeDay: "2024-06-17", expiresAt: "2024-06-18T04:00:00Z" } (the same tariff read the other way: one more day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/Port_of_Spain", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/Port_of_Spain" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (Friday, Monday, Tuesday: the weekend does not count)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/Port_of_Spain", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: ["2024-06-17"], timeZone: "America/Port_of_Spain" } }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-19", expiresAt: "2024-06-20T04:00:00Z" } (a terminal holiday on the Monday moves expiry a day)
+ * @example freeTimeExpiry("2024-06-15T14:00:00Z", 2, { basis: "working", timeZone: "America/Port_of_Spain", firstDay: "eventDay", calendar: { weekend: [6, 7], holidays: [], timeZone: "America/Port_of_Spain" } }) // { freeTimeStart: "2024-06-17", lastFreeDay: "2024-06-18", expiresAt: "2024-06-19T04:00:00Z" } (a Saturday discharge: free time starts Monday)
+ * @example freeTimeExpiry("2024-06-15T03:00:00Z", 1, { basis: "calendar", timeZone: "America/Port_of_Spain", firstDay: "eventDay" }) // { freeTimeStart: "2024-06-14", lastFreeDay: "2024-06-14", expiresAt: "2024-06-15T04:00:00Z" } (23:00 local on the 14th: the free day is over an hour later)
  * @example freeTimeExpiry("2024-09-07T15:00:00Z", 1, { basis: "calendar", timeZone: "America/Santiago", firstDay: "eventDay" }) // { freeTimeStart: "2024-09-07", lastFreeDay: "2024-09-07", expiresAt: "2024-09-08T04:00:00Z" } (Santiago skipped midnight on the 8th, so the day starts at 01:00)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "America/New_York" }) // null (firstDay has no default)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "America/New_York", firstDay: "eventDay" }) // null (a working-day count needs the terminal's calendar)
- * @example freeTimeExpiry("2024-06-14T19:00:00Z", 0, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no free days means no last free day)
- * @example freeTimeExpiry("2024-06-14T19:00:00", 3, { basis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // null (no offset: not an instant)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "calendar", timeZone: "Europe/London" }) // null (firstDay has no default)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 3, { basis: "working", timeZone: "Asia/Tokyo", firstDay: "eventDay" }) // null (a working-day count needs the terminal's calendar)
+ * @example freeTimeExpiry("2024-06-14T19:00:00Z", 0, { basis: "calendar", timeZone: "Australia/Sydney", firstDay: "eventDay" }) // null (no free days means no last free day)
+ * @example freeTimeExpiry("2024-06-14T19:00:00", 3, { basis: "calendar", timeZone: "Asia/Kolkata", firstDay: "eventDay" }) // null (no offset: not an instant)
+ * @example freeTimeExpiry("1970-01-01T00:30:00Z", 3, { basis: "calendar", firstDay: "eventDay", timeZone: "-00:44:30" }) // { freeTimeStart: "1969-12-31", lastFreeDay: "1970-01-02", expiresAt: "1970-01-03T00:44:30Z" }
  */
 export function freeTimeExpiry(clockStart, freeDays, options) {
     try {
         const terms = parseFreeTimeTerms(options);
         const allowed = parseFreeDays(freeDays, 1);
-        if (!isValidInstant(clockStart) || terms === null || allowed === null) {
+        const frame = terms === null ? null : zoneFrame(terms.timeZone);
+        if (!isValidInstant(clockStart) ||
+            terms === null ||
+            frame === null ||
+            allowed === null) {
             return null;
         }
-        const start = instantFrom(clockStart).toZonedDateTimeISO(terms.timeZone);
+        const start = frameZoned(instantFrom(clockStart), frame);
         const ledger = walkFreeTime(start, allowed, terms);
-        if (ledger === null) {
+        if (ledger === null ||
+            ledger.firstFree === null ||
+            ledger.lastFree === null) {
             return null;
         }
         return {
-            freeTimeStart: ledger.free[0].date,
-            lastFreeDay: ledger.free[allowed - 1].date,
-            expiresAt: ledger.expiresAt.toInstant().toString(),
+            freeTimeStart: isoDateString(ledger.firstFree),
+            lastFreeDay: isoDateString(ledger.lastFree),
+            expiresAt: Temporal.Instant.fromEpochNanoseconds(ledger.expiresAtNs).toString(),
         };
     }
     catch {

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

@@ -2,3 +2,4 @@ export * from "./billingTimeline.js";
 export * from "./chargeableDays.js";
 export * from "./demurrageClock.js";
 export * from "./freeTimeExpiry.js";
+export * from "./multimodalETA.js";

package/dist/intermodal/calculate/index.js

@@ -2,3 +2,4 @@ export * from "./billingTimeline.js";
 export * from "./chargeableDays.js";
 export * from "./demurrageClock.js";
 export * from "./freeTimeExpiry.js";
+export * from "./multimodalETA.js";

package/dist/intermodal/calculate/multimodalETA.d.ts

@@ -0,0 +1,76 @@
+import { type Leg, type ScheduleDeliveryOptions } from "../../transport/calculate/scheduleDelivery.js";
+/** What `multimodalETA` returns: the end-to-end ETA, with the time moving and the time waiting kept apart. */
+export interface MultimodalJourney {
+    /** The last leg's arrival rendered in its `timeZone`, as `scheduleDelivery` gives it. `""` only for an empty legs array. */
+    eta: string;
+    /** The number of legs in the journey. */
+    totalLegs: number;
+    /**
+     * The time the cargo spent moving: every leg's `duration` added up, as an ISO 8601 duration of
+     * elapsed time with hours as the largest unit.
+     */
+    totalTransit: string;
+    /**
+     * The time the cargo spent at the handoffs between legs: each leg's departure minus the previous
+     * leg's arrival, added up, in the same form as `totalTransit`. It includes any wait for a
+     * scheduled departure on top of the handoff's `dwellAfter`.
+     */
+    totalDwell: string;
+}
+/**
+ * Compute an end-to-end ETA across the legs of a multimodal move, and report the time in transit
+ * and the time in dwell separately.
+ *
+ * A truck→ship→rail move spends its time two ways: moving, and sitting at a handoff. The two are
+ * forecast differently and fail differently, so one opaque total hides the part a planner needs.
+ * `multimodalETA` schedules the legs with `scheduleDelivery` and splits the elapsed time from the
+ * first departure to the ETA into the two.
+ *
+ * - **The legs are `scheduleDelivery`'s.** Each leg's arrival plus its `dwellAfter` is the next
+ *   leg's departure unless the next leg names a scheduled `departure`; a scheduled departure
+ *   inside the dwell is a missed connection. Departures, zones and every validity rule are that
+ *   function's, and `eta` is its `eta`.
+ * - **Local-time resolution policy (`"compatible"`), as `scheduleDelivery` applies it.** A zoneless
+ *   first departure read in `startTimeZone`, a zoneless later-leg departure read in the previous
+ *   leg's `timeZone`, and a zoned departure written without an offset are wall times. An
+ *   **ambiguous** one (a fall-back hour the clock ran through twice) resolves to the **earlier**
+ *   instant and a **nonexistent** one (a spring-forward hour the clock skipped) to the **later**
+ *   instant, except that on any leg but the first a repeated hour takes the earliest pass at or
+ *   after the previous arrival plus its dwell, the first the cargo can catch. Write the offset to
+ *   pick a pass yourself.
+ * - **`totalTransit` is every leg's `duration` added up.** Durations are exact time: a day is 24
+ *   hours, and years, months and weeks return `null`. The sum is elapsed time, so a leg across a
+ *   DST change counts the hours that passed, not the change in the wall clock.
+ * - **`totalDwell` is the time actually spent at the handoffs**: each leg's departure minus the
+ *   previous leg's arrival. When every leg after the first chains from its predecessor, that is the
+ *   sum of the `dwellAfter` values. When a leg waits for a scheduled departure, the wait is dwell
+ *   too: the cargo is at the handoff either way. Dwell is never estimated; it is the caller's
+ *   `dwellAfter` and schedule.
+ * - **Transit plus dwell is the elapsed time** from the first departure to the ETA, exactly.
+ * - **The last leg's `dwellAfter` is not dwell.** There is no handoff after it, so it moves
+ *   nothing; it is still checked as a duration, as `scheduleDelivery` checks it.
+ * - Both totals are ISO 8601 durations with hours as the largest unit (`"PT400H"`, `"PT2H15M"`),
+ *   as `crossingTime` and `dwellTime` report elapsed time; they do not depend on any zone.
+ * - Each leg's fields are read once, so the totals always agree with the schedule.
+ * - An empty legs array returns `{ eta: "", totalLegs: 0, totalTransit: "PT0S", totalDwell: "PT0S" }`.
+ *   Returns `null` on invalid input: a non-array, a malformed leg, a missed connection, an invalid
+ *   `startTimeZone`, or an arrival outside the instant range.
+ * - An offset with seconds (`-00:44:30`) as a leg's `timeZone` or as `startTimeZone` returns
+ *   `null`, as in `scheduleDelivery`. A written zone cannot carry seconds (RFC 9557 §4.1), so `eta`
+ *   could not name it. Pass the IANA name.
+ *
+ * @param legs the journey's legs, in travel order
+ * @param options The zone a zoneless first-leg departure is read in
+ * @returns the ETA, the number of legs, and the total transit and dwell, or null on invalid input
+ *
+ * @example multimodalETA([{ departure: "2024-06-10T08:00:00+08:00[Asia/Shanghai]", duration: "PT6H", timeZone: "Asia/Shanghai", dwellAfter: "P2D" }, { duration: "P14DT6H", timeZone: "America/Los_Angeles", dwellAfter: "PT36H" }, { duration: "PT52H", timeZone: "America/Chicago" }]) // { eta: "2024-06-29T23:00:00-05:00[America/Chicago]", totalLegs: 3, totalTransit: "PT400H", totalDwell: "PT84H" } (truck, ship and rail: 484 hours door to door)
+ * @example multimodalETA([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { duration: "PT5H", timeZone: "Asia/Tokyo" }]) // { eta: "2024-06-16T02:00:00+09:00[Asia/Tokyo]", totalLegs: 2, totalTransit: "PT15H", totalDwell: "PT2H" }
+ * @example multimodalETA([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { departure: "2024-06-15T13:00:00Z", duration: "PT1H", timeZone: "UTC" }]) // { eta: "2024-06-15T14:00:00+00:00[UTC]", totalLegs: 2, totalTransit: "PT11H", totalDwell: "PT3H" } (two hours' handling and an hour's wait for the 13:00 departure)
+ * @example multimodalETA([{ departure: "2024-06-15T10:00:00Z", duration: "PT36H", timeZone: "Asia/Tokyo", dwellAfter: "PT5H" }]) // { eta: "2024-06-17T07:00:00+09:00[Asia/Tokyo]", totalLegs: 1, totalTransit: "PT36H", totalDwell: "PT0S" } (no handoff after the last leg)
+ * @example multimodalETA([{ departure: "2024-06-15T10:00:00", duration: "PT1H", timeZone: "UTC" }], { startTimeZone: "America/Sao_Paulo" }) // { eta: "2024-06-15T14:00:00+00:00[UTC]", totalLegs: 1, totalTransit: "PT1H", totalDwell: "PT0S" } (a published 10:00 wall time, read in São Paulo)
+ * @example multimodalETA([]) // { eta: "", totalLegs: 0, totalTransit: "PT0S", totalDwell: "PT0S" }
+ * @example multimodalETA([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { departure: "2024-06-15T11:00:00Z", duration: "PT1H", timeZone: "UTC" }]) // null (the connection leaves inside the dwell: missed)
+ * @example multimodalETA([{ departure: "2024-06-15T10:00:00Z", duration: "P1M", timeZone: "UTC" }]) // null (calendar units have no exact length)
+ * @example multimodalETA("legs") // null
+ */
+export declare function multimodalETA(legs: Leg[], options?: ScheduleDeliveryOptions): MultimodalJourney | null;

package/dist/intermodal/calculate/multimodalETA.js

@@ -0,0 +1,145 @@
+import { Temporal } from "../../internal/temporal.js";
+import { exactDurationNanoseconds } from "../../internal/index.js";
+import { formatHourDuration } from "../../internal/hourDurationString.js";
+import { scheduleDelivery, } from "../../transport/calculate/scheduleDelivery.js";
+import { isObject } from "../../internal/isObject.js";
+/**
+ * Every field of a `Leg`, each read once into a plain copy. Typed as a record of `keyof Leg`, so a
+ * field added to `Leg` and missing here, or a key here that `Leg` does not have, fails to compile
+ * rather than being dropped from the copy.
+ */
+const LEG_FIELDS = {
+    departure: true,
+    duration: true,
+    timeZone: true,
+    dwellAfter: true,
+    mode: true,
+    origin: true,
+    destination: true,
+};
+const LEG_KEYS = Object.keys(LEG_FIELDS);
+/**
+ * A plain copy of one leg with every field read exactly once, so the schedule and the totals are
+ * computed from the same values even when a field is a getter. An undefined field stays absent,
+ * which `scheduleDelivery` reads as omitted either way. A leg that is not an object is passed
+ * through for `scheduleDelivery` to refuse.
+ */
+function snapshotLeg(leg) {
+    if (!isObject(leg)) {
+        return leg;
+    }
+    const copy = {};
+    for (const key of LEG_KEYS) {
+        const value = Reflect.get(leg, key);
+        if (value !== undefined) {
+            copy[key] = value;
+        }
+    }
+    return copy;
+}
+/**
+ * Compute an end-to-end ETA across the legs of a multimodal move, and report the time in transit
+ * and the time in dwell separately.
+ *
+ * A truck→ship→rail move spends its time two ways: moving, and sitting at a handoff. The two are
+ * forecast differently and fail differently, so one opaque total hides the part a planner needs.
+ * `multimodalETA` schedules the legs with `scheduleDelivery` and splits the elapsed time from the
+ * first departure to the ETA into the two.
+ *
+ * - **The legs are `scheduleDelivery`'s.** Each leg's arrival plus its `dwellAfter` is the next
+ *   leg's departure unless the next leg names a scheduled `departure`; a scheduled departure
+ *   inside the dwell is a missed connection. Departures, zones and every validity rule are that
+ *   function's, and `eta` is its `eta`.
+ * - **Local-time resolution policy (`"compatible"`), as `scheduleDelivery` applies it.** A zoneless
+ *   first departure read in `startTimeZone`, a zoneless later-leg departure read in the previous
+ *   leg's `timeZone`, and a zoned departure written without an offset are wall times. An
+ *   **ambiguous** one (a fall-back hour the clock ran through twice) resolves to the **earlier**
+ *   instant and a **nonexistent** one (a spring-forward hour the clock skipped) to the **later**
+ *   instant, except that on any leg but the first a repeated hour takes the earliest pass at or
+ *   after the previous arrival plus its dwell, the first the cargo can catch. Write the offset to
+ *   pick a pass yourself.
+ * - **`totalTransit` is every leg's `duration` added up.** Durations are exact time: a day is 24
+ *   hours, and years, months and weeks return `null`. The sum is elapsed time, so a leg across a
+ *   DST change counts the hours that passed, not the change in the wall clock.
+ * - **`totalDwell` is the time actually spent at the handoffs**: each leg's departure minus the
+ *   previous leg's arrival. When every leg after the first chains from its predecessor, that is the
+ *   sum of the `dwellAfter` values. When a leg waits for a scheduled departure, the wait is dwell
+ *   too: the cargo is at the handoff either way. Dwell is never estimated; it is the caller's
+ *   `dwellAfter` and schedule.
+ * - **Transit plus dwell is the elapsed time** from the first departure to the ETA, exactly.
+ * - **The last leg's `dwellAfter` is not dwell.** There is no handoff after it, so it moves
+ *   nothing; it is still checked as a duration, as `scheduleDelivery` checks it.
+ * - Both totals are ISO 8601 durations with hours as the largest unit (`"PT400H"`, `"PT2H15M"`),
+ *   as `crossingTime` and `dwellTime` report elapsed time; they do not depend on any zone.
+ * - Each leg's fields are read once, so the totals always agree with the schedule.
+ * - An empty legs array returns `{ eta: "", totalLegs: 0, totalTransit: "PT0S", totalDwell: "PT0S" }`.
+ *   Returns `null` on invalid input: a non-array, a malformed leg, a missed connection, an invalid
+ *   `startTimeZone`, or an arrival outside the instant range.
+ * - An offset with seconds (`-00:44:30`) as a leg's `timeZone` or as `startTimeZone` returns
+ *   `null`, as in `scheduleDelivery`. A written zone cannot carry seconds (RFC 9557 §4.1), so `eta`
+ *   could not name it. Pass the IANA name.
+ *
+ * @param legs the journey's legs, in travel order
+ * @param options The zone a zoneless first-leg departure is read in
+ * @returns the ETA, the number of legs, and the total transit and dwell, or null on invalid input
+ *
+ * @example multimodalETA([{ departure: "2024-06-10T08:00:00+08:00[Asia/Shanghai]", duration: "PT6H", timeZone: "Asia/Shanghai", dwellAfter: "P2D" }, { duration: "P14DT6H", timeZone: "America/Los_Angeles", dwellAfter: "PT36H" }, { duration: "PT52H", timeZone: "America/Chicago" }]) // { eta: "2024-06-29T23:00:00-05:00[America/Chicago]", totalLegs: 3, totalTransit: "PT400H", totalDwell: "PT84H" } (truck, ship and rail: 484 hours door to door)
+ * @example multimodalETA([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { duration: "PT5H", timeZone: "Asia/Tokyo" }]) // { eta: "2024-06-16T02:00:00+09:00[Asia/Tokyo]", totalLegs: 2, totalTransit: "PT15H", totalDwell: "PT2H" }
+ * @example multimodalETA([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { departure: "2024-06-15T13:00:00Z", duration: "PT1H", timeZone: "UTC" }]) // { eta: "2024-06-15T14:00:00+00:00[UTC]", totalLegs: 2, totalTransit: "PT11H", totalDwell: "PT3H" } (two hours' handling and an hour's wait for the 13:00 departure)
+ * @example multimodalETA([{ departure: "2024-06-15T10:00:00Z", duration: "PT36H", timeZone: "Asia/Tokyo", dwellAfter: "PT5H" }]) // { eta: "2024-06-17T07:00:00+09:00[Asia/Tokyo]", totalLegs: 1, totalTransit: "PT36H", totalDwell: "PT0S" } (no handoff after the last leg)
+ * @example multimodalETA([{ departure: "2024-06-15T10:00:00", duration: "PT1H", timeZone: "UTC" }], { startTimeZone: "America/Sao_Paulo" }) // { eta: "2024-06-15T14:00:00+00:00[UTC]", totalLegs: 1, totalTransit: "PT1H", totalDwell: "PT0S" } (a published 10:00 wall time, read in São Paulo)
+ * @example multimodalETA([]) // { eta: "", totalLegs: 0, totalTransit: "PT0S", totalDwell: "PT0S" }
+ * @example multimodalETA([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { departure: "2024-06-15T11:00:00Z", duration: "PT1H", timeZone: "UTC" }]) // null (the connection leaves inside the dwell: missed)
+ * @example multimodalETA([{ departure: "2024-06-15T10:00:00Z", duration: "P1M", timeZone: "UTC" }]) // null (calendar units have no exact length)
+ * @example multimodalETA("legs") // null
+ */
+export function multimodalETA(legs, options) {
+    try {
+        if (!Array.isArray(legs)) {
+            return null;
+        }
+        const snapshot = legs.map(snapshotLeg);
+        const schedule = scheduleDelivery(snapshot, options);
+        if (schedule === null) {
+            return null;
+        }
+        const first = schedule.legTimes.at(0);
+        const last = schedule.legTimes.at(-1);
+        if (first === undefined || last === undefined) {
+            return {
+                eta: "",
+                totalLegs: 0,
+                totalTransit: "PT0S",
+                totalDwell: "PT0S",
+            };
+        }
+        // scheduleDelivery has accepted every duration as exact and not negative.
+        const durations = snapshot.map((leg) => exactDurationNanoseconds(leg.duration));
+        if (durations.some((nanoseconds) => nanoseconds === null)) {
+            return null;
+        }
+        const transit = durations.reduce((sum, ns) => sum + ns, 0n);
+        // Arrivals are the Z strings scheduleDelivery wrote. The first leg left its own duration
+        // before it arrived; the time between that departure and the last arrival that was not spent
+        // moving was spent at the handoffs.
+        const departure = Temporal.Instant.from(first.arrival).epochNanoseconds -
+            durations[0];
+        const elapsed = Temporal.Instant.from(last.arrival).epochNanoseconds - departure;
+        const totalTransit = formatHourDuration(transit);
+        const totalDwell = formatHourDuration(elapsed - transit);
+        if (totalTransit === "" || totalDwell === "") {
+            return null;
+        }
+        return {
+            eta: schedule.eta,
+            totalLegs: snapshot.length,
+            totalTransit,
+            totalDwell,
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/intermodal/format/bolTimestamp.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Which date on a bill of lading a value is rendered for, one per dated field of the DCSA
+ * Bill of Lading 3.0 `TransportDocument`:
+ *
+ * - `issue`: the date the B/L was issued, local to the place of issue (DCSA `issueDate`).
+ * - `received`: the date the last container was in the terminal, customs-cleared against the
+ *   intended vessel, on a received-for-shipment B/L (DCSA `receivedForShipmentDate`).
+ * - `shippedOnBoard`: the date the last container was loaded aboard the vessel, on a
+ *   shipped-on-board B/L (DCSA `shippedOnBoardDate`).
+ *
+ * All three are local calendar dates, so each renders the same way.
+ */
+export type BillOfLadingEvent = "issue" | "received" | "shippedOnBoard";
+/** Options for `bolTimestamp`. */
+export interface BolTimestampOptions {
+    /**
+     * The zone of the place the event happened, as an IANA name or a UTC offset: the place of issue
+     * for `issue`, and the terminal at the port of loading for `received` and `shippedOnBoard`. A UTC
+     * offset is a time zone identifier (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`,
+     * what `getTimeZoneOffset` returns). It is required, because every B/L date is local and a UTC
+     * date is a different date for part of every day.
+     */
+    timeZone: string;
+}
+/**
+ * Render an instant as the date a bill of lading carries for an event: the calendar date on the
+ * local clock where the event happened.
+ *
+ * A B/L date is a contractual date, not a timestamp. The DCSA Bill of Lading 3.0 standard
+ * (`TransportDocument`) types `issueDate` ("Local date when the transport document has been
+ * issued"), `receivedForShipmentDate` and `shippedOnBoardDate` as `format: date`: a date with no
+ * time and no offset. A system that records the loading as an instant has to turn it back into
+ * that local date, and taking the UTC date gets it wrong in both directions: 22:00 in São Paulo is
+ * 01:00Z the next day, and 07:00 in Shanghai is 23:00Z the day before.
+ *
+ * - **The result is a date with no time component**, `YYYY-MM-DD`, as
+ *   `Temporal.PlainDate.prototype.toString` writes it. A year outside 0000–9999 is written with a
+ *   sign and six digits (`"+275760-09-13"`).
+ * - **`timeZone` is required.** Every B/L date is local, so there is no UTC default and no
+ *   system zone: omitting it returns `""`. The zone is the caller's fact; GMT does not resolve a
+ *   port or a place of issue to a zone.
+ * - **`event` names which date this is** and is checked against the three `BillOfLadingEvent`
+ *   values; anything else returns `""`. All three are local calendar dates, so they render the
+ *   same way: the event keeps the call site honest about which field it fills, and the zone is the
+ *   one that differs by event.
+ * - `value` is any instant `isValidInstant` accepts: `Z`, an offset, or an offset with a
+ *   bracketed zone. Only the instant is read; a bracketed zone in `value` is not the zone the date
+ *   is read in, `timeZone` is. 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. A zoneless wall time or a bare date names no moment and returns `""`.
+ * - **No disambiguation arises.** The input is a moment, and a moment has exactly one local date
+ *   in any zone. The date changes at the zone's real midnight. A date the zone deleted is never
+ *   returned (`Pacific/Apia` skipped 2011-12-30), and after a fall-back that re-enters the
+ *   previous date the result is that date again, as the clock showed it (`America/Goose_Bay`,
+ *   7 November 2010).
+ * - Returns `""` when `value` is not an instant, `event` is not one of the three, `options` is not
+ *   an object, or `timeZone` is missing or invalid.
+ *
+ * @param value ISO 8601 instant string of the event (e.g. "2024-06-16T01:00:00Z")
+ * @param event which B/L date the value is rendered for
+ * @param options The zone of the place the event happened
+ * @returns the local calendar date as "YYYY-MM-DD", or "" on invalid input
+ *
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "America/Sao_Paulo" }) // "2024-06-15" (loaded at 22:00 local; the UTC date is the 16th)
+ * @example bolTimestamp("2024-06-14T23:00:00Z", "shippedOnBoard", { timeZone: "Asia/Shanghai" }) // "2024-06-15" (loaded at 07:00 local; the UTC date is the 14th)
+ * @example bolTimestamp("2024-06-15T21:00:00+02:00", "received", { timeZone: "Africa/Johannesburg" }) // "2024-06-15"
+ * @example bolTimestamp("2024-06-16T09:00:00+08:00[Asia/Shanghai]", "issue", { timeZone: "America/Sao_Paulo" }) // "2024-06-15" (the bracketed zone is not the zone the date is read in)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "+08:00" }) // "2024-06-16" (a fixed offset)
+ * @example bolTimestamp("2011-12-30T10:00:00Z", "shippedOnBoard", { timeZone: "Pacific/Apia" }) // "2011-12-31" (Samoa deleted 30 December)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard") // "" (every B/L date is local: the zone is required)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "loaded", { timeZone: "Europe/London" }) // "" (not a B/L event)
+ * @example bolTimestamp("2024-06-15T21:00:00", "shippedOnBoard", { timeZone: "Asia/Kolkata" }) // "" (no offset: not a moment)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "America/Nowhere" }) // ""
+ * @example bolTimestamp("1970-01-01T00:30:00Z", "issue", { timeZone: "-00:44:30" }) // "1969-12-31" (23:45:30 the day before, at a stored offset with seconds)
+ */
+export declare function bolTimestamp(value: string, event: BillOfLadingEvent, options: BolTimestampOptions): string;

package/dist/intermodal/format/bolTimestamp.js

@@ -0,0 +1,78 @@
+import { frameWallClock, instantFrom, isOptionsArgument, zoneFrame, } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+/** The three `BillOfLadingEvent` values. */
+const BILL_OF_LADING_EVENTS = new Set([
+    "issue",
+    "received",
+    "shippedOnBoard",
+]);
+/**
+ * Render an instant as the date a bill of lading carries for an event: the calendar date on the
+ * local clock where the event happened.
+ *
+ * A B/L date is a contractual date, not a timestamp. The DCSA Bill of Lading 3.0 standard
+ * (`TransportDocument`) types `issueDate` ("Local date when the transport document has been
+ * issued"), `receivedForShipmentDate` and `shippedOnBoardDate` as `format: date`: a date with no
+ * time and no offset. A system that records the loading as an instant has to turn it back into
+ * that local date, and taking the UTC date gets it wrong in both directions: 22:00 in São Paulo is
+ * 01:00Z the next day, and 07:00 in Shanghai is 23:00Z the day before.
+ *
+ * - **The result is a date with no time component**, `YYYY-MM-DD`, as
+ *   `Temporal.PlainDate.prototype.toString` writes it. A year outside 0000–9999 is written with a
+ *   sign and six digits (`"+275760-09-13"`).
+ * - **`timeZone` is required.** Every B/L date is local, so there is no UTC default and no
+ *   system zone: omitting it returns `""`. The zone is the caller's fact; GMT does not resolve a
+ *   port or a place of issue to a zone.
+ * - **`event` names which date this is** and is checked against the three `BillOfLadingEvent`
+ *   values; anything else returns `""`. All three are local calendar dates, so they render the
+ *   same way: the event keeps the call site honest about which field it fills, and the zone is the
+ *   one that differs by event.
+ * - `value` is any instant `isValidInstant` accepts: `Z`, an offset, or an offset with a
+ *   bracketed zone. Only the instant is read; a bracketed zone in `value` is not the zone the date
+ *   is read in, `timeZone` is. 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. A zoneless wall time or a bare date names no moment and returns `""`.
+ * - **No disambiguation arises.** The input is a moment, and a moment has exactly one local date
+ *   in any zone. The date changes at the zone's real midnight. A date the zone deleted is never
+ *   returned (`Pacific/Apia` skipped 2011-12-30), and after a fall-back that re-enters the
+ *   previous date the result is that date again, as the clock showed it (`America/Goose_Bay`,
+ *   7 November 2010).
+ * - Returns `""` when `value` is not an instant, `event` is not one of the three, `options` is not
+ *   an object, or `timeZone` is missing or invalid.
+ *
+ * @param value ISO 8601 instant string of the event (e.g. "2024-06-16T01:00:00Z")
+ * @param event which B/L date the value is rendered for
+ * @param options The zone of the place the event happened
+ * @returns the local calendar date as "YYYY-MM-DD", or "" on invalid input
+ *
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "America/Sao_Paulo" }) // "2024-06-15" (loaded at 22:00 local; the UTC date is the 16th)
+ * @example bolTimestamp("2024-06-14T23:00:00Z", "shippedOnBoard", { timeZone: "Asia/Shanghai" }) // "2024-06-15" (loaded at 07:00 local; the UTC date is the 14th)
+ * @example bolTimestamp("2024-06-15T21:00:00+02:00", "received", { timeZone: "Africa/Johannesburg" }) // "2024-06-15"
+ * @example bolTimestamp("2024-06-16T09:00:00+08:00[Asia/Shanghai]", "issue", { timeZone: "America/Sao_Paulo" }) // "2024-06-15" (the bracketed zone is not the zone the date is read in)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "+08:00" }) // "2024-06-16" (a fixed offset)
+ * @example bolTimestamp("2011-12-30T10:00:00Z", "shippedOnBoard", { timeZone: "Pacific/Apia" }) // "2011-12-31" (Samoa deleted 30 December)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard") // "" (every B/L date is local: the zone is required)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "loaded", { timeZone: "Europe/London" }) // "" (not a B/L event)
+ * @example bolTimestamp("2024-06-15T21:00:00", "shippedOnBoard", { timeZone: "Asia/Kolkata" }) // "" (no offset: not a moment)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "America/Nowhere" }) // ""
+ * @example bolTimestamp("1970-01-01T00:30:00Z", "issue", { timeZone: "-00:44:30" }) // "1969-12-31" (23:45:30 the day before, at a stored offset with seconds)
+ */
+export function bolTimestamp(value, event, options) {
+    try {
+        if (options === undefined || !isOptionsArgument(options)) {
+            return "";
+        }
+        const frame = zoneFrame(options.timeZone);
+        if (frame === null ||
+            !BILL_OF_LADING_EVENTS.has(event) ||
+            !isValidInstant(value)) {
+            return "";
+        }
+        return frameWallClock(instantFrom(value), frame).toPlainDate().toString();
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/intermodal/format/formatEdifactDate.d.ts

@@ -0,0 +1,34 @@
+import type { EdifactDateFormat } from "../../types/edi.js";
+/**
+ * Write an ISO 8601 date as a UN/EDIFACT `DTM` value (data element 2380) in a date format code
+ * (data element 2379). The inverse of `parseEdifactDate`: what one writes, the other reads back.
+ *
+ * The mask and description are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format code
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `102` | `CCYYMMDD` | "Calendar date: C = Century ; Y = Year ; M = Month ; D = Day." |
+ *
+ * - `value` is a date, as `isValidDate` accepts it. A date-time, an instant or a time returns
+ *   `""`, as `formatDate` returns `""` for them: pass the date alone.
+ * - Each field is zero-padded to the width the mask gives it.
+ * - A year outside 0000–9999 returns `""`: `CCYY` is four digits and no sign.
+ * - No function writes a two-digit year (`101`, `YYMMDD`): the one date code that is written
+ *   holds the whole year.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value ISO 8601 date (e.g. "2024-06-15")
+ * @param format The data element 2379 format code
+ * @returns the data element 2380 value, or "" on invalid input
+ *
+ * @example formatEdifactDate("2024-06-15", "102") // "20240615"
+ * @example formatEdifactDate("0987-01-05", "102") // "09870105"
+ * @example formatEdifactDate("2024-06-15T14:30:00", "102") // "" (a date-time is not a date)
+ * @example formatEdifactDate("2023-02-29", "102") // "" (not a real date)
+ * @example formatEdifactDate("+010000-01-01", "102") // "" (the mask holds four digits of year)
+ * @example formatEdifactDate("2024-06-15", "203") // "" (a date-time code: use formatEdifactDateTime)
+ */
+export declare function formatEdifactDate(value: string, format: EdifactDateFormat): string;