@northguild/gmt 1.15.0 → 1.17.0

package/dist/span/calculate/spanMs.js

@@ -0,0 +1,80 @@
+import { spanNs } from "./spanNs.js";
+/** Nanoseconds in a millisecond. */
+const NANOSECONDS_PER_MILLISECOND = 1000000n;
+/**
+ * The largest span, in nanoseconds, whose exact millisecond value a `number` still holds.
+ *
+ * Guarding here rather than on the truncated whole-millisecond part matters: a span of
+ * `MAX_SAFE_INTEGER` milliseconds *plus* a fraction passes a whole-millisecond check and
+ * then rounds up to 2^53 on recombination, returning an unsafe integer from a function
+ * documented to return the sentinel past the safe range.
+ */
+const MAX_SAFE_NANOSECONDS = BigInt(Number.MAX_SAFE_INTEGER) * NANOSECONDS_PER_MILLISECOND;
+/**
+ * Return the exact elapsed milliseconds between two ISO 8601 instant strings.
+ *
+ * The universal span primitive for profiling and observability. Fractional, like
+ * `performance.now()` — a sub-millisecond span is reported as a fraction, not rounded away.
+ *
+ * - Signed: negative when `start` is after `end`, so `spanMs(b, a)` is exactly
+ *   `-spanMs(a, b)`.
+ * - Measures **exact elapsed time**, never calendar distance. A wall-clock day containing a
+ *   DST transition is 23 or 25 hours (or 24.5, in `Australia/Lord_Howe`), and `spanMs`
+ *   reports the hours that actually elapsed. `spanWallClock` answers the calendar question;
+ *   conflating the two is the most common span bug there is.
+ * - Accepts anything `toNanoseconds` does: the full RFC 9557 instant grammar, no leap
+ *   seconds; calendar and elective annotations are ignored, as `Temporal.Instant.from` ignores
+ *   them. An offset designator (`Z`, `±HH:MM`) is
+ *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
+ *   which is the one string shape `spanWallClock` accepts and these two do not. The
+ *   endpoints need not share a zone; an instant is an instant.
+ * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
+ *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
+ *   with the offset is not checked. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - Returns `null` on invalid input, not `0` — `0` is the span between an instant and itself.
+ *   `null`, not `NaN`, because that is GMT's sentinel for every number-returning function:
+ *   it is the one a caller already checks for, and the only one `strictNullChecks` forces
+ *   them to handle. A `NaN` would type as plain `number` and propagate silently through
+ *   arithmetic. `spanNs` and `spanWallClock` return `null` for the same reason.
+ * - **Safe range.** Returns `null` when the exact span exceeds `Number.MAX_SAFE_INTEGER`
+ *   milliseconds (±9_007_199_254_740_991 ms, about ±285,000 years), which two instants at
+ *   opposite ends of `Temporal.Instant`'s range do. A sub-millisecond fraction counts
+ *   toward that ceiling, so any number returned is a safe integer or below. Use `spanNs`
+ *   past it — it carries the exact value as a `bigint`.
+ *   Sub-millisecond fidelity goes first, long before the ceiling: a double carries the
+ *   nanosecond digits exactly only while the span is under 2^53 ns, roughly 104 days.
+ * - Leap seconds are not counted. UTC repeats a second rather than numbering a 61st one, so
+ *   a span across one is a second short of the physical elapsed time; against a smeared
+ *   clock (Google, AWS, Meta) the error is up to a second spread over the smear window.
+ *   Leap-second-exact spans need a TAI scale, which GMT does not yet ship.
+ *
+ * @param start ISO 8601 instant string the span is measured from
+ * @param end ISO 8601 instant string the span is measured to
+ * @returns exact elapsed milliseconds, negative when start is after end, or null on invalid input
+ *
+ * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z") // 1000
+ * @example spanMs("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // -1000
+ * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0
+ * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00.123456789Z") // 123.456789
+ * @example spanMs("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 82800000 — 23 hours, not 24
+ * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is ignored
+ * @example spanMs("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // null — past the safe integer range, use spanNs
+ * @example spanMs("2024-03-10T12:00:00Z", "invalid") // null
+ */
+export function spanMs(start, end) {
+    const nanoseconds = spanNs(start, end);
+    if (nanoseconds === null) {
+        return null;
+    }
+    if (nanoseconds > MAX_SAFE_NANOSECONDS ||
+        nanoseconds < -MAX_SAFE_NANOSECONDS) {
+        return null;
+    }
+    // Split rather than dividing the whole bigint through a double: Number(nanoseconds) is
+    // already lossy past 2^53 ns (~104 days), which would corrupt the millisecond part too.
+    // BigInt division truncates toward zero and `%` keeps the dividend's sign, so both halves
+    // flip together and spanMs(b, a) === -spanMs(a, b) holds exactly.
+    const milliseconds = nanoseconds / NANOSECONDS_PER_MILLISECOND;
+    const remainder = nanoseconds % NANOSECONDS_PER_MILLISECOND;
+    return Number(milliseconds) + Number(remainder) / 1e6;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Return the exact elapsed nanoseconds between two ISO 8601 instant strings.
+ *
+ * The precise form of `spanMs`, and the one to reach for past a `number`'s safe range.
+ *
+ * - Signed: negative when `start` is after `end`, so `spanNs(b, a)` is exactly
+ *   `-spanNs(a, b)`.
+ * - Measures **exact elapsed time**, never calendar distance. Across a DST transition
+ *   "one day later" and "24 hours later" are different spans — `spanWallClock` answers
+ *   the calendar question.
+ * - Accepts anything `toNanoseconds` does: the full RFC 9557 instant grammar, no leap
+ *   seconds; calendar and elective annotations are ignored, as `Temporal.Instant.from` ignores
+ *   them. An offset designator (`Z`, `±HH:MM`) is
+ *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
+ *   which is the one string shape `spanWallClock` accepts and these two do not. The
+ *   endpoints need not share a zone; an instant is an instant.
+ * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
+ *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
+ *   with the offset is not checked. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - Returns `null` on invalid input, not `0n` — `0n` is the span between an instant and
+ *   itself. This is why it does not simply subtract two `toNanoseconds` results, which
+ *   return `0n` for both the epoch and a rejected string.
+ * - The result is a **duration**, not an instant: it ranges up to
+ *   ±17_280_000_000_000_000_000_000n, twice what `Temporal.Instant` can represent. Do not
+ *   feed it to `fromNanoseconds`.
+ * - Leap seconds are not counted. UTC repeats a second rather than numbering a 61st one, so
+ *   a span across one is a second short of the physical elapsed time; against a smeared
+ *   clock (Google, AWS, Meta) the error is up to a second spread over the smear window.
+ *   Leap-second-exact spans need a TAI scale, which GMT does not yet ship.
+ *
+ * @param start ISO 8601 instant string the span is measured from
+ * @param end ISO 8601 instant string the span is measured to
+ * @returns exact elapsed nanoseconds as a bigint, negative when start is after end, or null on invalid input
+ *
+ * @example spanNs("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z") // 1000000000n
+ * @example spanNs("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // -1000000000n
+ * @example spanNs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0n
+ * @example spanNs("2024-03-10T12:00:00.123456789Z", "2024-03-10T12:00:00.123456790Z") // 1n
+ * @example spanNs("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // 0n — same instant, different zones
+ * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is ignored
+ * @example spanNs("2024-03-10T12:00:00Z", "invalid") // null
+ */
+export declare function spanNs(start: string, end: string): bigint | null;

package/dist/span/calculate/spanNs.js

@@ -0,0 +1,51 @@
+import { parseInstantNanoseconds } from "../../internal/index.js";
+/**
+ * Return the exact elapsed nanoseconds between two ISO 8601 instant strings.
+ *
+ * The precise form of `spanMs`, and the one to reach for past a `number`'s safe range.
+ *
+ * - Signed: negative when `start` is after `end`, so `spanNs(b, a)` is exactly
+ *   `-spanNs(a, b)`.
+ * - Measures **exact elapsed time**, never calendar distance. Across a DST transition
+ *   "one day later" and "24 hours later" are different spans — `spanWallClock` answers
+ *   the calendar question.
+ * - Accepts anything `toNanoseconds` does: the full RFC 9557 instant grammar, no leap
+ *   seconds; calendar and elective annotations are ignored, as `Temporal.Instant.from` ignores
+ *   them. An offset designator (`Z`, `±HH:MM`) is
+ *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
+ *   which is the one string shape `spanWallClock` accepts and these two do not. The
+ *   endpoints need not share a zone; an instant is an instant.
+ * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
+ *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
+ *   with the offset is not checked. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - Returns `null` on invalid input, not `0n` — `0n` is the span between an instant and
+ *   itself. This is why it does not simply subtract two `toNanoseconds` results, which
+ *   return `0n` for both the epoch and a rejected string.
+ * - The result is a **duration**, not an instant: it ranges up to
+ *   ±17_280_000_000_000_000_000_000n, twice what `Temporal.Instant` can represent. Do not
+ *   feed it to `fromNanoseconds`.
+ * - Leap seconds are not counted. UTC repeats a second rather than numbering a 61st one, so
+ *   a span across one is a second short of the physical elapsed time; against a smeared
+ *   clock (Google, AWS, Meta) the error is up to a second spread over the smear window.
+ *   Leap-second-exact spans need a TAI scale, which GMT does not yet ship.
+ *
+ * @param start ISO 8601 instant string the span is measured from
+ * @param end ISO 8601 instant string the span is measured to
+ * @returns exact elapsed nanoseconds as a bigint, negative when start is after end, or null on invalid input
+ *
+ * @example spanNs("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z") // 1000000000n
+ * @example spanNs("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // -1000000000n
+ * @example spanNs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0n
+ * @example spanNs("2024-03-10T12:00:00.123456789Z", "2024-03-10T12:00:00.123456790Z") // 1n
+ * @example spanNs("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // 0n — same instant, different zones
+ * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is ignored
+ * @example spanNs("2024-03-10T12:00:00Z", "invalid") // null
+ */
+export function spanNs(start, end) {
+    const startNanoseconds = parseInstantNanoseconds(start);
+    const endNanoseconds = parseInstantNanoseconds(end);
+    if (startNanoseconds === null || endNanoseconds === null) {
+        return null;
+    }
+    return endNanoseconds - startNanoseconds;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Units `spanWallClock` measures a calendar distance in.
+ *
+ * | Unit | Meaning |
+ * | --- | --- |
+ * | `days` | Whole wall-clock days — a calendar day, whatever number of hours it happened to last. |
+ * | `hours` | Whole wall-clock hours — the hours a clock face advanced, not the hours that elapsed. |
+ * | `day`, `hour` | The singular names, accepted as Temporal accepts them. |
+ */
+export type WallClockSpanUnit = "days" | "hours" | "day" | "hour";
+/**
+ * Return the wall-clock distance between two zoned datetime strings — calendar time, not
+ * elapsed time.
+ *
+ * The counterpart to `spanMs`. Both are correct answers to different questions, and
+ * conflating them is the most common span bug there is: across a DST transition "one day
+ * later" and "24 hours later" are not the same moment.
+ *
+ * - Reads each endpoint's own local wall clock and measures between them, so a calendar day
+ *   is 1 day and 24 hours in every zone, including one whose offset shifted in between.
+ *   `spanMs` over the same pair reports the 23, 24.5 or 25 hours that actually elapsed.
+ * - Truncates toward zero, so the result is a whole count and `spanWallClock(b, a, unit)` is
+ *   `-spanWallClock(a, b, unit)`. Noon Friday to 18:00 Saturday is 1 day, or 30 hours — ask
+ *   for `hours` when the remainder matters.
+ * - **Not a count of boundaries crossed.** 23:00 to 01:00 the next calendar day is `0` days,
+ *   not `1`; that question is about local midnights, and is `startOfZoned`'s to answer.
+ * - **No disambiguation policy applies, because no local time is converted to an instant.**
+ *   The wall clock is read straight off the string with `Temporal.PlainDateTime.from`. Going
+ *   via `ZonedDateTime` would be a local → instant → local round trip, and that round trip is
+ *   lossy at exactly the DST edges this function exists to get right: an offset-less
+ *   `"2024-03-10T02:30:00[America/New_York]"` names a wall time that never occurred, and
+ *   Temporal's default `compatible` disambiguation would silently advance it to `03:30`,
+ *   turning a 24-hour answer into 23. A nonexistent or ambiguous local time is measured as
+ *   written instead — for a clock-face question, the digits in the string *are* the answer.
+ * - Requires a bracketed IANA time zone on both endpoints, as `isValidZonedDateTime` does —
+ *   an instant string (`Z`) or a bare offset carries no zone whose wall clock could shift.
+ *   The offset is optional, but a present one must match the zone. Leap seconds and
+ *   `[u-ca=...]` calendar annotations are rejected; `days` and `hours` mean the same thing in
+ *   every calendar system, so the annotation would change nothing.
+ * - The endpoints need not share a zone. When they differ, this is the distance between two
+ *   local wall clocks — a flight leaving New York at 23:00 and landing in Berlin at 11:00 the
+ *   next local day is 12 wall-clock hours, and 7 elapsed hours by `spanMs`.
+ * - Returns `null` on invalid input, not `0` — `0` is the span between a wall time and itself.
+ *
+ * @param start zoned ISO 8601 datetime string the span is measured from
+ * @param end zoned ISO 8601 datetime string the span is measured to
+ * @param unit "days" or "hours" (or the singular "day" or "hour") of wall-clock distance
+ * @returns whole wall-clock units, negative when start is after end, or null on invalid input
+ *
+ * @example spanWallClock("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]", "hours") // 24 — spanMs reports 82800000 (23 hours)
+ * @example spanWallClock("2024-11-02T12:00:00-04:00[America/New_York]", "2024-11-03T12:00:00-05:00[America/New_York]", "days") // 1 — spanMs reports 90000000 (25 hours)
+ * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T18:00:00-05:00[America/New_York]", "days") // 1 — truncated toward zero
+ * @example spanWallClock("2024-03-02T18:00:00-05:00[America/New_York]", "2024-03-01T12:00:00-05:00[America/New_York]", "hours") // -30
+ * @example spanWallClock("2024-03-10T23:00:00-04:00[America/New_York]", "2024-03-11T11:00:00+01:00[Europe/Berlin]", "hours") // 12 — each endpoint's own wall clock
+ * @example spanWallClock("2024-03-10T02:30:00[America/New_York]", "2024-03-11T02:30:00[America/New_York]", "hours") // 24 — a wall time that never occurred is measured as written
+ * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T12:00:00-05:00[America/New_York]", "day") // 1 — singular unit name
+ * @example spanWallClock("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "days") // null — no bracketed time zone
+ * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T12:00:00-05:00[America/New_York]", "minutes") // null
+ */
+export declare function spanWallClock(start: string, end: string, unit: WallClockSpanUnit): number | null;

package/dist/span/calculate/spanWallClock.js

@@ -0,0 +1,80 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../../zoned/validate/index.js";
+const WALL_CLOCK_SPAN_UNITS = {
+    days: "day",
+    hours: "hour",
+    day: "day",
+    hour: "hour",
+};
+/**
+ * Return the wall-clock distance between two zoned datetime strings — calendar time, not
+ * elapsed time.
+ *
+ * The counterpart to `spanMs`. Both are correct answers to different questions, and
+ * conflating them is the most common span bug there is: across a DST transition "one day
+ * later" and "24 hours later" are not the same moment.
+ *
+ * - Reads each endpoint's own local wall clock and measures between them, so a calendar day
+ *   is 1 day and 24 hours in every zone, including one whose offset shifted in between.
+ *   `spanMs` over the same pair reports the 23, 24.5 or 25 hours that actually elapsed.
+ * - Truncates toward zero, so the result is a whole count and `spanWallClock(b, a, unit)` is
+ *   `-spanWallClock(a, b, unit)`. Noon Friday to 18:00 Saturday is 1 day, or 30 hours — ask
+ *   for `hours` when the remainder matters.
+ * - **Not a count of boundaries crossed.** 23:00 to 01:00 the next calendar day is `0` days,
+ *   not `1`; that question is about local midnights, and is `startOfZoned`'s to answer.
+ * - **No disambiguation policy applies, because no local time is converted to an instant.**
+ *   The wall clock is read straight off the string with `Temporal.PlainDateTime.from`. Going
+ *   via `ZonedDateTime` would be a local → instant → local round trip, and that round trip is
+ *   lossy at exactly the DST edges this function exists to get right: an offset-less
+ *   `"2024-03-10T02:30:00[America/New_York]"` names a wall time that never occurred, and
+ *   Temporal's default `compatible` disambiguation would silently advance it to `03:30`,
+ *   turning a 24-hour answer into 23. A nonexistent or ambiguous local time is measured as
+ *   written instead — for a clock-face question, the digits in the string *are* the answer.
+ * - Requires a bracketed IANA time zone on both endpoints, as `isValidZonedDateTime` does —
+ *   an instant string (`Z`) or a bare offset carries no zone whose wall clock could shift.
+ *   The offset is optional, but a present one must match the zone. Leap seconds and
+ *   `[u-ca=...]` calendar annotations are rejected; `days` and `hours` mean the same thing in
+ *   every calendar system, so the annotation would change nothing.
+ * - The endpoints need not share a zone. When they differ, this is the distance between two
+ *   local wall clocks — a flight leaving New York at 23:00 and landing in Berlin at 11:00 the
+ *   next local day is 12 wall-clock hours, and 7 elapsed hours by `spanMs`.
+ * - Returns `null` on invalid input, not `0` — `0` is the span between a wall time and itself.
+ *
+ * @param start zoned ISO 8601 datetime string the span is measured from
+ * @param end zoned ISO 8601 datetime string the span is measured to
+ * @param unit "days" or "hours" (or the singular "day" or "hour") of wall-clock distance
+ * @returns whole wall-clock units, negative when start is after end, or null on invalid input
+ *
+ * @example spanWallClock("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]", "hours") // 24 — spanMs reports 82800000 (23 hours)
+ * @example spanWallClock("2024-11-02T12:00:00-04:00[America/New_York]", "2024-11-03T12:00:00-05:00[America/New_York]", "days") // 1 — spanMs reports 90000000 (25 hours)
+ * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T18:00:00-05:00[America/New_York]", "days") // 1 — truncated toward zero
+ * @example spanWallClock("2024-03-02T18:00:00-05:00[America/New_York]", "2024-03-01T12:00:00-05:00[America/New_York]", "hours") // -30
+ * @example spanWallClock("2024-03-10T23:00:00-04:00[America/New_York]", "2024-03-11T11:00:00+01:00[Europe/Berlin]", "hours") // 12 — each endpoint's own wall clock
+ * @example spanWallClock("2024-03-10T02:30:00[America/New_York]", "2024-03-11T02:30:00[America/New_York]", "hours") // 24 — a wall time that never occurred is measured as written
+ * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T12:00:00-05:00[America/New_York]", "day") // 1 — singular unit name
+ * @example spanWallClock("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "days") // null — no bracketed time zone
+ * @example spanWallClock("2024-03-01T12:00:00-05:00[America/New_York]", "2024-03-02T12:00:00-05:00[America/New_York]", "minutes") // null
+ */
+export function spanWallClock(start, end, unit) {
+    if (typeof unit !== "string") {
+        return null;
+    }
+    if (!Object.hasOwn(WALL_CLOCK_SPAN_UNITS, unit) ||
+        !isValidZonedDateTime(start) ||
+        !isValidZonedDateTime(end)) {
+        return null;
+    }
+    try {
+        const startWallClock = Temporal.PlainDateTime.from(start);
+        const endWallClock = Temporal.PlainDateTime.from(end);
+        const duration = startWallClock.until(endWallClock, {
+            largestUnit: WALL_CLOCK_SPAN_UNITS[unit],
+        });
+        return WALL_CLOCK_SPAN_UNITS[unit] === "day"
+            ? duration.days
+            : duration.hours;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/span/index.d.ts

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

package/dist/span/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 "./validate/index.js";

package/dist/span/validate/index.d.ts

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

package/dist/span/validate/index.js

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

package/dist/span/validate/isValidSpan.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Validate whether two ISO 8601 instant strings form a measurable span.
+ *
+ * True exactly when `spanMs` and `spanNs` will return a value rather than `null` — the
+ * endpoints both parse, so there is an elapsed time between them.
+ *
+ * - Accepts what `toNanoseconds` does on both sides: an offset designator is required,
+ *   optionally followed by a bracketed IANA zone; no leap seconds. Calendar and elective
+ *   annotations are ignored, as `Temporal.Instant.from` ignores them. The two endpoints need not
+ *   share a zone.
+ * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
+ *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
+ *   with the offset is not checked.
+ * - Order does not matter. A span is signed, not invalid, when `start` is after `end`, so
+ *   this is symmetric.
+ * - **`spanMs` can still return `null` on a pair this accepts** — a span wider than
+ *   `Number.MAX_SAFE_INTEGER` milliseconds has no `number` to return. That is a range
+ *   limit on the result, not a defect in the inputs, and `spanNs` returns the exact
+ *   `bigint` for the same pair.
+ * - Does **not** validate `spanWallClock`, which needs a bracketed IANA zone on both
+ *   endpoints rather than a bare offset — that is `isValidZonedDateTime`.
+ * - Returns `false` for non-strings and empty strings.
+ *
+ * @param start candidate ISO 8601 instant string the span would be measured from
+ * @param end candidate ISO 8601 instant string the span would be measured to
+ * @returns boolean indicating whether spanMs/spanNs will measure this pair
+ *
+ * @example isValidSpan("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z") // true
+ * @example isValidSpan("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // true — a zero span is a span
+ * @example isValidSpan("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // true — spans are signed
+ * @example isValidSpan("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // true
+ * @example isValidSpan("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00Z[Not/AZone]") // true — zone annotations are not checked
+ * @example isValidSpan("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // true — but spanMs returns null, use spanNs
+ * @example isValidSpan("2024-03-10T12:00:00Z", "invalid") // false
+ * @example isValidSpan("2024-03-10T12:00:00[America/New_York]", "2024-03-11T12:00:00[America/New_York]") // false — no offset designator
+ */
+export declare function isValidSpan(start: string, end: string): boolean;

package/dist/span/validate/isValidSpan.js

@@ -0,0 +1,41 @@
+import { parseInstantNanoseconds } from "../../internal/index.js";
+/**
+ * Validate whether two ISO 8601 instant strings form a measurable span.
+ *
+ * True exactly when `spanMs` and `spanNs` will return a value rather than `null` — the
+ * endpoints both parse, so there is an elapsed time between them.
+ *
+ * - Accepts what `toNanoseconds` does on both sides: an offset designator is required,
+ *   optionally followed by a bracketed IANA zone; no leap seconds. Calendar and elective
+ *   annotations are ignored, as `Temporal.Instant.from` ignores them. The two endpoints need not
+ *   share a zone.
+ * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
+ *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
+ *   with the offset is not checked.
+ * - Order does not matter. A span is signed, not invalid, when `start` is after `end`, so
+ *   this is symmetric.
+ * - **`spanMs` can still return `null` on a pair this accepts** — a span wider than
+ *   `Number.MAX_SAFE_INTEGER` milliseconds has no `number` to return. That is a range
+ *   limit on the result, not a defect in the inputs, and `spanNs` returns the exact
+ *   `bigint` for the same pair.
+ * - Does **not** validate `spanWallClock`, which needs a bracketed IANA zone on both
+ *   endpoints rather than a bare offset — that is `isValidZonedDateTime`.
+ * - Returns `false` for non-strings and empty strings.
+ *
+ * @param start candidate ISO 8601 instant string the span would be measured from
+ * @param end candidate ISO 8601 instant string the span would be measured to
+ * @returns boolean indicating whether spanMs/spanNs will measure this pair
+ *
+ * @example isValidSpan("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z") // true
+ * @example isValidSpan("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // true — a zero span is a span
+ * @example isValidSpan("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // true — spans are signed
+ * @example isValidSpan("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // true
+ * @example isValidSpan("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00Z[Not/AZone]") // true — zone annotations are not checked
+ * @example isValidSpan("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // true — but spanMs returns null, use spanNs
+ * @example isValidSpan("2024-03-10T12:00:00Z", "invalid") // false
+ * @example isValidSpan("2024-03-10T12:00:00[America/New_York]", "2024-03-11T12:00:00[America/New_York]") // false — no offset designator
+ */
+export function isValidSpan(start, end) {
+    return (parseInstantNanoseconds(start) !== null &&
+        parseInstantNanoseconds(end) !== 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";