@northguild/gmt 1.16.0 → 1.17.0

package/dist/internal/wallClockAtOffset.d.ts

@@ -0,0 +1,22 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * The wall clock an instant reads at a fixed UTC offset, including a sub-minute or fractional
+ * one. Callers write the offset text themselves.
+ *
+ * The shift happens on the wall clock, never on the instant: a `PlainDateTime` reaches a day
+ * further either side than an `Instant` does (TC39 `ISODateTimeWithinLimits` against
+ * `IsValidEpochNanoseconds`), so shifting the instant first would reject the last 14 hours of
+ * the representable range, where `+275760-09-13T00:00:00Z` at `+14:00` names a local time that
+ * exists. No offset time zone is built either: Temporal's offset time-zone identifiers are
+ * minute precision, and an offset such as `-00:44:30` or `+05:30:15.25` is not.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param offsetNanoseconds UTC offset in nanoseconds, east positive
+ * @returns the local wall clock at that offset
+ *
+ * @example wallClockAtOffset(Temporal.Instant.from("1970-01-01T00:00:00Z"), -2_670_000_000_000n).toString() // "1969-12-31T23:15:30"
+ * @example wallClockAtOffset(Temporal.Instant.from("+275760-09-13T00:00:00Z"), 50_400_000_000_000n).toString() // "+275760-09-13T14:00:00"
+ */
+export declare function wallClockAtOffset(instant: Temporal.Instant, offsetNanoseconds: bigint): Temporal.PlainDateTime;

package/dist/internal/wallClockAtOffset.js

@@ -0,0 +1,26 @@
+/**
+ * The wall clock an instant reads at a fixed UTC offset, including a sub-minute or fractional
+ * one. Callers write the offset text themselves.
+ *
+ * The shift happens on the wall clock, never on the instant: a `PlainDateTime` reaches a day
+ * further either side than an `Instant` does (TC39 `ISODateTimeWithinLimits` against
+ * `IsValidEpochNanoseconds`), so shifting the instant first would reject the last 14 hours of
+ * the representable range, where `+275760-09-13T00:00:00Z` at `+14:00` names a local time that
+ * exists. No offset time zone is built either: Temporal's offset time-zone identifiers are
+ * minute precision, and an offset such as `-00:44:30` or `+05:30:15.25` is not.
+ *
+ * Throws what Temporal throws; callers wrap it in their own try/catch.
+ *
+ * @param instant the exact time
+ * @param offsetNanoseconds UTC offset in nanoseconds, east positive
+ * @returns the local wall clock at that offset
+ *
+ * @example wallClockAtOffset(Temporal.Instant.from("1970-01-01T00:00:00Z"), -2_670_000_000_000n).toString() // "1969-12-31T23:15:30"
+ * @example wallClockAtOffset(Temporal.Instant.from("+275760-09-13T00:00:00Z"), 50_400_000_000_000n).toString() // "+275760-09-13T14:00:00"
+ */
+export function wallClockAtOffset(instant, offsetNanoseconds) {
+    return instant
+        .toZonedDateTimeISO("UTC")
+        .toPlainDateTime()
+        .add({ nanoseconds: Number(offsetNanoseconds) });
+}

package/dist/internal/zonedWallClockDifference.js

