@northguild/gmt 1.16.0 → 1.18.0

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

@@ -0,0 +1,102 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * The events a container's charging clocks run between, named after the DCSA Track & Trace
+ * equipment events they correspond to (`equipmentEventTypeCode` with `emptyIndicatorCode`):
+ *
+ * - `discharged`: DISC, laden — the full container is discharged from the vessel (import).
+ * - `available`: no DCSA event — the container availability date some import tariffs start the
+ *   clock at.
+ * - `gatedOut`: GTOT, laden — the full container leaves the terminal (import).
+ * - `emptyReturned`: GTIN, empty — the empty is returned to the terminal or depot (import).
+ * - `emptyReleased`: GTOT or PICK, empty — the empty is picked up for stuffing (export).
+ * - `gatedIn`: GTIN, laden — the full container is received at the terminal (export).
+ * - `loaded`: LOAD, laden — the full container is loaded on board (export).
+ */
+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;
+    /** 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. */
+export type ClockScope = "demurrage" | "detention" | "storage" | "combined";
+/** Which leg of the container's cycle the clock is on. */
+export type ClockDirection = "import" | "export";
+/** Where an import demurrage, storage or combined clock starts, when the tariff says so. */
+export type ClockStartEvent = "discharged" | "available";
+/** The options `demurrageClock` reads. */
+export interface ClockOptions {
+    /**
+     * The leg of the container's cycle, `"import"` or `"export"`; required, because the same scope
+     * runs between different events in each.
+     */
+    direction: ClockDirection;
+    /**
+     * 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;
+}
+/**
+ * Pick the two events a charge's clock runs between.
+ *
+ * No regulation or industry standard fixes these events; the carriers' published tariffs agree
+ * on them (import: Maersk's terms, CMA CGM's general terms, Hapag-Lloyd, ACL; export: Maersk, CMA
+ * CGM, ACL), and DCSA's glossary draws the line they rest on: demurrage is charged while the
+ * container is inside the terminal or depot, detention while it is outside, and storage is the
+ * charge for the terminal's space, paid to the terminal or to the carrier on its behalf. Export
+ * storage (`gatedIn` → `loaded`) follows from that storage definition; no tariff read quotes it.
+ * The merged clock runs demurrage and detention as one period, a named tariff product at Maersk
+ * ("Combined"), CMA CGM ("merged") and MSC. `demurrageClock` selects the pair for the charge and
+ * direction asked for, so the wrong pair can never reach `chargeableDays`.
+ *
+ * | scope | import | export |
+ * | --- | --- | --- |
+ * | `demurrage`, `storage` | `startEvent` → `gatedOut` | `gatedIn` → `loaded` |
+ * | `detention` | `gatedOut` → `emptyReturned` | `emptyReleased` → `gatedIn` |
+ * | `combined` | `startEvent` → `emptyReturned` | `emptyReleased` → `loaded` |
+ *
+ * - **`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.** 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
+ *   valid instant, used or not, with no holes in the array: a list with a bad entry is a bad list.
+ * - The result is an `Interval`, half-open `[start, end)`, in the caller's own strings, and feeds
+ *   `chargeableDays(start, end, …)` directly.
+ * - Some tariffs differ in words, not events: MSC USA calls the in-terminal container charge
+ *   "detention" and the out-of-terminal one "per diem". GMT's scope names follow the global usage.
+ * - Returns `null` when `events` is not an array or holds an invalid event or a hole, `scope`,
+ *   `direction` or `startEvent` is unknown, `options` is not an object, a required event is
+ *   missing or occurs more than once (a container discharged twice is a data error, not a choice),
+ *   or the end event precedes the start event.
+ *
+ * @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 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" }
+ * @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" }], "detention", { direction: "import" }) / { start: "2024-06-20T14:30:00Z", end: "2024-06-27T09:00:00Z" } (gate-out to empty return, not discharge)
+ * @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" }], "combined", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-27T09:00:00Z" } (merged: discharge to empty return)
+ * @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" }], "demurrage", { direction: "import", startEvent: "available" }) // { start: "2024-06-15T12:00:00Z", end: "2024-06-20T14:30:00Z" }
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "storage", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }
+ * @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: "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)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "discharged", at: "2024-06-15T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import" }) // null (discharged twice)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-21T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import" }) // null (gate-out before discharge)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "laytime", { direction: "import" }) // null (not a clock this function selects)
+ */
+export declare function demurrageClock(events: ClockEvent[], scope: ClockScope, options: ClockOptions): Interval | null;

package/dist/intermodal/calculate/demurrageClock.js

@@ -0,0 +1,140 @@
+import { Temporal } from "@js-temporal/polyfill";
+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",
+    "gatedOut",
+    "emptyReturned",
+    "emptyReleased",
+    "gatedIn",
+    "loaded",
+];
+const CLOCK_SCOPES = [
+    "demurrage",
+    "detention",
+    "storage",
+    "combined",
+];
+const CLOCK_START_EVENTS = [
+    "discharged",
+    "available",
+];
+/** The export clocks: fixed pairs, no start-event choice. */
+const EXPORT_CLOCKS = {
+    demurrage: ["gatedIn", "loaded"],
+    storage: ["gatedIn", "loaded"],
+    detention: ["emptyReleased", "gatedIn"],
+    combined: ["emptyReleased", "loaded"],
+};
+/**
+ * Pick the two events a charge's clock runs between.
+ *
+ * No regulation or industry standard fixes these events; the carriers' published tariffs agree
+ * on them (import: Maersk's terms, CMA CGM's general terms, Hapag-Lloyd, ACL; export: Maersk, CMA
+ * CGM, ACL), and DCSA's glossary draws the line they rest on: demurrage is charged while the
+ * container is inside the terminal or depot, detention while it is outside, and storage is the
+ * charge for the terminal's space, paid to the terminal or to the carrier on its behalf. Export
+ * storage (`gatedIn` → `loaded`) follows from that storage definition; no tariff read quotes it.
+ * The merged clock runs demurrage and detention as one period, a named tariff product at Maersk
+ * ("Combined"), CMA CGM ("merged") and MSC. `demurrageClock` selects the pair for the charge and
+ * direction asked for, so the wrong pair can never reach `chargeableDays`.
+ *
+ * | scope | import | export |
+ * | --- | --- | --- |
+ * | `demurrage`, `storage` | `startEvent` → `gatedOut` | `gatedIn` → `loaded` |
+ * | `detention` | `gatedOut` → `emptyReturned` | `emptyReleased` → `gatedIn` |
+ * | `combined` | `startEvent` → `emptyReturned` | `emptyReleased` → `loaded` |
+ *
+ * - **`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.** 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
+ *   valid instant, used or not, with no holes in the array: a list with a bad entry is a bad list.
+ * - The result is an `Interval`, half-open `[start, end)`, in the caller's own strings, and feeds
+ *   `chargeableDays(start, end, …)` directly.
+ * - Some tariffs differ in words, not events: MSC USA calls the in-terminal container charge
+ *   "detention" and the out-of-terminal one "per diem". GMT's scope names follow the global usage.
+ * - Returns `null` when `events` is not an array or holds an invalid event or a hole, `scope`,
+ *   `direction` or `startEvent` is unknown, `options` is not an object, a required event is
+ *   missing or occurs more than once (a container discharged twice is a data error, not a choice),
+ *   or the end event precedes the start event.
+ *
+ * @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 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" }
+ * @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" }], "detention", { direction: "import" }) / { start: "2024-06-20T14:30:00Z", end: "2024-06-27T09:00:00Z" } (gate-out to empty return, not discharge)
+ * @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" }], "combined", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-27T09:00:00Z" } (merged: discharge to empty return)
+ * @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" }], "demurrage", { direction: "import", startEvent: "available" }) // { start: "2024-06-15T12:00:00Z", end: "2024-06-20T14:30:00Z" }
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "storage", { direction: "import" }) / { start: "2024-06-14T19:00:00Z", end: "2024-06-20T14:30:00Z" }
+ * @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: "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)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "discharged", at: "2024-06-15T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import" }) // null (discharged twice)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-21T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "demurrage", { direction: "import" }) // null (gate-out before discharge)
+ * @example demurrageClock([{ type: "discharged", at: "2024-06-14T19:00:00Z" }, { type: "gatedOut", at: "2024-06-20T14:30:00Z" }], "laytime", { direction: "import" }) // null (not a clock this function selects)
+ */
+export function demurrageClock(events, scope, options) {
+    try {
+        return selectClock(events, scope, options);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}
+/** `demurrageClock` without the guard; every read of its arguments happens here. */
+function selectClock(events, scope, options) {
+    if (!Array.isArray(events) ||
+        !CLOCK_SCOPES.includes(scope) ||
+        !isObject(options)) {
+        return null;
+    }
+    const { direction } = options;
+    if (direction !== "import" && direction !== "export") {
+        return null;
+    }
+    // An explicit `undefined` is an omission (TC39 GetOption); `null` is a value, and not a valid one.
+    const startEvent = optionOrDefault(options.startEvent, "discharged");
+    if (!CLOCK_START_EVENTS.includes(startEvent)) {
+        return null;
+    }
+    // `Array.from` turns a hole into `undefined`, which the check rejects; `every` would skip it.
+    const list = Array.from(events);
+    const wellFormed = list.every((event) => isObject(event) &&
+        CLOCK_EVENT_TYPES.includes(event.type) &&
+        typeof event.at === "string" &&
+        isValidInstant(event.at));
+    if (!wellFormed) {
+        return null;
+    }
+    const [startType, endType] = direction === "export"
+        ? EXPORT_CLOCKS[scope]
+        : scope === "detention"
+            ? ["gatedOut", "emptyReturned"]
+            : [startEvent, scope === "combined" ? "emptyReturned" : "gatedOut"];
+    const only = (type) => {
+        const matches = list.filter((event) => event.type === type);
+        return matches.length === 1 ? matches[0].at : null;
+    };
+    const start = only(startType);
+    const end = only(endType);
+    if (start === null || end === null) {
+        return null;
+    }
+    return Temporal.Instant.compare(instantFrom(start), instantFrom(end)) > 0
+        ? null
+        : { start, end };
+}

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

@@ -0,0 +1,67 @@
+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 {
+    /** 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;
+    /** The instant free time ends: the start of the local day after `lastFreeDay`, as a UTC instant. */
+    expiresAt: string;
+}
+/**
+ * Lay out a container's free time from the instant its clock started, and say when it ends.
+ *
+ * Free time is the money calculation in container logistics, and none of its terms is a fact
+ * about the port: the number of free days, whether the day of discharge is free day one, and
+ * whether weekends count are all set by the carrier's tariff or the service contract. So every
+ * term is a parameter. No regulation or industry standard fixes how free time is counted (DCSA types only its unit: calendar days, working days, hours or day of discharge; GMT counts
+ * days); the result is the window every tariff states, and what an invoice can print about it:
+ * 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, 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.
+ * - **`firstDay` has no default.** `"eventDay"` makes the event day free day one; `"nextDay"`
+ *   starts free time on the following counted day. The two differ by exactly one day of charges,
+ *   and a silent default here is a wrong invoice, so omitting it returns `null`.
+ * - **`basis` decides which days count.** `"calendar"` counts every local day, so a weekend
+ *   burns two free days while the terminal is shut. `"working"` counts only the working days of
+ *   `options.calendar` (its weekend and holidays; `calendar.timeZone` is not read), and is
+ *   required to have one: a working-day count without a calendar is a guess and returns `null`.
+ *   Under `"working"` a Saturday discharge starts free time on Monday under either `firstDay`.
+ *   A tariff counting "calendar days excluding bank holidays" (Hapag-Lloyd Japan, MSC Vietnam) is
+ *   `"working"` with an empty `weekend`. How days after expiry are charged is a separate term;
+ *   see `chargeableDays`'s `chargeBasis`.
+ * - **`expiresAt` is half-open.** It is the first instant of the local day after `lastFreeDay`,
+ *   as a UTC instant. A gate-out at exactly `expiresAt` is not a chargeable day; see
+ *   `chargeableDays`. Under `"working"` it can fall on a weekend, which is then simply not
+ *   chargeable.
+ * - `freeDays` is a whole number of at least `1`: with no free days there is no last free day
+ *   to name, and `chargeableDays` accepts `0` for that tariff.
+ * - Returns `null` when `clockStart` is not an instant, `freeDays` is not a whole number of at
+ *   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.
+ *
+ * @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-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)
+ */
+export declare function freeTimeExpiry(clockStart: string, freeDays: number, options: FreeTimeOptions): FreeTime | null;

package/dist/intermodal/calculate/freeTimeExpiry.js

@@ -0,0 +1,82 @@
+import { instantFrom, parseFreeDays, parseFreeTimeTerms, walkFreeTime, } 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.
+ *
+ * Free time is the money calculation in container logistics, and none of its terms is a fact
+ * about the port: the number of free days, whether the day of discharge is free day one, and
+ * whether weekends count are all set by the carrier's tariff or the service contract. So every
+ * term is a parameter. No regulation or industry standard fixes how free time is counted (DCSA types only its unit: calendar days, working days, hours or day of discharge; GMT counts
+ * days); the result is the window every tariff states, and what an invoice can print about it:
+ * 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, 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.
+ * - **`firstDay` has no default.** `"eventDay"` makes the event day free day one; `"nextDay"`
+ *   starts free time on the following counted day. The two differ by exactly one day of charges,
+ *   and a silent default here is a wrong invoice, so omitting it returns `null`.
+ * - **`basis` decides which days count.** `"calendar"` counts every local day, so a weekend
+ *   burns two free days while the terminal is shut. `"working"` counts only the working days of
+ *   `options.calendar` (its weekend and holidays; `calendar.timeZone` is not read), and is
+ *   required to have one: a working-day count without a calendar is a guess and returns `null`.
+ *   Under `"working"` a Saturday discharge starts free time on Monday under either `firstDay`.
+ *   A tariff counting "calendar days excluding bank holidays" (Hapag-Lloyd Japan, MSC Vietnam) is
+ *   `"working"` with an empty `weekend`. How days after expiry are charged is a separate term;
+ *   see `chargeableDays`'s `chargeBasis`.
+ * - **`expiresAt` is half-open.** It is the first instant of the local day after `lastFreeDay`,
+ *   as a UTC instant. A gate-out at exactly `expiresAt` is not a chargeable day; see
+ *   `chargeableDays`. Under `"working"` it can fall on a weekend, which is then simply not
+ *   chargeable.
+ * - `freeDays` is a whole number of at least `1`: with no free days there is no last free day
+ *   to name, and `chargeableDays` accepts `0` for that tariff.
+ * - Returns `null` when `clockStart` is not an instant, `freeDays` is not a whole number of at
+ *   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.
+ *
+ * @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-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)
+ */
+export function freeTimeExpiry(clockStart, freeDays, options) {
+    try {
+        const terms = parseFreeTimeTerms(options);
+        const allowed = parseFreeDays(freeDays, 1);
+        if (!isValidInstant(clockStart) || terms === null || allowed === null) {
+            return null;
+        }
+        const start = instantFrom(clockStart).toZonedDateTimeISO(terms.timeZone);
+        const ledger = walkFreeTime(start, allowed, terms);
+        if (ledger === null) {
+            return null;
+        }
+        return {
+            freeTimeStart: ledger.free[0].date,
+            lastFreeDay: ledger.free[allowed - 1].date,
+            expiresAt: ledger.expiresAt.toInstant().toString(),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,4 @@
+export * from "./billingTimeline.js";
+export * from "./chargeableDays.js";
+export * from "./demurrageClock.js";
+export * from "./freeTimeExpiry.js";

package/dist/intermodal/calculate/index.js

@@ -0,0 +1,4 @@
+export * from "./billingTimeline.js";
+export * from "./chargeableDays.js";
+export * from "./demurrageClock.js";
+export * from "./freeTimeExpiry.js";

package/dist/intermodal/index.d.ts

@@ -0,0 +1,2 @@
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";

package/dist/intermodal/index.js

@@ -0,0 +1,3 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";

package/dist/internal/businessCalendar.d.ts

@@ -11,6 +11,11 @@ export type ResolvedBusinessCalendar = {
     holidays: Set<string>;
 };
 export declare const DEFAULT_BUSINESS_CALENDAR: ResolvedBusinessCalendar;
+/**
+ * Reduce a holiday list to its normalised ISO dates, or `null` when it is not an array of ISO
+ * PlainDate strings. Shared with `OperatingSchedule.holidays`, which takes the same list.
+ */
+export declare function parseHolidays(holidays: unknown): Set<string> | null;
 /**
  * Reduce a caller-supplied `BusinessCalendar` to its lookups, or `null` when it is not one.
  *

package/dist/internal/businessCalendar.js

@@ -29,7 +29,11 @@ function parseWeekend(weekend) {
     // All seven weekdays closed leaves no business day, so every walk would run to its cap.
     return days.size < ISO_WEEKDAYS ? days : null;
 }
-function parseHolidays(holidays) {
+/**
+ * Reduce a holiday list to its normalised ISO dates, or `null` when it is not an array of ISO
+ * PlainDate strings. Shared with `OperatingSchedule.holidays`, which takes the same list.
+ */
+export function parseHolidays(holidays) {
     if (!Array.isArray(holidays)) {
         return null;
     }

package/dist/internal/cycleFieldValue.d.ts

@@ -8,10 +8,12 @@
  *   not by repeatedly correcting a single overflow.
  * - Round path is **not** "round to nearest": it steps by `Math.sign(amount)` first, then snaps to
  *   the next multiple of `Math.abs(amount)` in the direction of that sign (ceiling for positive
- *   amounts, floor for negative). Multiples are relative to `0`, not `bounds.min`. This matches
- *   `@internationalized/date`'s `CycleOptions.round` behavior exactly (verified against its
- *   `manipulation.ts` source) — e.g. minute `22` cycled by `+15` with `round: true` lands on `30`
- *   (the next multiple of 15 above 22), not `15` (the nearest multiple).
+ *   amounts, floor for negative). Multiples are relative to `0`, not `bounds.min`. GMT's own
+ *   rule, not a standard's: a cycle always moves the way `amount` points, and the nearest
+ *   multiple can lie the other way — e.g. minute `22` cycled by `+15` with `round: true` lands on
+ *   `30` (the next multiple of 15 above 22), not `15` (the nearest multiple).
+ * - Comparison: `@internationalized/date`'s `CycleOptions.round` rounds a bounded field the same
+ *   way.
  *
  * @param current the field's current numeric value
  * @param amount signed amount to cycle by

package/dist/internal/cycleFieldValue.js

@@ -8,10 +8,12 @@
  *   not by repeatedly correcting a single overflow.
  * - Round path is **not** "round to nearest": it steps by `Math.sign(amount)` first, then snaps to
  *   the next multiple of `Math.abs(amount)` in the direction of that sign (ceiling for positive
- *   amounts, floor for negative). Multiples are relative to `0`, not `bounds.min`. This matches
- *   `@internationalized/date`'s `CycleOptions.round` behavior exactly (verified against its
- *   `manipulation.ts` source) — e.g. minute `22` cycled by `+15` with `round: true` lands on `30`
- *   (the next multiple of 15 above 22), not `15` (the nearest multiple).
+ *   amounts, floor for negative). Multiples are relative to `0`, not `bounds.min`. GMT's own
+ *   rule, not a standard's: a cycle always moves the way `amount` points, and the nearest
+ *   multiple can lie the other way — e.g. minute `22` cycled by `+15` with `round: true` lands on
+ *   `30` (the next multiple of 15 above 22), not `15` (the nearest multiple).
+ * - Comparison: `@internationalized/date`'s `CycleOptions.round` rounds a bounded field the same
+ *   way.
  *
  * @param current the field's current numeric value
  * @param amount signed amount to cycle by

