@northguild/gmt 1.14.2 → 1.16.0

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-options.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Core fields shared by all calendar-formatting interfaces.
+ * Each domain variant (plain, unix, utc, zoned) extends this and may
+ * add domain-specific fields like `timeZone` or `epochUnit`.
+ */
+export interface CalendarOptions {
+    /** Anchor point for the relative day comparison. */
+    reference?: string;
+    /** `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half. */
+    timeStyle?: "short" | "medium" | "full";
+}

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/datetime-format-options.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Options accepted by date/time formatting functions that delegate to
+ * `Intl.DateTimeFormat` (via Temporal's `.toLocaleString()` or
+ * `TemporalIntl.DateTimeFormat`).
+ */
+export type DateTimeFormatOptions = Intl.DateTimeFormatOptions;

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

@@ -0,0 +1,5 @@
+/**
+ * Plural unit keys accepted by `formatDuration` for `UNIT_TO_INTL` lookup. Maps to
+ * singular `Intl.NumberFormat` unit labels (e.g. `"years"` → `"year"`).
+ */
+export type DurationUnit = "years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds";

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,5 @@
+export * from "./business-calendar.js";
+export * from "./calendar-options.js";
 export * from "./calendar-system.js";
 export * from "./date-cycle-field.js";
 export * from "./date-duration-unit.js";
@@ -5,14 +7,29 @@ export * from "./date-time-cycle-field.js";
 export * from "./date-time-duration-units.js";
 export * from "./date-time-unit.js";
 export * from "./date-unit.js";
+export * from "./datetime-format-options.js";
 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";
+export * from "./relative-date-time-unit.js";
+export * from "./relative-date-unit.js";
 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,5 @@
+export * from "./business-calendar.js";
+export * from "./calendar-options.js";
 export * from "./calendar-system.js";
 export * from "./date-cycle-field.js";
 export * from "./date-duration-unit.js";
@@ -5,14 +7,28 @@ export * from "./date-time-cycle-field.js";
 export * from "./date-time-duration-units.js";
 export * from "./date-time-unit.js";
 export * from "./date-unit.js";
+export * from "./datetime-format-options.js";
 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";
+export * from "./relative-date-time-unit.js";
+export * from "./relative-date-unit.js";
 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

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

package/dist/types/relative-date-time-unit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Full 7-member `RelativeUnit` for `PlainDateTime`-based formatting. Covers the
+ * complete set of `Intl.RelativeTimeFormat` units supported by Temporal, excluding
+ * `quarter`.
+ */
+export type RelativeDateTimeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";

package/dist/types/relative-date-unit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Narrow `RelativeUnit` for `PlainDate`-based formatting. Excludes `hour`,
+ * `minute`, and `second` because `PlainDate` has no time component.
+ */
+export type RelativeDateUnit = "year" | "month" | "week" | "day";

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

@@ -0,0 +1,18 @@
+import type { RelativeRoundingMethod } from "./relative-rounding-method.js";
+/**
+ * Core fields shared by all relative-time formatting interfaces.
+ * Each domain variant (plain, unix, utc, zoned) extends this and may
+ * restrict `largestUnit` or add domain-specific fields.
+ */
+export interface RelativeTimeFormatOptions {
+    /** Name style: "long" (default), "short", or "narrow". */
+    style?: "long" | "short" | "narrow";
+    /** Whether to use relative time words ("in 2 days") or numeric ("2 days"). */
+    numeric?: "always" | "auto";
+    /** The largest unit to display. Each domain restricts the allowed values. */
+    largestUnit?: string;
+    /** How the computed distance rounds to the display unit. */
+    roundingMethod?: RelativeRoundingMethod;
+    /** Anchor point for the relative diff. */
+    reference?: string;
+}

package/dist/types/relative-time-unit.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Narrow `RelativeUnit` for `PlainTime`-based formatting. Excludes date units
+ * (`year`, `month`, `week`, `day`) because `PlainTime` has no date component.
+ */
+export type RelativeTimeUnit = "hour" | "minute" | "second";

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

@@ -0,0 +1,6 @@
+/**
+ * Canonical 7-member unit for `Intl.RelativeTimeFormat` and Temporal `since`/`until`
+ * totals, excluding `quarter`. Shared by `formatRelativeUnix`, `formatRelativeUtc`,
+ * and `formatRelativeZoned` after importing from this barrel.
+ */
+export type RelativeUnit = "year" | "month" | "week" | "day" | "hour" | "minute" | "second";