@northguild/gmt 1.15.0 → 1.16.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/types/business-calendar.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A jurisdiction's working week: which weekdays are weekend, which dates are holidays, and
+ * which locality the answer is for.
+ *
+ * - `weekend` is ISO weekday numbers, 1 (Monday) through 7 (Sunday). It is explicit because
+ *   Saturday–Sunday is not universal: much of the Middle East is Friday–Saturday (`[5, 6]`),
+ *   and some markets keep a one-day weekend (`[7]`). `[]` means no weekly closure at all.
+ *   Duplicates are ignored; all seven days being weekend leaves no business day and is invalid.
+ * - `holidays` is ISO PlainDate strings (`"2024-07-04"`), never datetimes. Order does not
+ *   matter and duplicates are ignored. GMT bundles no holiday table — holiday data is
+ *   jurisdictional, changes annually and sometimes with days of notice, so the caller supplies
+ *   it. No exchange or currency calendar ships either; an opt-in data subpath for them is
+ *   planned, not published.
+ * - `timeZone` is an IANA identifier recording which locality the calendar describes. The
+ *   business-day functions never read it: they take and return local dates, so the answer is
+ *   the same whatever it says. It is what a caller holding an *instant* needs, to reduce that
+ *   instant to a local date first — with `floorToZone` or `getZonedDateTimeFields` — before
+ *   asking a business-day question.
+ *
+ * Narrow a candidate with `isValidBusinessCalendar`. Compose two jurisdictions' calendars with
+ * `mergeCalendars`.
+ */
+export type BusinessCalendar = {
+    weekend: number[];
+    holidays: string[];
+    timeZone: string;
+};

package/dist/types/calendar-system.d.ts

@@ -1 +1,9 @@
-export type CalendarSystem = "gregorian" | "hebrew" | "islamic-civil" | "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" | "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic";
+/**
+ * A calendar GMT's calendar functions support, named by its canonical calendar id: the CLDR
+ * `common/bcp47/calendar.xml` type that Temporal's `CanonicalizeCalendar` returns, and that
+ * RFC 9557's `[u-ca=<id>]` annotation carries.
+ *
+ * The set is `"iso8601"` plus the rows of the Intl Era and Month Code proposal's
+ * `table-calendar-types` that GMT supports; `"chinese"` and `"dangi"` are not supported.
+ */
+export type CalendarSystem = "iso8601" | "gregory" | "hebrew" | "islamic-civil" | "islamic-tbla" | "islamic-umalqura" | "japanese" | "buddhist" | "roc" | "persian" | "indian" | "ethiopic" | "ethioaa" | "coptic";

package/dist/types/fiscal-calendar.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Week-per-period shape of a 52/53-week fiscal year, one entry per month of a quarter.
+ *
+ * - `"4-5-4"` — the NRF retail calendar, the US retail standard.
+ * - `"4-4-5"` — the longer month falls at the end of the quarter.
+ * - `"5-4-4"` — the longer month falls at the start of the quarter.
+ *
+ * Narrow a candidate — a pattern out of config, an env var or a form — with
+ * `isValidFiscalPattern`.
+ */
+export type FiscalPattern = "4-5-4" | "4-4-5" | "5-4-4";
+/** Caller-supplied 52/53-week fiscal calendar. GMT bundles none. */
+export interface FiscalCalendar {
+    /** Weeks per period within each quarter. */
+    pattern: FiscalPattern;
+    /**
+     * The year-end rule, stated as one ISO date: fiscal years end on this date's **weekday**,
+     * on the occurrence nearest this date's **month and day**. For the NRF retail calendar —
+     * "the Saturday nearest to January 31" — that is `"2026-01-31"`.
+     */
+    yearEndsOn: string;
+}

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./business-calendar.js";
 export * from "./calendar-options.js";
 export * from "./calendar-system.js";
 export * from "./date-cycle-field.js";
@@ -11,7 +12,9 @@ export * from "./disambiguation.js";
 export * from "./duration-relative-to.js";
 export * from "./duration-string-options.js";
 export * from "./duration-unit.js";
+export * from "./fiscal-calendar.js";
 export * from "./fractional-digit.js";
+export * from "./interval.js";
 export * from "./now-unit.js";
 export * from "./offset.js";
 export * from "./overflow.js";
@@ -21,9 +24,12 @@ export * from "./relative-rounding-method.js";
 export * from "./relative-time-options.js";
 export * from "./relative-time-unit.js";
 export * from "./relative-unit.js";
+export * from "./roll-convention.js";
 export * from "./rounding-options.js";
 export * from "./time-cycle-field.js";
 export * from "./time-duration-unit.js";
 export * from "./time-unit.js";
 export * from "./unix-now-unit.js";
 export * from "./utc-now-unit.js";
+export * from "./zone-bucket-unit.js";
+export type { UnixUnit } from "../unix/validate/isValidUnixUnit.js";

package/dist/types/index.js

@@ -1,3 +1,4 @@
+export * from "./business-calendar.js";
 export * from "./calendar-options.js";
 export * from "./calendar-system.js";
 export * from "./date-cycle-field.js";
@@ -11,7 +12,9 @@ export * from "./disambiguation.js";
 export * from "./duration-relative-to.js";
 export * from "./duration-string-options.js";
 export * from "./duration-unit.js";
+export * from "./fiscal-calendar.js";
 export * from "./fractional-digit.js";
+export * from "./interval.js";
 export * from "./now-unit.js";
 export * from "./offset.js";
 export * from "./overflow.js";