package/dist/internal/daylightTime.d.ts

@@ -0,0 +1,33 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Whether an instant is in daylight saving time, read from the zone's offset changes alone.
+ *
+ * The rule: daylight time runs from a forward change of the clocks to the backward change that
+ * undoes it. A backward change undoes the most recent forward change of the same size that is not
+ * yet undone, and only if it comes less than 365 days after it. An instant is in daylight time when
+ * it is at or after such a forward change and before the backward change paired with it.
+ *
+ * A forward change that is never undone, or undone a year or more later, is a change of standard
+ * time (`Europe/Istanbul` 2016, `Europe/Moscow` 2011 to 2014), as is any backward change with no
+ * forward change to undo (`Asia/Almaty` 2024).
+ *
+ * This is GMT's own definition, not the tz database's daylight flag, which no JavaScript API
+ * exposes and offsets do not determine.
+ *
+ * Cost: one transition lookup forward, then one back, and more only outside the ordinary summer
+ * case. A paired change is less than 365 days away, so every lookup is given that limit and reads
+ * no further: with GMT's own search (temporalCompat D13) at most 74 offset samples and 51 reads to
+ * pin a change, for any zone and any instant.
+ *
+ * @param zoned the instant, in the zone to read
+ * @returns true in daylight time, false in standard time or when the walk exceeds its bound
+ */
+export declare function isInDaylightTime(zoned: Temporal.ZonedDateTime): boolean;
+/**
+ * Whether a zone observes daylight saving time as of an instant: the instant is in daylight time,
+ * or a daylight period begins within the 365 days after it. Same rule as `isInDaylightTime`.
+ *
+ * @param zoned the instant to judge from, in the zone to read
+ * @returns true when the zone observes daylight time then, false otherwise or past the walk bound
+ */
+export declare function observesDaylightTime(zoned: Temporal.ZonedDateTime): boolean;