@northguild/gmt 1.17.0 → 1.19.0

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

@@ -5,33 +5,53 @@ export interface BillingDates {
      * last incurred or, for a re-bill, the issuance date of the invoice received.
      */
     anchorOn: string;
-    /** The date the invoice was issued, once it has been. */
+    /**
+     * The date the invoice was issued, once it has been, as an ISO date.
+     *
+     * @defaultValue None. `issuedByDeadline` and `disputeDeadline` are `null`.
+     */
     invoiceIssuedOn?: string;
-    /** The date the dispute request was received, once it has been. */
+    /**
+     * The date the dispute request was received, once it has been, as an ISO date. It needs
+     * `invoiceIssuedOn` and may not precede it.
+     *
+     * @defaultValue None. `requestedByDeadline` and `resolutionDeadline` are `null`.
+     */
     requestReceivedOn?: string;
 }
 /** The three windows the caller supplies, in calendar days, none defaulted, and an optional agreed resolution date. */
 export interface BillingWindows {
-    /** Days from `anchorOn` within which the invoice must be issued. */
+    /** The days from `anchorOn` within which the invoice must be issued. */
     issueDays: number;
-    /** Days from `invoiceIssuedOn` within which a dispute may be raised. */
+    /** The days from `invoiceIssuedOn` within which a dispute may be raised. */
     disputeDays: number;
-    /** Days from `requestReceivedOn` within which the dispute must be resolved. */
+    /** The days from `requestReceivedOn` within which the dispute must be resolved. */
     resolutionDays: number;
-    /** A resolution date the parties agreed instead; it replaces the computed one. */
+    /**
+     * A resolution date the parties agreed instead, as an ISO date on or after `requestReceivedOn`;
+     * it replaces the computed one.
+     *
+     * @defaultValue None. `resolutionDeadline` is `requestReceivedOn + resolutionDays`.
+     */
     agreedResolutionOn?: string;
 }
 /** What `billingTimeline` returns: each deadline as an ISO date, and each comparison once its date exists. */
 export interface BillingDeadlines {
-    /** `anchorOn + issueDays`. */
+    /** The last date the invoice may be issued: `anchorOn + issueDays`. */
     invoiceDeadline: string;
     /** Whether `invoiceIssuedOn` is on or before `invoiceDeadline`; `null` until an invoice date exists. */
     issuedByDeadline: boolean | null;
-    /** `invoiceIssuedOn + disputeDays`; `null` until an invoice date exists. */
+    /**
+     * The last date a dispute may be raised: `invoiceIssuedOn + disputeDays`; `null` until an invoice
+     * date exists.
+     */
     disputeDeadline: string | null;
     /** Whether `requestReceivedOn` is on or before `disputeDeadline`; `null` until a request date exists. */
     requestedByDeadline: boolean | null;
-    /** `requestReceivedOn + resolutionDays`, or `agreedResolutionOn`; `null` until a request date exists. */
+    /**
+     * The last date the dispute must be resolved: `requestReceivedOn + resolutionDays`, or
+     * `agreedResolutionOn`; `null` until a request date exists.
+     */
     resolutionDeadline: string | null;
 }
 /**
@@ -76,8 +96,8 @@ export interface BillingDeadlines {
  *   request exists without an invoice or before it, `agreedResolutionOn` is before the request,
  *   or a deadline would leave Temporal's range.
  *
- * @param dates { anchorOn: string, invoiceIssuedOn?: string, requestReceivedOn?: string } ISO dates
- * @param windows { issueDays: number, disputeDays: number, resolutionDays: number, agreedResolutionOn?: string } calendar-day windows, none defaulted
+ * @param dates The anchor date, and the invoice and request dates once they exist
+ * @param windows The three calendar-day windows, none defaulted, and an agreed resolution date
  * @returns { invoiceDeadline, issuedByDeadline, disputeDeadline, requestedByDeadline, resolutionDeadline }, or null on invalid input
  *
  * @example billingTimeline({ anchorOn: "2026-03-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (no invoice yet: a forecast)

package/dist/intermodal/calculate/billingTimeline.js

@@ -43,8 +43,8 @@ import { isValidDate } from "../../plain/validate/isValidDate.js";
  *   request exists without an invoice or before it, `agreedResolutionOn` is before the request,
  *   or a deadline would leave Temporal's range.
  *
- * @param dates { anchorOn: string, invoiceIssuedOn?: string, requestReceivedOn?: string } ISO dates
- * @param windows { issueDays: number, disputeDays: number, resolutionDays: number, agreedResolutionOn?: string } calendar-day windows, none defaulted
+ * @param dates The anchor date, and the invoice and request dates once they exist
+ * @param windows The three calendar-day windows, none defaulted, and an agreed resolution date
  * @returns { invoiceDeadline, issuedByDeadline, disputeDeadline, requestedByDeadline, resolutionDeadline }, or null on invalid input
  *
  * @example billingTimeline({ anchorOn: "2026-03-01" }, { issueDays: 30, disputeDays: 30, resolutionDays: 30 }) // { invoiceDeadline: "2026-03-31", issuedByDeadline: null, disputeDeadline: null, requestedByDeadline: null, resolutionDeadline: null } (no invoice yet: a forecast)

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

@@ -1,18 +1,18 @@
 import type { FreeTimeBasis, FreeTimeOptions } from "../../types/index.js";
 /** A band of chargeable-day ordinals and how many of the charged days fell in it. */
 export interface TierBand {
-    /** First chargeable-day ordinal of the band, from 1. */
+    /** The first chargeable-day ordinal of the band, from 1. */
     from: number;
-    /** Last ordinal of the band, or `null` for the open final band. */
+    /** The last ordinal of the band, or `null` for the open final band. */
     to: number | null;
-    /** Charged days that fell in the band. */
+    /** The number of charged days that fell in the band. */
     days: number;
 }
 /** What `chargeableDays` returns: the day count an invoice bills, and the dates that back it. */
 export interface FreeTimeCharges {
-    /** Free days the dwell touched, at most the tariff's `freeDays`. */
+    /** The number of free days the dwell touched, at most the tariff's `freeDays`. */
     freeDaysUsed: number;
-    /** Counted days on or after `expiresAt` the dwell touched. */
+    /** The number of counted days on or after `expiresAt` the dwell touched. */
     chargeableDays: number;
     /** The instant free time ended, as a UTC instant, as `freeTimeExpiry` reports it. */
     expiresAt: string;
@@ -31,6 +31,13 @@ export type FreeTimeChargeOptions = FreeTimeOptions & {
      * working days of `calendar`. No default; see `chargeableDays`.
      */
     chargeBasis: FreeTimeBasis;
+    /**
+     * The last chargeable-day ordinal of each band, as strictly ascending positive whole numbers:
+     * `[5, 10]` is days 1–5, 6–10 and 11 onward. They are day bands, not rates. Every band is
+     * returned, an empty one with `days: 0`, and the last is always open.
+     *
+     * @defaultValue None. `byTier` is the single open band `{ from: 1, to: null }`.
+     */
     tiers?: number[];
 };
 /**
@@ -66,20 +73,21 @@ export type FreeTimeChargeOptions = FreeTimeOptions & {
  * - **`freeDays` may be `0`** for a tariff with no free time: `expiresAt` is the start of day one,
  *   the first day counted on `basis` (under `"nextDay"`, the first after the event day), and days
  *   before it are neither free nor charged.
- * - **`tiers` are day bands, not rates.** `[5, 10]` names the last chargeable-day ordinal of
- *   each band: days 1–5, 6–10 and 11 onward. Every band is returned, an empty one with
- *   `days: 0`, and the last is always open. Omitted, `byTier` is the single open band
- *   `{ from: 1, to: null }`. A list that is not strictly ascending positive whole numbers
- *   returns `null`.
  * - Returns `null` when either instant is invalid, `clockEnd` is before `clockStart` (an
  *   inverted dwell is a data error), `freeDays` is not a whole number of at least `0`, the
  *   options fail as they do for `freeTimeExpiry`, `tiers` has a hole, an unsafe integer or does not ascend, 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
  * @param clockEnd ISO 8601 instant string of the event that stops it (gate-out or empty return)
  * @param freeDays whole number of free days the tariff allows, 0 or more
- * @param options { basis, chargeBasis, timeZone, firstDay, calendar?, tiers?: number[] }
+ * @param options The tariff's counting terms for free time and for charged days, and the tier bands
  * @returns the free days used, the chargeable days, the expiry, the charged dates and the days per tier band, or null on invalid input
  *
  * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)

package/dist/intermodal/calculate/chargeableDays.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "../../internal/index.js";
+import { bandsByTier, frameInstant, frameZoned, instantFrom, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, zoneFrame, } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
 /**
  * Count the days a container is charged for between the start of its clock and its exit,
@@ -34,20 +34,21 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  * - **`freeDays` may be `0`** for a tariff with no free time: `expiresAt` is the start of day one,
  *   the first day counted on `basis` (under `"nextDay"`, the first after the event day), and days
  *   before it are neither free nor charged.
- * - **`tiers` are day bands, not rates.** `[5, 10]` names the last chargeable-day ordinal of
- *   each band: days 1–5, 6–10 and 11 onward. Every band is returned, an empty one with
- *   `days: 0`, and the last is always open. Omitted, `byTier` is the single open band
- *   `{ from: 1, to: null }`. A list that is not strictly ascending positive whole numbers
- *   returns `null`.
  * - Returns `null` when either instant is invalid, `clockEnd` is before `clockStart` (an
  *   inverted dwell is a data error), `freeDays` is not a whole number of at least `0`, the
  *   options fail as they do for `freeTimeExpiry`, `tiers` has a hole, an unsafe integer or does not ascend, 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
  * @param clockEnd ISO 8601 instant string of the event that stops it (gate-out or empty return)
  * @param freeDays whole number of free days the tariff allows, 0 or more
- * @param options { basis, chargeBasis, timeZone, firstDay, calendar?, tiers?: number[] }
+ * @param options The tariff's counting terms for free time and for charged days, and the tier bands
  * @returns the free days used, the chargeable days, the expiry, the charged dates and the days per tier band, or null on invalid input
  *
  * @example chargeableDays("2024-06-14T19:00:00Z", "2024-06-17T04:00:00Z", 3, { basis: "calendar", chargeBasis: "calendar", timeZone: "America/New_York", firstDay: "eventDay" }) // { freeDaysUsed: 3, chargeableDays: 0, expiresAt: "2024-06-17T04:00:00Z", chargedDates: [], byTier: [{ from: 1, to: null, days: 0 }] } (gate-out exactly at expiry is free)
@@ -69,15 +70,17 @@ export function chargeableDays(clockStart, clockEnd, freeDays, options) {
         const allowed = parseFreeDays(freeDays, 0);
         // Read after the terms, so a non-object `options` is never read from.
         const tiers = terms === null ? null : parseTiers(options.tiers);
+        const frame = terms === null ? null : zoneFrame(terms.timeZone);
         if (!isValidInstant(clockStart) ||
             !isValidInstant(clockEnd) ||
             terms === null ||
+            frame === null ||
             allowed === null ||
             tiers === null) {
             return null;
         }
-        const start = Temporal.Instant.from(clockStart).toZonedDateTimeISO(terms.timeZone);
-        const end = Temporal.Instant.from(clockEnd).toZonedDateTimeISO(terms.timeZone);
+        const start = frameZoned(instantFrom(clockStart), frame);
+        const end = frameZoned(instantFrom(clockEnd), frame);
         if (Temporal.ZonedDateTime.compare(start, end) > 0) {
             return null;
         }
@@ -88,7 +91,7 @@ export function chargeableDays(clockStart, clockEnd, freeDays, options) {
         return {
             freeDaysUsed: ledger.used,
             chargeableDays: ledger.charged.length,
-            expiresAt: ledger.expiresAt.toInstant().toString(),
+            expiresAt: frameInstant(ledger.expiresAt, frame).toString(),
             chargedDates: ledger.charged.map((day) => day.date),
             byTier: bandsByTier(tiers, ledger.charged.length),
         };

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

@@ -15,8 +15,9 @@ import type { Interval } from "../../types/index.js";
 export type ClockEventType = "discharged" | "available" | "gatedOut" | "emptyReturned" | "emptyReleased" | "gatedIn" | "loaded";
 /** A container event: what happened and the instant it happened. */
 export interface ClockEvent {
+    /** What happened to the container, as one of the events a charging clock can start or end at. */
     type: ClockEventType;
-    /** ISO 8601 instant string: `Z`, an offset, or a bracketed zone. */
+    /** The instant it happened, as an ISO 8601 string: `Z`, an offset, or a bracketed zone. */
     at: string;
 }
 /** Which charge is being clocked. `combined` is the merged demurrage-and-detention clock. */
@@ -27,9 +28,18 @@ export type ClockDirection = "import" | "export";
 export type ClockStartEvent = "discharged" | "available";
 /** The options `demurrageClock` reads. */
 export interface ClockOptions {
-    /** `"import"` or `"export"`; required, because the same scope runs between different events in each. */
+    /**
+     * The leg of the container's cycle, `"import"` or `"export"`; required, because the same scope
+     * runs between different events in each.
+     */
     direction: ClockDirection;
-    /** Import only: `"discharged"` (the default) or `"available"`. Not read for export or detention. */
+    /**
+     * Where an import demurrage, storage or combined clock starts: `"discharged"`, the classic
+     * definition, or `"available"` for tariffs that start at the availability date. Not read for
+     * export or detention.
+     *
+     * @defaultValue `"discharged"`
+     */
     startEvent?: ClockStartEvent;
 }
 /**
@@ -53,9 +63,8 @@ export interface ClockOptions {
  *
  * - **`direction` has no default.** The same scope name selects different events on the import and
  *   export legs, and guessing it from the events present would be a silent guess.
- * - **`startEvent` is import only**: `"discharged"` by default, the classic definition, or
- *   `"available"` for tariffs that start at the availability date. It is not read for detention
- *   or export, so one options object can serve every scope on a leg. A tariff that starts at
+ * - **`startEvent` is import only.** It is not read for detention or export, so one options
+ *   object can serve every scope on a leg. A tariff that starts at
  *   customs release (Hapag-Lloyd Japan) or ends export demurrage at the cut-off or the scheduled
  *   sailing passes that instant as the event's `at`; GMT does not invent an event for one tariff.
  * - Events may be in any order, and every one must be `{ type, at }` with a known type and a
@@ -71,7 +80,7 @@ export interface ClockOptions {
  *
  * @param events the container's events, `{ type, at }`, `type` one of discharged, available, gatedOut, emptyReturned, emptyReleased, gatedIn, loaded
  * @param scope "demurrage" | "detention" | "storage" | "combined"
- * @param options { direction: "import" | "export", startEvent?: "discharged" | "available" }
+ * @param options Which leg of the cycle the clock is on, and where an import clock starts
  * @returns { start, end } of the requested clock, or null on invalid input
  *
  * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "available", at: "2024-06-15T12:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }, { type: "emptyReturned", at: "2024-06-27T09:00:00Z" }], "demurrage", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }

package/dist/intermodal/calculate/demurrageClock.js

@@ -1,6 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isObject } from "../../internal/index.js";
+import { instantFrom, isObject } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 const CLOCK_EVENT_TYPES = [
     "discharged",
     "available",
@@ -48,9 +49,8 @@ const EXPORT_CLOCKS = {
  *
  * - **`direction` has no default.** The same scope name selects different events on the import and
  *   export legs, and guessing it from the events present would be a silent guess.
- * - **`startEvent` is import only**: `"discharged"` by default, the classic definition, or
- *   `"available"` for tariffs that start at the availability date. It is not read for detention
- *   or export, so one options object can serve every scope on a leg. A tariff that starts at
+ * - **`startEvent` is import only.** It is not read for detention or export, so one options
+ *   object can serve every scope on a leg. A tariff that starts at
  *   customs release (Hapag-Lloyd Japan) or ends export demurrage at the cut-off or the scheduled
  *   sailing passes that instant as the event's `at`; GMT does not invent an event for one tariff.
  * - Events may be in any order, and every one must be `{ type, at }` with a known type and a
@@ -66,7 +66,7 @@ const EXPORT_CLOCKS = {
  *
  * @param events the container's events, `{ type, at }`, `type` one of discharged, available, gatedOut, emptyReturned, emptyReleased, gatedIn, loaded
  * @param scope "demurrage" | "detention" | "storage" | "combined"
- * @param options { direction: "import" | "export", startEvent?: "discharged" | "available" }
+ * @param options Which leg of the cycle the clock is on, and where an import clock starts
  * @returns { start, end } of the requested clock, or null on invalid input
  *
  * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "available", at: "2024-06-15T12:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }, { type: "emptyReturned", at: "2024-06-27T09:00:00Z" }], "demurrage", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }
@@ -107,7 +107,7 @@ function selectClock(events, scope, options) {
         return null;
     }
     // An explicit `undefined` is an omission (TC39 GetOption); `null` is a value, and not a valid one.
-    const startEvent = options.startEvent === undefined ? "discharged" : options.startEvent;
+    const startEvent = optionOrDefault(options.startEvent, "discharged");
     if (!CLOCK_START_EVENTS.includes(startEvent)) {
         return null;
     }
@@ -134,7 +134,7 @@ function selectClock(events, scope, options) {
     if (start === null || end === null) {
         return null;
     }
-    return Temporal.Instant.compare(Temporal.Instant.from(start), Temporal.Instant.from(end)) > 0
+    return Temporal.Instant.compare(instantFrom(start), instantFrom(end)) > 0
         ? null
         : { start, end };
 }

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

@@ -1,7 +1,7 @@
 import type { FreeTimeOptions } from "../../types/index.js";
 /** What `freeTimeExpiry` returns: the free-time window as local dates, and the instant it ends. */
 export interface FreeTime {
-    /** Free day one, as a local date in the counting zone. */
+    /** The first free day, as a local date in the counting zone. */
     freeTimeStart: string;
     /** The last free day, as a local date in the counting zone. */
     lastFreeDay: string;
@@ -19,8 +19,9 @@ export interface FreeTime {
  * the free time allowed and the dates it starts and ends.
  *
  * - **Days are the terminal's local days.** `clockStart` is an instant (`Z`, an offset, or a
- *   bracketed zone, of which only the instant is read); its local date in `options.timeZone` is
- *   the event day. A container discharged at 23:00 has used a free day by 00:01 under
+ *   bracketed zone, of which only the instant is read, a minute-rounded offset as the zone's
+ *   real one, as `isValidInstant` describes); its local date in `options.timeZone` is the
+ *   event day. A container discharged at 23:00 has used a free day by 00:01 under
  *   `firstDay: "eventDay"`. Day boundaries are the zone's real ones, as `floorToZone` and
  *   `dwellTime` find them: a 23- or 25-hour day is one day, a date the zone deleted is never a
  *   free day, and a fall-back that re-enters an earlier date never moves the count backwards.
@@ -45,10 +46,16 @@ 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 { basis: "calendar" | "working", timeZone: string, firstDay: "eventDay" | "nextDay", calendar?: BusinessCalendar }
+ * @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)
@@ -62,5 +69,6 @@ export interface FreeTime {
  * @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("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,5 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { parseFreeDays, parseFreeTimeTerms, walkFreeTime, } from "../../internal/index.js";
+import { frameInstant, 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.
@@ -12,8 +11,9 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  * the free time allowed and the dates it starts and ends.
  *
  * - **Days are the terminal's local days.** `clockStart` is an instant (`Z`, an offset, or a
- *   bracketed zone, of which only the instant is read); its local date in `options.timeZone` is
- *   the event day. A container discharged at 23:00 has used a free day by 00:01 under
+ *   bracketed zone, of which only the instant is read, a minute-rounded offset as the zone's
+ *   real one, as `isValidInstant` describes); its local date in `options.timeZone` is the
+ *   event day. A container discharged at 23:00 has used a free day by 00:01 under
  *   `firstDay: "eventDay"`. Day boundaries are the zone's real ones, as `floorToZone` and
  *   `dwellTime` find them: a 23- or 25-hour day is one day, a date the zone deleted is never a
  *   free day, and a fall-back that re-enters an earlier date never moves the count backwards.
@@ -38,10 +38,16 @@ 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 { basis: "calendar" | "working", timeZone: string, firstDay: "eventDay" | "nextDay", calendar?: BusinessCalendar }
+ * @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)
@@ -55,15 +61,20 @@ import { isValidInstant } from "../../precision/validate/isValidInstant.js";
  * @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("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 = Temporal.Instant.from(clockStart).toZonedDateTimeISO(terms.timeZone);
+        const start = frameZoned(instantFrom(clockStart), frame);
         const ledger = walkFreeTime(start, allowed, terms);
         if (ledger === null) {
             return null;
@@ -71,7 +82,7 @@ export function freeTimeExpiry(clockStart, freeDays, options) {
         return {
             freeTimeStart: ledger.free[0].date,
             lastFreeDay: ledger.free[allowed - 1].date,
-            expiresAt: ledger.expiresAt.toInstant().toString(),
+            expiresAt: frameInstant(ledger.expiresAt, frame).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/New_York" }) // { eta: "2024-06-15T15:00:00+00:00[UTC]", totalLegs: 1, totalTransit: "PT1H", totalDwell: "PT0S" } (a published 10:00 wall time, read in New York)
+ * @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;