@@ -21,9 +24,11 @@ export * from "./relative-rounding-method.js";
 export * from "./relative-time-options.js";
 export * from "./relative-time-unit.js";
 export * from "./relative-unit.js";
+export * from "./roll-convention.js";
 export * from "./rounding-options.js";
 export * from "./time-cycle-field.js";
 export * from "./time-duration-unit.js";
 export * from "./time-unit.js";
 export * from "./unix-now-unit.js";
 export * from "./utc-now-unit.js";
+export * from "./zone-bucket-unit.js";

package/dist/types/interval.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A span of time between two ISO 8601 instant strings, half-open: `[start, end)`.
+ *
+ * - An instant `t` is inside when `start ≤ t < end` (EWD831; SQL:2011 closed-open `PERIOD`;
+ *   RFC 5545 `DTEND` is non-inclusive). Intervals that touch share no instant.
+ * - Both endpoints are instants: an offset (`Z`, `±HH:MM`) is required, a bracketed IANA zone is
+ *   optional, and the two may name different zones. Leap seconds are rejected; a `[u-ca=...]`
+ *   annotation is ignored, as `Temporal.Instant.from` ignores it.
+ * - `start === end` (as instants) is a valid, empty interval: it has a position but contains no
+ *   instant. `start` after `end` is invalid.
+ *
+ * Narrow a candidate with `isValidInterval`. Used by the `interval/` namespace; the older
+ * `plain|utc|zoned|unix/interval` functions take positional strings and a different model.
+ */
+export type Interval = {
+    start: string;
+    end: string;
+};

package/dist/types/now-unit.d.ts

@@ -2,4 +2,4 @@
  * Units extractable from the current system local time via `getNowUnit`.
  * Defined as `DateTimeUnit | "dayOfWeek"`.
  */
-export type NowUnit = import("./date-time-unit.js").DateTimeUnit | "dayOfWeek";
+export type NowUnit = import("@js-temporal/polyfill").Temporal.SmallestUnit<import("./date-time-unit.js").DateTimeUnit> | "dayOfWeek";

package/dist/types/roll-convention.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What `rollDate` does when a date lands on a non-business day.
+ *
+ * Every industry has an answer and they differ, so the convention is always explicit.
+ *
+ * No TC39, ECMA or RFC standard governs these, so each cites the domain text that does.
+ * `"following"`, `"modifiedFollowing"` and `"preceding"` are the three conventions
+ * [ISDA 2006 Definitions §4.12(a)](https://www.isda.org/a/smMDE/Blackline-2000-v-2006-ISDA-Definitions.pdf) defines, in (i), (ii)
+ * and (iii): "if 'Following' is specified …", "if 'Modified Following' or 'Modified' is
+ * specified …" and "if 'Preceding' is specified, that date will be the first preceding day
+ * that is a Business Day". §4.12(a) defines no Modified Preceding: `"modifiedPreceding"` is
+ * FpML's `BusinessDayConventionEnum` `MODPRECEDING`, "adjusted to the first preceding day
+ * that is a business day unless that day falls in the previous calendar month, in which
+ * case … the first following day". `"none"` is what
+ * [OpenGamma Strata](https://strata.opengamma.io/apidocs/com/opengamma/strata/basics/date/BusinessDayConventions.html)
+ * calls `NO_ADJUST`.
+ *
+ * - `"following"` — forward to the next business day, or the date itself if it is one.
+ * - `"modifiedFollowing"` — forward, unless that crosses into the next month, then backward.
+ * - `"preceding"` — backward to the previous business day, or the date itself if it is one.
+ * - `"modifiedPreceding"` — backward, unless that crosses into the previous month, then forward.
+ * - `"endOfMonth"` — the last business day of the date's own month, wherever in the month the
+ *   date falls; it leaves the month only if that whole month is closed. **GMT's own, not
+ *   ISDA's**, and not the industry "EOM rule" — that is a *schedule* rule, holding every date
+ *   in a schedule to its month's last day once the anchor is one. Build that rule from this
+ *   one by testing the anchor for month-end yourself and applying `"endOfMonth"` to the
+ *   unadjusted target date.
+ * - `"none"` — return the date unadjusted, business day or not.
+ *
+ * Narrow a candidate with `isValidRollConvention`.
+ */
+export type RollConvention = "following" | "modifiedFollowing" | "preceding" | "modifiedPreceding" | "endOfMonth" | "none";

package/dist/types/utc-now-unit.d.ts

@@ -2,4 +2,4 @@
  * Units extractable from the current UTC instant via `getUtcNowUnit`.
  * Defined as `DateTimeUnit | "dayOfWeek"`.
  */
-export type UtcNowUnit = import("./date-time-unit.js").DateTimeUnit | "dayOfWeek";
+export type UtcNowUnit = import("@js-temporal/polyfill").Temporal.SmallestUnit<import("./date-time-unit.js").DateTimeUnit> | "dayOfWeek";

package/dist/types/zone-bucket-unit.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Units `floorToZone` and `bucketRange` floor an instant to, in a target time zone.
+ *
+ * Narrower than `DateTimeUnit` on purpose: these are the boundaries a calendar in a zone
+ * actually has. Sub-hour units need no zone (a minute boundary is the same instant
+ * everywhere a zone's offset is a whole minute), and `year` is left out because the fiscal
+ * and calendar year questions are `getFiscalPeriod`'s and `getQuarter`'s.
+ *
+ * Narrow a candidate unit with `isValidZoneBucketUnit`.
+ */
+export type ZoneBucketUnit = "hour" | "day" | "week" | "month";