@@ -1,4 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { TIME_ZONE_ANNOTATION } from "./isoStringBody.js";
 import { MAX_EPOCH_NANOSECONDS, MIN_EPOCH_NANOSECONDS, } from "./epochNanoseconds.js";
 import { calendarDateAdd as compatCalendarDateAdd, calendarDateUntil as compatCalendarDateUntil, isCalendarArithmeticCompatNeeded, isNudgeWindowCompatNeeded, } from "./temporalCompat/index.js";
 import { epochNanosecondsFor, isNamedTimeZone, isValidEpoch, utcEpochNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
@@ -43,7 +44,7 @@ const UTC_EQUIVALENT_OFFSET_ZONE = "+00:00";
 const OPTIONS_PROBE = new Temporal.ZonedDateTime(0n, "UTC");
 const ZERO_DURATION = new Temporal.Duration();
 /** An RFC 9557 time zone annotation (`[Europe/London]`, `[!+01:00]`), never a `key=value` one. */
-const TIME_ZONE_ANNOTATION = /\[!?[^\]=]+\]/;
+const timeZoneAnnotation = new RegExp(TIME_ZONE_ANNOTATION);
 const ZERO_DATE_DURATION = {
     years: 0,
     months: 0,
@@ -766,7 +767,7 @@ function zonedRelativeTo(relativeTo) {
         return relativeTo;
     try {
         if (typeof relativeTo === "string") {
-            return TIME_ZONE_ANNOTATION.test(relativeTo)
+            return timeZoneAnnotation.test(relativeTo)
                 ? zonedDateTimeFrom(relativeTo)
                 : null;
         }
@@ -868,7 +869,7 @@ function plainRelativeToNeedingCompat(relativeTo) {
         }
         else if (typeof relativeTo === "string" &&
             relativeTo.includes("u-ca=") &&
-            !TIME_ZONE_ANNOTATION.test(relativeTo)) {
+            !timeZoneAnnotation.test(relativeTo)) {
             plain = Temporal.PlainDate.from(relativeTo);
         }
         else {
@@ -974,7 +975,7 @@ function plainRelativeTo(relativeTo) {
             return relativeTo.toPlainDate();
         }
         if (typeof relativeTo === "string" &&
-            !TIME_ZONE_ANNOTATION.test(relativeTo)) {
+            !timeZoneAnnotation.test(relativeTo)) {
             return Temporal.PlainDate.from(relativeTo);
         }
         if (relativeTo !== null &&

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

@@ -0,0 +1,72 @@
+/** What `dwellTime` returns: exact elapsed time plus the local view every charging regime counts in. */
+export interface Dwell {
+    /** Exact elapsed time from entry to exit, as an ISO 8601 duration with hours as the largest unit. */
+    duration: string;
+    /** The entry, rendered in the dwell zone. */
+    enter: string;
+    /** The exit, rendered in the dwell zone. */
+    exit: string;
+    /** Distinct local calendar dates the dwell touched, counted half-open at the exit. */
+    calendarDays: number;
+}
+/**
+ * Measure how long something sat somewhere, and how many local calendar days it sat there.
+ *
+ * Terminals, depots, yards, stations, gates and berths all charge dwell, and none of them
+ * charge by elapsed hours. They count the local calendar days the thing was present, so a
+ * container that gates in at 23:00 and out at 01:00 has been there two hours and two days.
+ * `dwellTime` returns both, and is the one "local days crossed" primitive in the library: free
+ * time and demurrage (INT-12), laytime day counts (MAR-19) and hospital length of stay
+ * all take their day boundary from here rather than each deciding what a midnight is.
+ *
+ * - **`duration` is exact elapsed time.** A dwell spanning a DST transition reports the hours
+ *   that actually elapsed; the local wall clocks at either end can be an hour apart from that.
+ *   Hours is the largest unit, so the value never depends on a calendar.
+ * - **`calendarDays` is not `duration` rounded up.** It is the number of distinct local dates
+ *   in `targetZone` that the half-open interval `[entry, exit)` touches: entry and exit on the
+ *   same local date is `1`, across one local midnight is `2`, and so on. A dwell that ends
+ *   exactly at a local midnight does not touch the new day, because the exit instant itself
+ *   is excluded — the same half-open rule as `bucketRange` and CORE-6's intervals. A zero-length
+ *   dwell touches one date. The count walks the zone's real transitions: between two of them
+ *   the wall clock runs forward without a break, so each stretch touches every date from its
+ *   first instant to its last, and the count is the size of the union of those dates. A 23- or
+ *   25-hour local day is one day, not 0.96 or 1.04 of one; a date the zone deleted is never
+ *   touched (`Pacific/Apia` skipped 2011-12-30); and a date the clock falls back into is still
+ *   one date (`America/Goose_Bay` fell back from 00:01 on 7 November 2010 into the 6th).
+ * - **The zone decides the count, so it has to be stated.** `targetZone` is used when given.
+ *   Without it, the entry's bracketed IANA zone is used. As in `Temporal.Instant.from`, a
+ *   bracketed zone is otherwise not read, so it is not validated either: the entry's is read
+ *   (and must exist and agree with its offset) only when it supplies the dwell zone, because
+ *   `targetZone` is omitted, and the exit's is never read. If the entry and exit are bare
+ *   instants — `Z` or an offset — and no `targetZone` is given, the result is `null`: an
+ *   offset is not a zone (CORE-4), and a day count in an unstated locality would be a guess.
+ * - `enter` and `exit` are the two instants rendered in the dwell zone, so a charging record
+ *   shows the local times the terminal's own clock showed.
+ * - `targetZone` is whatever `isValidTimeZone` accepts, which is what Temporal accepts: an IANA
+ *   identifier, or a fixed offset such as `"+02:00"`, as `etaAtZone` also takes. Days are then
+ *   counted in that offset, which observes no DST, so pass the place's IANA zone when there is one.
+ * - GMT does not resolve a port, terminal or station code to a zone; the caller supplies the
+ *   identifier.
+ * - Long dwells stay cheap: the walk visits zone transitions, not days. A dwell that crosses
+ *   more than 10,000 transitions (about 5,000 years of twice-yearly DST) returns `null`.
+ * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
+ *   dwell is a data error, not a negative stay), or when no zone can be determined.
+ *
+ * @param entry ISO 8601 zoned datetime or instant string of the gate-in, arrival or admission
+ * @param exit ISO 8601 zoned datetime or instant string of the gate-out, departure or discharge
+ * @param targetZone IANA timeZone identifier or fixed offset the days are counted in; defaults to `entry`'s bracketed zone
+ * @returns exact duration, zone-local entry and exit, and the local calendar days touched, or null on invalid input
+ *
+ * @example dwellTime("2024-06-15T23:00:00-04:00[America/New_York]", "2024-06-16T01:00:00-04:00[America/New_York]") // { duration: "PT2H", enter: "2024-06-15T23:00:00-04:00[America/New_York]", exit: "2024-06-16T01:00:00-04:00[America/New_York]", calendarDays: 2 }
+ * @example dwellTime("2024-06-15T08:00:00Z", "2024-06-15T17:30:00Z", "Europe/Berlin") // { duration: "PT9H30M", enter: "2024-06-15T10:00:00+02:00[Europe/Berlin]", exit: "2024-06-15T19:30:00+02:00[Europe/Berlin]", calendarDays: 1 }
+ * @example dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "Europe/London") // { duration: "PT2H30M", enter: "2024-06-15T23:30:00+01:00[Europe/London]", exit: "2024-06-16T02:00:00+01:00[Europe/London]", calendarDays: 2 }
+ * @example dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "Europe/Amsterdam") // { duration: "PT2H30M", enter: "2024-06-16T00:30:00+02:00[Europe/Amsterdam]", exit: "2024-06-16T03:00:00+02:00[Europe/Amsterdam]", calendarDays: 1 } (the same two instants, one fewer day: the zone decides)
+ * @example dwellTime("2024-06-15T22:00:00Z", "2024-06-16T04:00:00Z", "America/New_York") // { duration: "PT6H", enter: "2024-06-15T18:00:00-04:00[America/New_York]", exit: "2024-06-16T00:00:00-04:00[America/New_York]", calendarDays: 1 } (an exit exactly at local midnight does not touch the new day)
+ * @example dwellTime("2024-03-10T05:00:00Z", "2024-03-10T12:00:00Z", "America/New_York") // { duration: "PT7H", enter: "2024-03-10T00:00:00-05:00[America/New_York]", exit: "2024-03-10T08:00:00-04:00[America/New_York]", calendarDays: 1 } (seven elapsed hours across the spring-forward, one local day)
+ * @example dwellTime("2011-12-30T08:00:00Z", "2011-12-30T11:00:00Z", "Pacific/Apia") // { duration: "PT3H", enter: "2011-12-29T22:00:00-10:00[Pacific/Apia]", exit: "2011-12-31T01:00:00+14:00[Pacific/Apia]", calendarDays: 2 } (29 and 31 December: Samoa deleted the 30th)
+ * @example dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "+02:00") // { duration: "PT2H30M", enter: "2024-06-16T00:30:00+02:00[+02:00]", exit: "2024-06-16T03:00:00+02:00[+02:00]", calendarDays: 1 } (a fixed offset counts days with no DST)
+ * @example dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z") // null (bare instants and no zone: the day count has no locality)
+ * @example dwellTime("2024-06-16T01:00:00Z", "2024-06-15T22:30:00Z", "Europe/London") // null (exit before entry)
+ * @example dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "Europe/Londres") // null
+ */
+export declare function dwellTime(entry: string, exit: string, targetZone?: string): Dwell | null;

package/dist/transport/calculate/dwellTime.js

@@ -0,0 +1,126 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { countZonedLocalDates, zonedDateTimeFrom } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
+import { isValidZonedDateTime } from "../../zoned/validate/isValidZonedDateTime.js";
+/**
+ * The zone a dwell is counted in: the caller's, or the one the entry string carries.
+ *
+ * An entry written with a bracketed IANA zone names a place; `Z` and offset-only strings name a
+ * moment and nothing else, so with no `targetZone` there is no locality to count days in.
+ */
+function dwellZone(entry, targetZone) {
+    if (targetZone !== undefined) {
+        return isValidTimeZone(targetZone) ? targetZone : null;
+    }
+    if (!isValidZonedDateTime(entry)) {
+        return null;
+    }
+    try {
+        return zonedDateTimeFrom(entry).timeZoneId;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Measure how long something sat somewhere, and how many local calendar days it sat there.
+ *
+ * Terminals, depots, yards, stations, gates and berths all charge dwell, and none of them
+ * charge by elapsed hours. They count the local calendar days the thing was present, so a
+ * container that gates in at 23:00 and out at 01:00 has been there two hours and two days.
+ * `dwellTime` returns both, and is the one "local days crossed" primitive in the library: free
+ * time and demurrage (INT-12), laytime day counts (MAR-19) and hospital length of stay
+ * all take their day boundary from here rather than each deciding what a midnight is.
+ *
+ * - **`duration` is exact elapsed time.** A dwell spanning a DST transition reports the hours
+ *   that actually elapsed; the local wall clocks at either end can be an hour apart from that.
+ *   Hours is the largest unit, so the value never depends on a calendar.
+ * - **`calendarDays` is not `duration` rounded up.** It is the number of distinct local dates
+ *   in `targetZone` that the half-open interval `[entry, exit)` touches: entry and exit on the
+ *   same local date is `1`, across one local midnight is `2`, and so on. A dwell that ends
+ *   exactly at a local midnight does not touch the new day, because the exit instant itself
+ *   is excluded — the same half-open rule as `bucketRange` and CORE-6's intervals. A zero-length
+ *   dwell touches one date. The count walks the zone's real transitions: between two of them
+ *   the wall clock runs forward without a break, so each stretch touches every date from its
+ *   first instant to its last, and the count is the size of the union of those dates. A 23- or
+ *   25-hour local day is one day, not 0.96 or 1.04 of one; a date the zone deleted is never
+ *   touched (`Pacific/Apia` skipped 2011-12-30); and a date the clock falls back into is still
+ *   one date (`America/Goose_Bay` fell back from 00:01 on 7 November 2010 into the 6th).
+ * - **The zone decides the count, so it has to be stated.** `targetZone` is used when given.
+ *   Without it, the entry's bracketed IANA zone is used. As in `Temporal.Instant.from`, a
+ *   bracketed zone is otherwise not read, so it is not validated either: the entry's is read
+ *   (and must exist and agree with its offset) only when it supplies the dwell zone, because
+ *   `targetZone` is omitted, and the exit's is never read. If the entry and exit are bare
+ *   instants — `Z` or an offset — and no `targetZone` is given, the result is `null`: an
+ *   offset is not a zone (CORE-4), and a day count in an unstated locality would be a guess.
+ * - `enter` and `exit` are the two instants rendered in the dwell zone, so a charging record
+ *   shows the local times the terminal's own clock showed.
+ * - `targetZone` is whatever `isValidTimeZone` accepts, which is what Temporal accepts: an IANA
+ *   identifier, or a fixed offset such as `"+02:00"`, as `etaAtZone` also takes. Days are then
+ *   counted in that offset, which observes no DST, so pass the place's IANA zone when there is one.
+ * - GMT does not resolve a port, terminal or station code to a zone; the caller supplies the
+ *   identifier.
+ * - Long dwells stay cheap: the walk visits zone transitions, not days. A dwell that crosses
+ *   more than 10,000 transitions (about 5,000 years of twice-yearly DST) returns `null`.
+ * - Returns `null` when either instant is invalid, when `exit` is before `entry` (an inverted
+ *   dwell is a data error, not a negative stay), or when no zone can be determined.
+ *
+ * @param entry ISO 8601 zoned datetime or instant string of the gate-in, arrival or admission
+ * @param exit ISO 8601 zoned datetime or instant string of the gate-out, departure or discharge
+ * @param targetZone IANA timeZone identifier or fixed offset the days are counted in; defaults to `entry`'s bracketed zone
+ * @returns exact duration, zone-local entry and exit, and the local calendar days touched, or null on invalid input
+ *
+ * @example dwellTime("2024-06-15T23:00:00-04:00[America/New_York]", "2024-06-16T01:00:00-04:00[America/New_York]") // { duration: "PT2H", enter: "2024-06-15T23:00:00-04:00[America/New_York]", exit: "2024-06-16T01:00:00-04:00[America/New_York]", calendarDays: 2 }
+ * @example dwellTime("2024-06-15T08:00:00Z", "2024-06-15T17:30:00Z", "Europe/Berlin") // { duration: "PT9H30M", enter: "2024-06-15T10:00:00+02:00[Europe/Berlin]", exit: "2024-06-15T19:30:00+02:00[Europe/Berlin]", calendarDays: 1 }
+ * @example dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "Europe/London") // { duration: "PT2H30M", enter: "2024-06-15T23:30:00+01:00[Europe/London]", exit: "2024-06-16T02:00:00+01:00[Europe/London]", calendarDays: 2 }
+ * @example dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "Europe/Amsterdam") // { duration: "PT2H30M", enter: "2024-06-16T00:30:00+02:00[Europe/Amsterdam]", exit: "2024-06-16T03:00:00+02:00[Europe/Amsterdam]", calendarDays: 1 } (the same two instants, one fewer day: the zone decides)
+ * @example dwellTime("2024-06-15T22:00:00Z", "2024-06-16T04:00:00Z", "America/New_York") // { duration: "PT6H", enter: "2024-06-15T18:00:00-04:00[America/New_York]", exit: "2024-06-16T00:00:00-04:00[America/New_York]", calendarDays: 1 } (an exit exactly at local midnight does not touch the new day)
+ * @example dwellTime("2024-03-10T05:00:00Z", "2024-03-10T12:00:00Z", "America/New_York") // { duration: "PT7H", enter: "2024-03-10T00:00:00-05:00[America/New_York]", exit: "2024-03-10T08:00:00-04:00[America/New_York]", calendarDays: 1 } (seven elapsed hours across the spring-forward, one local day)
+ * @example dwellTime("2011-12-30T08:00:00Z", "2011-12-30T11:00:00Z", "Pacific/Apia") // { duration: "PT3H", enter: "2011-12-29T22:00:00-10:00[Pacific/Apia]", exit: "2011-12-31T01:00:00+14:00[Pacific/Apia]", calendarDays: 2 } (29 and 31 December: Samoa deleted the 30th)
+ * @example dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "+02:00") // { duration: "PT2H30M", enter: "2024-06-16T00:30:00+02:00[+02:00]", exit: "2024-06-16T03:00:00+02:00[+02:00]", calendarDays: 1 } (a fixed offset counts days with no DST)
+ * @example dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z") // null (bare instants and no zone: the day count has no locality)
+ * @example dwellTime("2024-06-16T01:00:00Z", "2024-06-15T22:30:00Z", "Europe/London") // null (exit before entry)
+ * @example dwellTime("2024-06-15T22:30:00Z", "2024-06-16T01:00:00Z", "Europe/Londres") // null
+ */
+export function dwellTime(entry, exit, targetZone) {
+    try {
+        if (!isValidInstant(entry) || !isValidInstant(exit)) {
+            return null;
+        }
+        const zone = dwellZone(entry, targetZone);
+        if (zone === null) {
+            return null;
+        }
+        const entryInstant = Temporal.Instant.from(entry);
+        const exitInstant = Temporal.Instant.from(exit);
+        if (Temporal.Instant.compare(entryInstant, exitInstant) > 0) {
+            return null;
+        }
+        const enter = entryInstant.toZonedDateTimeISO(zone);
+        const leave = exitInstant.toZonedDateTimeISO(zone);
+        // Half-open at the exit: the dwell's last instant is one nanosecond before it, so an exit
+        // exactly on a local day boundary does not touch the new day. A zero-length dwell still
+        // touches the one date it sits on.
+        const last = Temporal.Instant.compare(entryInstant, exitInstant) < 0
+            ? leave.subtract({ nanoseconds: 1 })
+            : leave;
+        const calendarDays = countZonedLocalDates(enter, last);
+        if (calendarDays === null) {
+            return null;
+        }
+        return {
+            duration: entryInstant
+                .until(exitInstant, { largestUnit: "hours" })
+                .toString(),
+            enter: enter.toString(),
+            exit: leave.toString(),
+            calendarDays,
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,2 @@
+export * from "./dwellTime.js";
+export * from "./transitTime.js";

package/dist/transport/calculate/index.js

@@ -0,0 +1,2 @@
+export * from "./dwellTime.js";
+export * from "./transitTime.js";

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

@@ -0,0 +1,53 @@
+/**
+ * Add a transit duration to a departure and return the arrival, in the departure's own zone.
+ *
+ * The first of the three shared transport operations: a leg is a departure plus how long it
+ * takes. Every mode publishes it that way, and every mode gets the same thing wrong — a leg
+ * that crosses a DST transition is a fixed number of *elapsed* hours, not a wall-clock
+ * interval, so the local arrival time reflects the shift.
+ *
+ * - **Transit time is exact time.** Hours, minutes, seconds and fractions are added as elapsed
+ *   time, and a day component means 24 hours, exactly. That is TC39 Temporal's rule:
+ *   `Duration.prototype.round` and `total` without a `relativeTo` treat a day as 24 hours and
+ *   require a `relativeTo` for weeks, months and years. A 26-hour leg that starts the evening
+ *   before a spring-forward arrives at a wall time one hour later than a wall-clock reading would
+ *   suggest, because that is when the vessel, train or aircraft actually gets there.
+ * - **Calendar units are refused.** A `duration` with years, months or weeks returns `""`: no
+ *   leg takes "a month" in a sense that time arithmetic can fix without a reference point, and
+ *   Temporal will not add them to an instant either. Scheduled connections that are dated rather
+ *   than timed belong to `scheduleDelivery`.
+ * - **The departure's zone is preserved.** A bracketed IANA zone (`…-05:00[America/New_York]`)
+ *   stays that zone, so the arrival's offset is whatever is in force there at arrival. A `Z`
+ *   instant returns a `Z` instant; an offset-only instant keeps its offset, written exactly as
+ *   the departure wrote it, sub-minute offsets such as `+05:30:15` included (an offset is not a
+ *   zone, so nothing else can be inferred from it — see `toOffsetInstant`). A bracketed zone
+ *   that does not exist, or that contradicts its offset, is rejected as `isValidZonedDateTime`
+ *   rejects it; it does not fall back to the offset.
+ * - RFC 9557 annotations are read as `Temporal.Instant.from` reads them: a bracket without `=`
+ *   is a time zone, and a `key=value` bracket with an unknown key is ignored when elective and
+ *   rejected when critical (`[!…]`). A calendar on a departure without a zone is accepted and
+ *   changes nothing, since an instant has no calendar; a zoned departure's calendar must be ISO,
+ *   as `isValidZonedDateTime` requires.
+ * - A negative duration is allowed and moves backwards; that is how a departure is recovered
+ *   from an arrival.
+ * - Returns `""` when `departure` is not a zoned datetime or instant string, or `duration` is
+ *   not an ISO 8601 duration.
+ *
+ * @param departure ISO 8601 zoned datetime (bracketed zone) or instant string (`Z` or offset)
+ * @param duration ISO 8601 duration of the leg; time units and 24-hour days only
+ * @returns the arrival in the departure's zone or offset form, or "" on invalid input
+ *
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "PT2H30M") // "2024-06-15T12:30:00-04:00[America/New_York]"
+ * @example transitTime("2024-03-09T23:00:00-05:00[America/New_York]", "PT4H") // "2024-03-10T04:00:00-04:00[America/New_York]" (four elapsed hours across the spring-forward, so the wall clock reads 04:00, not 03:00)
+ * @example transitTime("2024-03-09T12:00:00-05:00[America/New_York]", "P1D") // "2024-03-10T13:00:00-04:00[America/New_York]" (a day is 24 elapsed hours, not "the same wall time tomorrow")
+ * @example transitTime("2024-06-15T10:00:00Z", "PT36H") // "2024-06-16T22:00:00Z"
+ * @example transitTime("2024-06-15T10:00:00+09:00", "PT1H") // "2024-06-15T11:00:00+09:00" (an offset stays an offset)
+ * @example transitTime("2024-06-15T10:00:00+05:30:15", "PT1H") // "2024-06-15T11:00:00+05:30:15" (a sub-minute offset is kept as written)
+ * @example transitTime("2024-06-15T10:00:00Z[foo=bar]", "PT1H") // "2024-06-15T11:00:00Z" (an elective unknown annotation is ignored)
+ * @example transitTime("2024-06-15T12:30:00-04:00[America/New_York]", "-PT2H30M") // "2024-06-15T10:00:00-04:00[America/New_York]"
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "P1M") // "" (calendar units need a reference point)
+ * @example transitTime("2024-06-15T10:00:00-05:00[America/New_York]", "PT2H") // "" (New York is -04:00 in June: the offset contradicts the zone)
+ * @example transitTime("2024-06-15T10:00:00", "PT2H") // "" (no zone and no offset: not a moment)
+ * @example transitTime("2024-06-15T10:00:00Z", "2 hours") // ""
+ */
+export declare function transitTime(departure: string, duration: string): string;

package/dist/transport/calculate/transitTime.js

@@ -0,0 +1,118 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { EXTENDED_UTC_OFFSET, TIME_ZONE_ANNOTATION, utcOffsetStringNanoseconds, wallClockAtOffset, zonedDateTimeFrom, } from "../../internal/index.js";
+import { isValidDuration } from "../../duration/validate/isValidDuration.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+import { isValidZonedDateTime } from "../../zoned/validate/isValidZonedDateTime.js";
+/**
+ * Trailing `Z` or extended offset of an instant string, before any annotation. The offset grammar
+ * is `isValidInstant`'s own (`EXTENDED_UTC_OFFSET`), so every offset it accepts, `,` fractions
+ * included, is captured as written.
+ */
+const trailingOffset = new RegExp(`(Z|${EXTENDED_UTC_OFFSET})(?:\\[[^\\]]*\\])*$`);
+/**
+ * A time-zone annotation anywhere in the string (`TIME_ZONE_ANNOTATION`). Every `key=value`
+ * bracket is a tagged annotation, which `isValidInstant` already decides.
+ */
+const zoneAnnotation = new RegExp(TIME_ZONE_ANNOTATION);
+/**
+ * Add a transit duration to a departure and return the arrival, in the departure's own zone.
+ *
+ * The first of the three shared transport operations: a leg is a departure plus how long it
+ * takes. Every mode publishes it that way, and every mode gets the same thing wrong — a leg
+ * that crosses a DST transition is a fixed number of *elapsed* hours, not a wall-clock
+ * interval, so the local arrival time reflects the shift.
+ *
+ * - **Transit time is exact time.** Hours, minutes, seconds and fractions are added as elapsed
+ *   time, and a day component means 24 hours, exactly. That is TC39 Temporal's rule:
+ *   `Duration.prototype.round` and `total` without a `relativeTo` treat a day as 24 hours and
+ *   require a `relativeTo` for weeks, months and years. A 26-hour leg that starts the evening
+ *   before a spring-forward arrives at a wall time one hour later than a wall-clock reading would
+ *   suggest, because that is when the vessel, train or aircraft actually gets there.
+ * - **Calendar units are refused.** A `duration` with years, months or weeks returns `""`: no
+ *   leg takes "a month" in a sense that time arithmetic can fix without a reference point, and
+ *   Temporal will not add them to an instant either. Scheduled connections that are dated rather
+ *   than timed belong to `scheduleDelivery`.
+ * - **The departure's zone is preserved.** A bracketed IANA zone (`…-05:00[America/New_York]`)
+ *   stays that zone, so the arrival's offset is whatever is in force there at arrival. A `Z`
+ *   instant returns a `Z` instant; an offset-only instant keeps its offset, written exactly as
+ *   the departure wrote it, sub-minute offsets such as `+05:30:15` included (an offset is not a
+ *   zone, so nothing else can be inferred from it — see `toOffsetInstant`). A bracketed zone
+ *   that does not exist, or that contradicts its offset, is rejected as `isValidZonedDateTime`
+ *   rejects it; it does not fall back to the offset.
+ * - RFC 9557 annotations are read as `Temporal.Instant.from` reads them: a bracket without `=`
+ *   is a time zone, and a `key=value` bracket with an unknown key is ignored when elective and
+ *   rejected when critical (`[!…]`). A calendar on a departure without a zone is accepted and
+ *   changes nothing, since an instant has no calendar; a zoned departure's calendar must be ISO,
+ *   as `isValidZonedDateTime` requires.
+ * - A negative duration is allowed and moves backwards; that is how a departure is recovered
+ *   from an arrival.
+ * - Returns `""` when `departure` is not a zoned datetime or instant string, or `duration` is
+ *   not an ISO 8601 duration.
+ *
+ * @param departure ISO 8601 zoned datetime (bracketed zone) or instant string (`Z` or offset)
+ * @param duration ISO 8601 duration of the leg; time units and 24-hour days only
+ * @returns the arrival in the departure's zone or offset form, or "" on invalid input
+ *
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "PT2H30M") // "2024-06-15T12:30:00-04:00[America/New_York]"
+ * @example transitTime("2024-03-09T23:00:00-05:00[America/New_York]", "PT4H") // "2024-03-10T04:00:00-04:00[America/New_York]" (four elapsed hours across the spring-forward, so the wall clock reads 04:00, not 03:00)
+ * @example transitTime("2024-03-09T12:00:00-05:00[America/New_York]", "P1D") // "2024-03-10T13:00:00-04:00[America/New_York]" (a day is 24 elapsed hours, not "the same wall time tomorrow")
+ * @example transitTime("2024-06-15T10:00:00Z", "PT36H") // "2024-06-16T22:00:00Z"
+ * @example transitTime("2024-06-15T10:00:00+09:00", "PT1H") // "2024-06-15T11:00:00+09:00" (an offset stays an offset)
+ * @example transitTime("2024-06-15T10:00:00+05:30:15", "PT1H") // "2024-06-15T11:00:00+05:30:15" (a sub-minute offset is kept as written)
+ * @example transitTime("2024-06-15T10:00:00Z[foo=bar]", "PT1H") // "2024-06-15T11:00:00Z" (an elective unknown annotation is ignored)
+ * @example transitTime("2024-06-15T12:30:00-04:00[America/New_York]", "-PT2H30M") // "2024-06-15T10:00:00-04:00[America/New_York]"
+ * @example transitTime("2024-06-15T10:00:00-04:00[America/New_York]", "P1M") // "" (calendar units need a reference point)
+ * @example transitTime("2024-06-15T10:00:00-05:00[America/New_York]", "PT2H") // "" (New York is -04:00 in June: the offset contradicts the zone)
+ * @example transitTime("2024-06-15T10:00:00", "PT2H") // "" (no zone and no offset: not a moment)
+ * @example transitTime("2024-06-15T10:00:00Z", "2 hours") // ""
+ */
+export function transitTime(departure, duration) {
+    // A non-string would reach the regex tests below, which coerce it: a throwing `toString`, a
+    // Symbol or a hostile Proxy would escape. Refuse it before any read.
+    if (typeof departure !== "string" || typeof duration !== "string") {
+        return "";
+    }
+    try {
+        return addLeg(departure, duration);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}
+/** `transitTime` for two strings, without the guard. */
+function addLeg(departure, duration) {
+    if (!isValidDuration(duration)) {
+        return "";
+    }
+    const zoned = isValidZonedDateTime(departure);
+    // A string that names a zone must name a real one that agrees with its offset; only a string
+    // that names none may fall back to the instant path.
+    if (!zoned &&
+        (zoneAnnotation.test(departure) || !isValidInstant(departure))) {
+        return "";
+    }
+    try {
+        const parsed = Temporal.Duration.from(duration);
+        if (parsed.years !== 0 || parsed.months !== 0 || parsed.weeks !== 0) {
+            return "";
+        }
+        // Days become 24 exact hours; every remaining unit is already exact time.
+        const exact = parsed.round({ largestUnit: "hours" });
+        if (zoned) {
+            return zonedDateTimeFrom(departure).add(exact).toString();
+        }
+        const arrival = Temporal.Instant.from(departure).add(exact);
+        const offset = trailingOffset.exec(departure)?.[1] ?? "Z";
+        if (offset === "Z") {
+            return arrival.toString();
+        }
+        // The arrival's wall clock in the departure's own offset, written with that offset's text.
+        const wall = wallClockAtOffset(arrival, utcOffsetStringNanoseconds(offset));
+        return `${wall.toString()}${offset}`;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/transport/convert/etaAtZone.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Render an arrival instant as local time in the zone where it will be read.
+ *
+ * Schedules are computed in UTC and displayed where the cargo lands. The zone is the caller's
+ * fact: GMT does not resolve a port, airport, terminal or station code to a timezone, and
+ * takes an IANA identifier instead (see the parked registries note in the epic's painpoints).
+ *
+ * - `arrivalUtc` is any instant `isValidInstant` accepts — `Z`, an offset, or an offset with a
+ *   bracketed zone. Only the instant is read; a bracketed zone in the input is not the zone the
+ *   result is rendered in, `targetZone` is.
+ * - **No disambiguation arises.** The input is a moment, and a moment has exactly one wall
+ *   time in any zone, so the `disambiguation` vocabulary of `resolveLocal` does not apply here.
+ *   On a fall-back night two moments an hour apart print the same wall time with different
+ *   offsets, and the offset in the result is what tells them apart; on a spring-forward night
+ *   the skipped hour simply never appears. That is also why the result carries its offset and
+ *   zone rather than a bare wall time.
+ * - Returns a zoned ISO 8601 string, `Temporal.ZonedDateTime.prototype.toString()`'s form:
+ *   wall time, offset, bracketed zone.
+ * - `targetZone` is whatever `isValidTimeZone` accepts, which is what Temporal accepts: an IANA
+ *   identifier, or a fixed offset such as `"+09:00"`, which renders with the offset as its zone.
+ *   A fixed offset is a legitimate rendering choice for a ship's log (MAR-18); it is not a place.
+ * - Returns `""` when the instant or the zone is invalid.
+ *
+ * @param arrivalUtc ISO 8601 instant string of the arrival
+ * @param targetZone IANA timeZone identifier of the place the arrival is read in
+ * @returns zoned ISO 8601 string of the local arrival, or "" on invalid input
+ *
+ * @example etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokyo") // "2024-06-15T21:30:00+09:00[Asia/Tokyo]"
+ * @example etaAtZone("2024-06-15T12:30:00Z", "America/Los_Angeles") // "2024-06-15T05:30:00-07:00[America/Los_Angeles]"
+ * @example etaAtZone("2024-06-15T12:30:00+02:00", "Pacific/Apia") // "2024-06-15T23:30:00+13:00[Pacific/Apia]" (the offset fixes the instant; the zone renders it)
+ * @example etaAtZone("2024-11-03T05:30:00Z", "America/New_York") // "2024-11-03T01:30:00-04:00[America/New_York]" (the first 01:30 of the fall-back night)
+ * @example etaAtZone("2024-11-03T06:30:00Z", "America/New_York") // "2024-11-03T01:30:00-05:00[America/New_York]" (the second; the offset tells them apart)
+ * @example etaAtZone("2024-06-15T12:30:00", "Asia/Tokyo") // "" (no offset designator: not a moment)
+ * @example etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokio") // ""
+ */
+export declare function etaAtZone(arrivalUtc: string, targetZone: string): string;

package/dist/transport/convert/etaAtZone.js

@@ -0,0 +1,53 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+import { isValidTimeZone } from "../../zoned/validate/isValidTimeZone.js";
+/**
+ * Render an arrival instant as local time in the zone where it will be read.
+ *
+ * Schedules are computed in UTC and displayed where the cargo lands. The zone is the caller's
+ * fact: GMT does not resolve a port, airport, terminal or station code to a timezone, and
+ * takes an IANA identifier instead (see the parked registries note in the epic's painpoints).
+ *
+ * - `arrivalUtc` is any instant `isValidInstant` accepts — `Z`, an offset, or an offset with a
+ *   bracketed zone. Only the instant is read; a bracketed zone in the input is not the zone the
+ *   result is rendered in, `targetZone` is.
+ * - **No disambiguation arises.** The input is a moment, and a moment has exactly one wall
+ *   time in any zone, so the `disambiguation` vocabulary of `resolveLocal` does not apply here.
+ *   On a fall-back night two moments an hour apart print the same wall time with different
+ *   offsets, and the offset in the result is what tells them apart; on a spring-forward night
+ *   the skipped hour simply never appears. That is also why the result carries its offset and
+ *   zone rather than a bare wall time.
+ * - Returns a zoned ISO 8601 string, `Temporal.ZonedDateTime.prototype.toString()`'s form:
+ *   wall time, offset, bracketed zone.
+ * - `targetZone` is whatever `isValidTimeZone` accepts, which is what Temporal accepts: an IANA
+ *   identifier, or a fixed offset such as `"+09:00"`, which renders with the offset as its zone.
+ *   A fixed offset is a legitimate rendering choice for a ship's log (MAR-18); it is not a place.
+ * - Returns `""` when the instant or the zone is invalid.
+ *
+ * @param arrivalUtc ISO 8601 instant string of the arrival
+ * @param targetZone IANA timeZone identifier of the place the arrival is read in
+ * @returns zoned ISO 8601 string of the local arrival, or "" on invalid input
+ *
+ * @example etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokyo") // "2024-06-15T21:30:00+09:00[Asia/Tokyo]"
+ * @example etaAtZone("2024-06-15T12:30:00Z", "America/Los_Angeles") // "2024-06-15T05:30:00-07:00[America/Los_Angeles]"
+ * @example etaAtZone("2024-06-15T12:30:00+02:00", "Pacific/Apia") // "2024-06-15T23:30:00+13:00[Pacific/Apia]" (the offset fixes the instant; the zone renders it)
+ * @example etaAtZone("2024-11-03T05:30:00Z", "America/New_York") // "2024-11-03T01:30:00-04:00[America/New_York]" (the first 01:30 of the fall-back night)
+ * @example etaAtZone("2024-11-03T06:30:00Z", "America/New_York") // "2024-11-03T01:30:00-05:00[America/New_York]" (the second; the offset tells them apart)
+ * @example etaAtZone("2024-06-15T12:30:00", "Asia/Tokyo") // "" (no offset designator: not a moment)
+ * @example etaAtZone("2024-06-15T12:30:00Z", "Asia/Tokio") // ""
+ */
+export function etaAtZone(arrivalUtc, targetZone) {
+    try {
+        if (!isValidInstant(arrivalUtc) || !isValidTimeZone(targetZone)) {
+            return "";
+        }
+        return Temporal.Instant.from(arrivalUtc)
+            .toZonedDateTimeISO(targetZone)
+            .toString();
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/transport/convert/index.d.ts

@@ -0,0 +1 @@
+export * from "./etaAtZone.js";

package/dist/transport/convert/index.js

@@ -0,0 +1 @@
+export * from "./etaAtZone.js";

package/dist/transport/index.d.ts

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

package/dist/transport/index.js

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

package/dist/types/free-time-options.d.ts

@@ -0,0 +1,34 @@
+import type { BusinessCalendar } from "./business-calendar.js";
+/**
+ * How days are counted: every local calendar day, or only the terminal's working days. Used for
+ * free time (`basis`) and, separately, for the days charged after it (`chargeBasis`), because
+ * published tariffs commonly count the two differently.
+ */
+export type FreeTimeBasis = "calendar" | "working";
+/**
+ * Whether the day of the triggering event is free day one (`"eventDay"`), or free time starts
+ * on the following counted day (`"nextDay"`). The two conventions differ by one full day of
+ * charges, so no function defaults it.
+ */
+export type FreeTimeFirstDay = "eventDay" | "nextDay";
+/**
+ * The tariff terms a free-time count needs. Free time is set by carrier, lane, trade and service
+ * contract, never by port, so every term is a parameter and no counting term has a default.
+ *
+ * - `basis`: `"calendar"` counts every local day, so a weekend burns two free days while the
+ *   terminal is shut; `"working"` counts only the days `calendar` marks as working, and the
+ *   clock does not run on weekends or holidays.
+ * - `timeZone`: the IANA identifier of the terminal, depot or yard whose local midnight ends a
+ *   day. GMT does not resolve a port or terminal code to a zone. A fixed offset such as
+ *   `"+02:00"` is accepted, as `isValidTimeZone` accepts it, but observes no DST.
+ * - `firstDay`: `"eventDay"` or `"nextDay"`, see `FreeTimeFirstDay`.
+ * - `calendar`: the terminal's `BusinessCalendar`, required when `basis` is `"working"` and not
+ *   read when it is `"calendar"`. Its `timeZone` field is not read either, as the business-day
+ *   functions never read it: `timeZone` above is the counting zone.
+ */
+export type FreeTimeOptions = {
+    basis: FreeTimeBasis;
+    timeZone: string;
+    firstDay: FreeTimeFirstDay;
+    calendar?: BusinessCalendar;
+};