@northguild/gmt 1.15.0 → 1.17.0

package/dist/internal/halfOpenIntervals.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Half-open `[start, end)` interval algebra over any totally ordered value type.
+ *
+ * `t ∈ [start, end) ⇔ start ≤ t < end` — EWD831, SQL:2011 closed-open `PERIOD`
+ * (ISO/IEC 9075-2:2011) and RFC 5545 §3.6.1 non-inclusive `DTEND`. These helpers carry the same
+ * rules as the CORE-6 `interval/` namespace (see `context/domination/specs/CORE-6-spec.md` §3)
+ * for the positional families whose values are not instants (`PlainDate`, `PlainDateTime`,
+ * `PlainTime`) and for the relations `interval/` has no function for.
+ *
+ * - `compare` returns a negative, zero or positive number, like `Temporal.*.compare`.
+ * - Callers validate first: every span passed in has `start ≤ end`.
+ * - No helper ever steps a value by one unit, so nothing can overflow a type's range or wrap a
+ *   `PlainTime` past midnight.
+ * - Every returned span is a fresh object holding values from the inputs.
+ */
+type Compare<T> = (left: T, right: T) => number;
+/** A validated `[start, end)` span of one value type. */
+export interface HalfOpenSpan<T> {
+    start: T;
+    end: T;
+}
+/**
+ * True when the spans share at least one value: `a.start < b.end && b.start < a.end`.
+ * Touching spans do not overlap, and an empty span overlaps only when strictly inside the other.
+ *
+ * @example halfOpenOverlap({ start: 1, end: 5 }, { start: 3, end: 8 }, (x, y) => x - y) // true
+ * @example halfOpenOverlap({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // false (touching)
+ */
+export declare function halfOpenOverlap<T>(a: HalfOpenSpan<T>, b: HalfOpenSpan<T>, compare: Compare<T>): boolean;
+/**
+ * True when `start ≤ point < end`. An empty span contains no value.
+ *
+ * @example halfOpenContainsPoint({ start: 1, end: 5 }, 1, (x, y) => x - y) // true
+ * @example halfOpenContainsPoint({ start: 1, end: 5 }, 5, (x, y) => x - y) // false (end is excluded)
+ */
+export declare function halfOpenContainsPoint<T>(span: HalfOpenSpan<T>, point: T, compare: Compare<T>): boolean;
+/**
+ * True when `inner` lies within `outer` and the two overlap. For a non-empty `inner` this is
+ * `outer.start ≤ inner.start && inner.end ≤ outer.end`; an empty `inner` counts only strictly
+ * inside `outer`, matching CORE-6's `clampInterval`, which clamps an empty interval at an edge to
+ * `null` and one strictly inside to itself.
+ *
+ * @example halfOpenContainsSpan({ start: 1, end: 9 }, { start: 3, end: 9 }, (x, y) => x - y) // true
+ * @example halfOpenContainsSpan({ start: 1, end: 9 }, { start: 9, end: 9 }, (x, y) => x - y) // false (empty at the edge)
+ */
+export declare function halfOpenContainsSpan<T>(outer: HalfOpenSpan<T>, inner: HalfOpenSpan<T>, compare: Compare<T>): boolean;
+/**
+ * The shared span `[max(starts), min(ends))`, or `null` when the spans do not overlap.
+ * `halfOpenIntersection(a, b) !== null ⇔ halfOpenOverlap(a, b)` by construction.
+ *
+ * @example halfOpenIntersection({ start: 1, end: 5 }, { start: 3, end: 8 }, (x, y) => x - y) // { start: 3, end: 5 }
+ * @example halfOpenIntersection({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // null (touching)
+ */
+export declare function halfOpenIntersection<T>(a: HalfOpenSpan<T>, b: HalfOpenSpan<T>, compare: Compare<T>): HalfOpenSpan<T> | null;
+/**
+ * Coalesce spans into sorted, disjoint, non-touching, non-empty runs (CORE-6
+ * `coalesceIntervalNanoseconds`): touching spans join, an empty span touching or inside a run is
+ * absorbed, and an empty span nothing touches is dropped.
+ *
+ * @example halfOpenMerge([{ start: 3, end: 8 }, { start: 1, end: 3 }], (x, y) => x - y) // [{ start: 1, end: 8 }]
+ * @example halfOpenMerge([{ start: 5, end: 5 }], (x, y) => x - y) // []
+ */
+export declare function halfOpenMerge<T>(spans: ReadonlyArray<HalfOpenSpan<T>>, compare: Compare<T>): Array<HalfOpenSpan<T>>;
+/**
+ * The union of two spans when it is one non-empty span, otherwise `null` — the single run of
+ * `halfOpenMerge([a, b])`. Touching spans join; spans with a gap, and two empty spans, give `null`.
+ *
+ * @example halfOpenUnion({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // { start: 1, end: 5 }
+ * @example halfOpenUnion({ start: 1, end: 3 }, { start: 4, end: 5 }, (x, y) => x - y) // null (gap)
+ */
+export declare function halfOpenUnion<T>(a: HalfOpenSpan<T>, b: HalfOpenSpan<T>, compare: Compare<T>): HalfOpenSpan<T> | null;
+/**
+ * The parts of `from` not covered by any span in `remove`, sorted and non-empty (CORE-6
+ * `subtractIntervals`). Pieces end exactly where a removal starts and start exactly where one
+ * ends.
+ *
+ * @example halfOpenDifference({ start: 1, end: 9 }, [{ start: 3, end: 5 }], (x, y) => x - y) // [{ start: 1, end: 3 }, { start: 5, end: 9 }]
+ * @example halfOpenDifference({ start: 1, end: 9 }, [{ start: 1, end: 9 }], (x, y) => x - y) // []
+ */
+export declare function halfOpenDifference<T>(from: HalfOpenSpan<T>, remove: ReadonlyArray<HalfOpenSpan<T>>, compare: Compare<T>): Array<HalfOpenSpan<T>>;
+/**
+ * The symmetric difference of any number of spans: every maximal run of values covered an odd
+ * number of times, sorted by start.
+ *
+ * Every start and end is a boundary. At each distinct boundary value the coverage parity flips
+ * when the number of starts plus ends there is odd. A span's own start and end cancel when it is
+ * empty, and one span ending where another starts leaves the parity unchanged, so touching odd
+ * runs come out as one maximal run.
+ *
+ * @example halfOpenXor([{ start: 1, end: 5 }, { start: 3, end: 8 }], (x, y) => x - y) // [{ start: 1, end: 3 }, { start: 5, end: 8 }]
+ * @example halfOpenXor([{ start: 1, end: 3 }, { start: 3, end: 5 }], (x, y) => x - y) // [{ start: 1, end: 5 }]
+ */
+export declare function halfOpenXor<T>(spans: ReadonlyArray<HalfOpenSpan<T>>, compare: Compare<T>): Array<HalfOpenSpan<T>>;
+/**
+ * True when one non-empty span ends exactly where the other non-empty span starts — they share
+ * no value and leave no gap (Allen's "meets", in either order). An empty span abuts nothing.
+ *
+ * @example halfOpenAbuts({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // true
+ * @example halfOpenAbuts({ start: 1, end: 3 }, { start: 4, end: 5 }, (x, y) => x - y) // false (gap)
+ */
+export declare function halfOpenAbuts<T>(a: HalfOpenSpan<T>, b: HalfOpenSpan<T>, compare: Compare<T>): boolean;
+export {};

package/dist/internal/halfOpenIntervals.js

@@ -0,0 +1,180 @@
+/**
+ * Half-open `[start, end)` interval algebra over any totally ordered value type.
+ *
+ * `t ∈ [start, end) ⇔ start ≤ t < end` — EWD831, SQL:2011 closed-open `PERIOD`
+ * (ISO/IEC 9075-2:2011) and RFC 5545 §3.6.1 non-inclusive `DTEND`. These helpers carry the same
+ * rules as the CORE-6 `interval/` namespace (see `context/domination/specs/CORE-6-spec.md` §3)
+ * for the positional families whose values are not instants (`PlainDate`, `PlainDateTime`,
+ * `PlainTime`) and for the relations `interval/` has no function for.
+ *
+ * - `compare` returns a negative, zero or positive number, like `Temporal.*.compare`.
+ * - Callers validate first: every span passed in has `start ≤ end`.
+ * - No helper ever steps a value by one unit, so nothing can overflow a type's range or wrap a
+ *   `PlainTime` past midnight.
+ * - Every returned span is a fresh object holding values from the inputs.
+ */
+/**
+ * True when the spans share at least one value: `a.start < b.end && b.start < a.end`.
+ * Touching spans do not overlap, and an empty span overlaps only when strictly inside the other.
+ *
+ * @example halfOpenOverlap({ start: 1, end: 5 }, { start: 3, end: 8 }, (x, y) => x - y) // true
+ * @example halfOpenOverlap({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // false (touching)
+ */
+export function halfOpenOverlap(a, b, compare) {
+    return compare(a.start, b.end) < 0 && compare(b.start, a.end) < 0;
+}
+/**
+ * True when `start ≤ point < end`. An empty span contains no value.
+ *
+ * @example halfOpenContainsPoint({ start: 1, end: 5 }, 1, (x, y) => x - y) // true
+ * @example halfOpenContainsPoint({ start: 1, end: 5 }, 5, (x, y) => x - y) // false (end is excluded)
+ */
+export function halfOpenContainsPoint(span, point, compare) {
+    return compare(span.start, point) <= 0 && compare(point, span.end) < 0;
+}
+/**
+ * True when `inner` lies within `outer` and the two overlap. For a non-empty `inner` this is
+ * `outer.start ≤ inner.start && inner.end ≤ outer.end`; an empty `inner` counts only strictly
+ * inside `outer`, matching CORE-6's `clampInterval`, which clamps an empty interval at an edge to
+ * `null` and one strictly inside to itself.
+ *
+ * @example halfOpenContainsSpan({ start: 1, end: 9 }, { start: 3, end: 9 }, (x, y) => x - y) // true
+ * @example halfOpenContainsSpan({ start: 1, end: 9 }, { start: 9, end: 9 }, (x, y) => x - y) // false (empty at the edge)
+ */
+export function halfOpenContainsSpan(outer, inner, compare) {
+    return (halfOpenOverlap(outer, inner, compare) &&
+        compare(outer.start, inner.start) <= 0 &&
+        compare(inner.end, outer.end) <= 0);
+}
+/**
+ * The shared span `[max(starts), min(ends))`, or `null` when the spans do not overlap.
+ * `halfOpenIntersection(a, b) !== null ⇔ halfOpenOverlap(a, b)` by construction.
+ *
+ * @example halfOpenIntersection({ start: 1, end: 5 }, { start: 3, end: 8 }, (x, y) => x - y) // { start: 3, end: 5 }
+ * @example halfOpenIntersection({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // null (touching)
+ */
+export function halfOpenIntersection(a, b, compare) {
+    if (!halfOpenOverlap(a, b, compare)) {
+        return null;
+    }
+    return {
+        start: compare(a.start, b.start) >= 0 ? a.start : b.start,
+        end: compare(a.end, b.end) <= 0 ? a.end : b.end,
+    };
+}
+/**
+ * Coalesce spans into sorted, disjoint, non-touching, non-empty runs (CORE-6
+ * `coalesceIntervalNanoseconds`): touching spans join, an empty span touching or inside a run is
+ * absorbed, and an empty span nothing touches is dropped.
+ *
+ * @example halfOpenMerge([{ start: 3, end: 8 }, { start: 1, end: 3 }], (x, y) => x - y) // [{ start: 1, end: 8 }]
+ * @example halfOpenMerge([{ start: 5, end: 5 }], (x, y) => x - y) // []
+ */
+export function halfOpenMerge(spans, compare) {
+    const sorted = [...spans].sort((left, right) => compare(left.start, right.start));
+    const runs = [];
+    for (const span of sorted) {
+        const last = runs[runs.length - 1];
+        if (last !== undefined && compare(span.start, last.end) <= 0) {
+            if (compare(span.end, last.end) > 0) {
+                last.end = span.end;
+            }
+        }
+        else {
+            runs.push({ start: span.start, end: span.end });
+        }
+    }
+    return runs.filter((run) => compare(run.start, run.end) < 0);
+}
+/**
+ * The union of two spans when it is one non-empty span, otherwise `null` — the single run of
+ * `halfOpenMerge([a, b])`. Touching spans join; spans with a gap, and two empty spans, give `null`.
+ *
+ * @example halfOpenUnion({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // { start: 1, end: 5 }
+ * @example halfOpenUnion({ start: 1, end: 3 }, { start: 4, end: 5 }, (x, y) => x - y) // null (gap)
+ */
+export function halfOpenUnion(a, b, compare) {
+    const runs = halfOpenMerge([a, b], compare);
+    return runs.length === 1 ? runs[0] : null;
+}
+/**
+ * The parts of `from` not covered by any span in `remove`, sorted and non-empty (CORE-6
+ * `subtractIntervals`). Pieces end exactly where a removal starts and start exactly where one
+ * ends.
+ *
+ * @example halfOpenDifference({ start: 1, end: 9 }, [{ start: 3, end: 5 }], (x, y) => x - y) // [{ start: 1, end: 3 }, { start: 5, end: 9 }]
+ * @example halfOpenDifference({ start: 1, end: 9 }, [{ start: 1, end: 9 }], (x, y) => x - y) // []
+ */
+export function halfOpenDifference(from, remove, compare) {
+    const pieces = [];
+    let cursor = from.start;
+    for (const run of halfOpenMerge(remove, compare)) {
+        if (compare(run.start, from.end) >= 0) {
+            break;
+        }
+        if (compare(run.end, cursor) <= 0) {
+            continue;
+        }
+        if (compare(run.start, cursor) > 0) {
+            pieces.push({ start: cursor, end: run.start });
+        }
+        cursor = run.end;
+    }
+    if (compare(cursor, from.end) < 0) {
+        pieces.push({ start: cursor, end: from.end });
+    }
+    return pieces;
+}
+/**
+ * The symmetric difference of any number of spans: every maximal run of values covered an odd
+ * number of times, sorted by start.
+ *
+ * Every start and end is a boundary. At each distinct boundary value the coverage parity flips
+ * when the number of starts plus ends there is odd. A span's own start and end cancel when it is
+ * empty, and one span ending where another starts leaves the parity unchanged, so touching odd
+ * runs come out as one maximal run.
+ *
+ * @example halfOpenXor([{ start: 1, end: 5 }, { start: 3, end: 8 }], (x, y) => x - y) // [{ start: 1, end: 3 }, { start: 5, end: 8 }]
+ * @example halfOpenXor([{ start: 1, end: 3 }, { start: 3, end: 5 }], (x, y) => x - y) // [{ start: 1, end: 5 }]
+ */
+export function halfOpenXor(spans, compare) {
+    const boundaries = spans
+        .flatMap((span) => [span.start, span.end])
+        .sort(compare);
+    const result = [];
+    let runStart = null;
+    let index = 0;
+    while (index < boundaries.length) {
+        const point = boundaries[index];
+        let count = 0;
+        while (index < boundaries.length &&
+            compare(boundaries[index], point) === 0) {
+            count += 1;
+            index += 1;
+        }
+        if (count % 2 === 0) {
+            continue;
+        }
+        if (runStart === null) {
+            runStart = point;
+        }
+        else {
+            result.push({ start: runStart, end: point });
+            runStart = null;
+        }
+    }
+    return result;
+}
+/**
+ * True when one non-empty span ends exactly where the other non-empty span starts — they share
+ * no value and leave no gap (Allen's "meets", in either order). An empty span abuts nothing.
+ *
+ * @example halfOpenAbuts({ start: 1, end: 3 }, { start: 3, end: 5 }, (x, y) => x - y) // true
+ * @example halfOpenAbuts({ start: 1, end: 3 }, { start: 4, end: 5 }, (x, y) => x - y) // false (gap)
+ */
+export function halfOpenAbuts(a, b, compare) {
+    if (compare(a.start, a.end) === 0 || compare(b.start, b.end) === 0) {
+        return false;
+    }
+    return compare(a.end, b.start) === 0 || compare(b.end, a.start) === 0;
+}

package/dist/internal/hasCalendarAnnotation.d.ts

@@ -1,27 +1,27 @@
 /**
- * Return true when `value` carries a `[u-ca=...]` calendar annotation — either GMT's own
- * native-digit shape or Temporal's own ISO-digit RFC 9557 shape.
+ * Return true when `value` carries a `[u-ca=...]` calendar annotation, in any position.
  *
- * The implementation has not changed since E5; its *meaning* has, because `zoned/` is no longer
- * uniform. Current usage, after E7 (issue #152):
+ * RFC 9557 lets any suffix annotation carry a critical flag (§3.3; `critical-flag` in the §4.1
+ * ABNF), and Temporal honours it for the calendar key:
+ * `Temporal.ZonedDateTime.from("5784-01-01T14:30:00-05:00[America/New_York][!u-ca=hebrew]")`
+ * succeeds in the Hebrew calendar, reading ISO year 5784 as Hebrew year 9544. The flag only makes
+ * the annotation harder to ignore, so `[!u-ca=...]` is detected exactly like `[u-ca=...]`. A
+ * critical time-zone annotation (`[!America/New_York]`) carries no key and does not match.
+ * Temporal rejects an upper-case `[U-CA=` key outright, so it needs no special case.
  *
- * - **`utc/`** (already regex-gated to a strict `<date>T<time>Z` shape) and **`unix/`** (numeric
- *   input, structurally immune) reject every annotation, exactly as they always have.
- * - **`isValidZonedDateTime`** still rejects every annotation, and the ~72 `zoned/` functions
- *   gated on it therefore still do too. That gate is deliberately left alone: loosening it would
- *   make `isValidZonedDateTime(x) === true` while e.g. `getZonedYear(x) === null`, i.e. a
- *   validator certifying strings its own namespace refuses.
- * - **The ~18 calendar-aware `zoned/` functions** added by E7 gate on the parallel
- *   `isValidCalendarZonedDateTime`/`isValidCalendarZonedInterval` instead, which ACCEPT GMT's
- *   `<date>T<time><offset>[u-ca=...][timeZone]` grammar and reject only Temporal's own segment
- *   ordering. Those paths use `internal/calendarValueOfZoned.ts` and
- *   `internal/calendarZonedString.ts`, not this predicate.
- * - **`plain/`** `PlainDate` functions accept GMT's annotated shape via `isValidCalendarDate`
- *   (E5's D1); `plain/` `PlainDateTime`/`PlainTime` functions have no annotated grammar of their
- *   own and treat one as invalid input.
+ * Since CORE-8 (#22) the non-calendar validators no longer use it: `isValidDate`,
+ * `isValidDateTime`, `isValidZonedDateTime` and `isValidZonedRange` read the calendar Temporal
+ * reads (`calendarId === "iso8601"`), and instants ignore the annotation as `Temporal.Instant.from`
+ * does. It remains a routing test: does a string name a calendar at all?
  *
  * So this predicate answers exactly one question — "does this string carry an annotation at all?"
- * — and says nothing about whether the caller should accept it. Reach for it only where the
- * answer is "reject unconditionally".
+ * — and says nothing about whether the caller should accept it.
+ *
+ * @param value candidate ISO 8601 string
+ * @returns true when a calendar annotation is present, critical or not
+ *
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00Z[u-ca=hebrew]") // true
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00Z[!u-ca=hebrew]") // true (critical flag)
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00-05:00[!America/New_York]") // false (a zone, not a calendar)
  */
 export declare function hasCalendarAnnotation(value: string): boolean;

package/dist/internal/hasCalendarAnnotation.js

@@ -1,29 +1,31 @@
+/** A `[u-ca=` calendar annotation, with or without RFC 9557's critical flag (`[!u-ca=`). */
+const calendarAnnotation = /\[!?u-ca=/;
 /**
- * Return true when `value` carries a `[u-ca=...]` calendar annotation — either GMT's own
- * native-digit shape or Temporal's own ISO-digit RFC 9557 shape.
+ * Return true when `value` carries a `[u-ca=...]` calendar annotation, in any position.
  *
- * The implementation has not changed since E5; its *meaning* has, because `zoned/` is no longer
- * uniform. Current usage, after E7 (issue #152):
+ * RFC 9557 lets any suffix annotation carry a critical flag (§3.3; `critical-flag` in the §4.1
+ * ABNF), and Temporal honours it for the calendar key:
+ * `Temporal.ZonedDateTime.from("5784-01-01T14:30:00-05:00[America/New_York][!u-ca=hebrew]")`
+ * succeeds in the Hebrew calendar, reading ISO year 5784 as Hebrew year 9544. The flag only makes
+ * the annotation harder to ignore, so `[!u-ca=...]` is detected exactly like `[u-ca=...]`. A
+ * critical time-zone annotation (`[!America/New_York]`) carries no key and does not match.
+ * Temporal rejects an upper-case `[U-CA=` key outright, so it needs no special case.
  *
- * - **`utc/`** (already regex-gated to a strict `<date>T<time>Z` shape) and **`unix/`** (numeric
- *   input, structurally immune) reject every annotation, exactly as they always have.
- * - **`isValidZonedDateTime`** still rejects every annotation, and the ~72 `zoned/` functions
- *   gated on it therefore still do too. That gate is deliberately left alone: loosening it would
- *   make `isValidZonedDateTime(x) === true` while e.g. `getZonedYear(x) === null`, i.e. a
- *   validator certifying strings its own namespace refuses.
- * - **The ~18 calendar-aware `zoned/` functions** added by E7 gate on the parallel
- *   `isValidCalendarZonedDateTime`/`isValidCalendarZonedInterval` instead, which ACCEPT GMT's
- *   `<date>T<time><offset>[u-ca=...][timeZone]` grammar and reject only Temporal's own segment
- *   ordering. Those paths use `internal/calendarValueOfZoned.ts` and
- *   `internal/calendarZonedString.ts`, not this predicate.
- * - **`plain/`** `PlainDate` functions accept GMT's annotated shape via `isValidCalendarDate`
- *   (E5's D1); `plain/` `PlainDateTime`/`PlainTime` functions have no annotated grammar of their
- *   own and treat one as invalid input.
+ * Since CORE-8 (#22) the non-calendar validators no longer use it: `isValidDate`,
+ * `isValidDateTime`, `isValidZonedDateTime` and `isValidZonedRange` read the calendar Temporal
+ * reads (`calendarId === "iso8601"`), and instants ignore the annotation as `Temporal.Instant.from`
+ * does. It remains a routing test: does a string name a calendar at all?
  *
  * So this predicate answers exactly one question — "does this string carry an annotation at all?"
- * — and says nothing about whether the caller should accept it. Reach for it only where the
- * answer is "reject unconditionally".
+ * — and says nothing about whether the caller should accept it.
+ *
+ * @param value candidate ISO 8601 string
+ * @returns true when a calendar annotation is present, critical or not
+ *
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00Z[u-ca=hebrew]") // true
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00Z[!u-ca=hebrew]") // true (critical flag)
+ * @example hasCalendarAnnotation("2024-02-10T12:00:00-05:00[!America/New_York]") // false (a zone, not a calendar)
  */
 export function hasCalendarAnnotation(value) {
-    return typeof value === "string" && value.includes("[u-ca=");
+    return typeof value === "string" && calendarAnnotation.test(value);
 }

package/dist/internal/hourDurationString.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Format a non-negative count of nanoseconds as an ISO 8601 duration with hours as the largest
+ * unit — the string `Temporal.Instant.prototype.until(…, { largestUnit: "hour" }).toString()`
+ * produces for a span of that length. Returns "" for a negative count or if Temporal throws.
+ *
+ * - Splits with bigint division, so it stays exact past 2^53 ns and across the full Instant
+ *   span (1.728 × 10^22 ns = 4 800 000 000 h, which `Number` holds exactly).
+ *
+ * @param nanoseconds non-negative elapsed nanoseconds
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example formatHourDuration(0n) // "PT0S"
+ * @example formatHourDuration(178200000000001n) // "PT49H30M0.000000001S"
+ * @example formatHourDuration(-1n) // ""
+ */
+export declare function formatHourDuration(nanoseconds: bigint): string;

package/dist/internal/hourDurationString.js

@@ -0,0 +1,47 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, } from "./foreignEpochs.js";
+const NANOSECONDS_PER_HOUR = 3600000000000n;
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+/**
+ * Format a non-negative count of nanoseconds as an ISO 8601 duration with hours as the largest
+ * unit — the string `Temporal.Instant.prototype.until(…, { largestUnit: "hour" }).toString()`
+ * produces for a span of that length. Returns "" for a negative count or if Temporal throws.
+ *
+ * - Splits with bigint division, so it stays exact past 2^53 ns and across the full Instant
+ *   span (1.728 × 10^22 ns = 4 800 000 000 h, which `Number` holds exactly).
+ *
+ * @param nanoseconds non-negative elapsed nanoseconds
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example formatHourDuration(0n) // "PT0S"
+ * @example formatHourDuration(178200000000001n) // "PT49H30M0.000000001S"
+ * @example formatHourDuration(-1n) // ""
+ */
+export function formatHourDuration(nanoseconds) {
+    if (nanoseconds < 0n) {
+        return "";
+    }
+    const hours = nanoseconds / NANOSECONDS_PER_HOUR;
+    const afterHours = nanoseconds % NANOSECONDS_PER_HOUR;
+    const minutes = afterHours / NANOSECONDS_PER_MINUTE;
+    const afterMinutes = afterHours % NANOSECONDS_PER_MINUTE;
+    const seconds = afterMinutes / NANOSECONDS_PER_SECOND;
+    const afterSeconds = afterMinutes % NANOSECONDS_PER_SECOND;
+    const milliseconds = afterSeconds / NANOSECONDS_PER_MILLISECOND;
+    const afterMilliseconds = afterSeconds % NANOSECONDS_PER_MILLISECOND;
+    const microseconds = afterMilliseconds / NANOSECONDS_PER_MICROSECOND;
+    const remainder = afterMilliseconds % NANOSECONDS_PER_MICROSECOND;
+    try {
+        return Temporal.Duration.from({
+            hours: Number(hours),
+            minutes: Number(minutes),
+            seconds: Number(seconds),
+            milliseconds: Number(milliseconds),
+            microseconds: Number(microseconds),
+            nanoseconds: Number(remainder),
+        }).toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/internal/httpDateFields.d.ts

@@ -0,0 +1,24 @@
+/** Date-time fields read from an RFC 9110 HTTP-date, before calendar validation. */
+export interface HttpDateFields {
+    /** ISO day of week 1 (Monday) – 7 (Sunday). */
+    dayOfWeek: number;
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+}
+/**
+ * Read the fields of an RFC 9110 obsolete HTTP-date: `rfc850-date` or
+ * `asctime-date`. IMF-fixdate is read with the exported `httpDate` pattern.
+ *
+ * - Shape checks only: the calendar date and the day of week are left to the
+ *   caller (`Temporal.PlainDateTime.from` with `overflow: "reject"`).
+ * - An `rfc850-date` reads the clock (`Temporal.Now.instant`) to place its
+ *   two-digit year; that call throws if the clock cannot be read.
+ *
+ * @param value candidate obsolete HTTP-date
+ * @returns the fields, or `null` when `value` is neither obsolete format
+ */
+export declare function readObsoleteHttpDate(value: string): HttpDateFields | null;

package/dist/internal/httpDateFields.js

@@ -0,0 +1,86 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES, } from "./englishCalendarNames.js";
+// RFC 9110 §5.6.7 obsolete formats. HTTP-date is case-sensitive (%s strings).
+//   rfc850-date  = day-name-l "," SP date2 SP time-of-day SP GMT
+//   date2        = day "-" month "-" 2DIGIT
+// Capture groups: 1 day-name-l, 2 day, 3 month, 4 year, 5 hour, 6 minute, 7 second.
+const RFC850_DATE = /^(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\d{2})-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+//   asctime-date = day-name SP date3 SP time-of-day SP year
+//   date3        = month SP ( 2DIGIT / ( SP 1DIGIT ))
+// Capture groups: 1 day-name, 2 month, 3 day, 4 hour, 5 minute, 6 second, 7 year.
+const ASCTIME_DATE = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{2}| \d) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/;
+const LONG_WEEKDAY_NAMES = [
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+    "Sunday",
+];
+function monthNumber(name) {
+    return (ENGLISH_MONTH_NAMES.indexOf(name) +
+        1);
+}
+// "Recipients of a timestamp value in rfc850-date format, which uses a
+// two-digit year, MUST interpret a timestamp that appears to be more than 50
+// years in the future as representing the most recent year in the past that
+// had the same last two digits." The year chosen is the latest one ending in
+// those digits whose timestamp is not more than 50 years after now.
+function resolveTwoDigitYear(twoDigits, fields) {
+    const limit = Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .add({ years: 50 })
+        .toPlainDateTime();
+    const isBeyondLimit = (year) => Temporal.PlainDateTime.compare({ ...fields, year }, limit) > 0;
+    let year = Math.floor(limit.year / 100) * 100 + twoDigits;
+    while (isBeyondLimit(year))
+        year -= 100;
+    while (!isBeyondLimit(year + 100))
+        year += 100;
+    return year;
+}
+/**
+ * Read the fields of an RFC 9110 obsolete HTTP-date: `rfc850-date` or
+ * `asctime-date`. IMF-fixdate is read with the exported `httpDate` pattern.
+ *
+ * - Shape checks only: the calendar date and the day of week are left to the
+ *   caller (`Temporal.PlainDateTime.from` with `overflow: "reject"`).
+ * - An `rfc850-date` reads the clock (`Temporal.Now.instant`) to place its
+ *   two-digit year; that call throws if the clock cannot be read.
+ *
+ * @param value candidate obsolete HTTP-date
+ * @returns the fields, or `null` when `value` is neither obsolete format
+ */
+export function readObsoleteHttpDate(value) {
+    const rfc850 = RFC850_DATE.exec(value);
+    if (rfc850 !== null) {
+        const [, dayName, day, month, year, hour, minute, second] = rfc850;
+        const fields = {
+            month: monthNumber(month),
+            day: Number(day),
+            hour: Number(hour),
+            minute: Number(minute),
+            second: Number(second),
+        };
+        return {
+            ...fields,
+            dayOfWeek: LONG_WEEKDAY_NAMES.indexOf(dayName) + 1,
+            year: resolveTwoDigitYear(Number(year), fields),
+        };
+    }
+    const asctime = ASCTIME_DATE.exec(value);
+    if (asctime !== null) {
+        const [, dayName, month, day, hour, minute, second, year] = asctime;
+        return {
+            dayOfWeek: ENGLISH_WEEKDAY_NAMES.indexOf(dayName) + 1,
+            year: Number(year),
+            month: monthNumber(month),
+            day: Number(day),
+            hour: Number(hour),
+            minute: Number(minute),
+            second: Number(second),
+        };
+    }
+    return null;
+}

package/dist/internal/index.d.ts

@@ -1,34 +1,55 @@
-export { advanceBusinessDays } from "./advanceBusinessDays.js";
-export { adjustZonedBusinessDays } from "./adjustZonedBusinessDays.js";
 export { advanceToWeekday } from "./advanceToWeekday.js";
-export { calendarDateParts, type CalendarDateStringParts, formatCalendarDate, parseCalendarDateValue, } from "./calendarDateString.js";
-export { isCalendarSystem, temporalCalendarIds } from "./calendarSystemIds.js";
+export { parseCalendarDateValue } from "./calendarDateString.js";
+export { canonicalCalendarSystem, isCalendarSystem } from "./calendarSystemIds.js";
 export { parseCalendarDatePairForArithmetic } from "./calendarDatePairPolicy.js";
 export { parseCalendarZonedPairForArithmetic } from "./calendarZonedPairPolicy.js";
 export { calendarOfAllDateValues, calendarSystemOfDateValue, } from "./calendarValueOfDate.js";
 export { calendarOfAllZonedValues, calendarSystemOfZonedValue, } from "./calendarValueOfZoned.js";
 export { formatZonedInCalendar, parseCalendarZonedValue, } from "./calendarZonedString.js";
 export { cycleFieldValue } from "./cycleFieldValue.js";
+export { fiscalPeriodOfWeek, fiscalYearOf } from "./fiscalCalendar.js";
+export { floorDivide } from "./floorDivide.js";
+export { DOT_NET_TICKS_EPOCH_OFFSET, EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PHANTOM_END_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, EXCEL_PHANTOM_SERIAL, FILE_TIME_EPOCH_OFFSET_TICKS, MAX_DOT_NET_TICKS, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MAX_FILE_TIME, MILLISECONDS_PER_DAY, MIN_DOT_NET_TICKS, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, MIN_FILE_TIME, MIN_PG_MICROSECONDS, NANOSECONDS_PER_DAY, NANOSECONDS_PER_DAY_NUMBER, NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, NANOSECONDS_PER_TICK, NTP_EPOCH_OFFSET_NANOSECONDS, NTP_ERA_UNITS, NTP_UNITS_PER_SECOND, PG_EPOCH_OFFSET_MICROSECONDS, } from "./foreignEpochs.js";
+export { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "./epochNanoseconds.js";
 export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.js";
-export { calendarDateStringParts, formatDateInCalendar, } from "./formatDateInCalendar.js";
-export { hasCalendarAnnotation } from "./hasCalendarAnnotation.js";
+export { formatDateInCalendar } from "./formatDateInCalendar.js";
+export { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "./freeTimeLedger.js";
+export { halfOpenAbuts, halfOpenContainsPoint, halfOpenContainsSpan, halfOpenDifference, halfOpenIntersection, halfOpenMerge, halfOpenOverlap, halfOpenUnion, halfOpenXor, } from "./halfOpenIntervals.js";
+export { EXTENDED_UTC_OFFSET, isoStringBody, TIME_ZONE_ANNOTATION, } from "./isoStringBody.js";
+export { formatHourDuration } from "./hourDurationString.js";
+export { canonicalInstantIntervals } from "./instantIntervalText.js";
+export { parseInstantNanoseconds } from "./instantNanoseconds.js";
+export { coalesceIntervalNanoseconds, parseIntervalNanoseconds, parseIntervalNanosecondsList, } from "./intervalNanoseconds.js";
 export { resolveDurationRelativeTo } from "./resolveDurationRelativeTo.js";
+export { formatUtcOffset, parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
 export { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES, } from "./englishCalendarNames.js";
-export { dateFromEthiopicFamilyFields, ethiopicFamilyDateParts, formatEthiopicFamilyDate, isEthiopicFamilyCalendar, } from "./ethiopicFamilyCalendar.js";
+export { defaultFractionalDigits } from "./defaultFractionalDigits.js";
 export { getLocaleFirstDayOfWeek } from "./getLocaleFirstDayOfWeek.js";
-export { getLocaleMinimalDaysInFirstWeek } from "./getLocaleMinimalDaysInFirstWeek.js";
+export { resolveMinimalDaysInFirstWeek } from "./resolveMinimalDaysInFirstWeek.js";
 export { getLocaleWeekYearBounds } from "./getLocaleWeekYearBounds.js";
 export { getLocaleWeekendDays } from "./getLocaleWeekendDays.js";
-export { getStartOfZonedUnit, getUnitSpan } from "./intervalCountHelpers.js";
+export { getUnitSpan } from "./intervalCountHelpers.js";
+export { isObject, isOptionsArgument } from "./isObject.js";
 export { isValidAmount } from "./isValidAmount.js";
 export { joinDateTimeConnector } from "./joinDateTimeConnector.js";
 export { isValidDayOfWeek } from "./isValidDayOfWeek.js";
 export { monthGridWeekRow } from "./monthGridWeekRow.js";
 export { normalizeDateTime } from "./normalizeDateTime.js";
 export { DATE_PATTERN_FIELDS, DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, TIME_PATTERN_FIELDS, } from "./patternToken.js";
+export { plainDateAdd } from "./plainDateAdd.js";
+export { plainDateUntil } from "./plainDateUntil.js";
 export { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
 export { resolveDurationUnit } from "./resolveDurationUnit.js";
 export { resolveOverflow } from "./resolveOverflow.js";
 export { resolveRelativeRounding } from "./resolveRelativeRounding.js";
+export { parseUnixEpochInterval, parseUnixEpochIntervalList, parseUnixEpochIntervalPair, parseUnixEpochValue, } from "./unixEpochValue.js";
+export { tileByUnit } from "./splitStep.js";
+export { countZonedBuckets, nextZonedBucketStart, type WeekStartDay, zonedUnitEnd, zonedUnitStart, } from "./zonedBucket.js";
+export { countZonedLocalDates } from "./zonedLocalDates.js";
+export { utcOffsetStringNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+export { wallClockAtOffset } from "./wallClockAtOffset.js";
+export { durationCompare, durationRound, durationTotal, isCalendarDifferenceAcrossZones, plainUntilWithRounding, zonedUntil, } from "./zonedWallClockDifference.js";
+export { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
+export { zonelessCalendarDate } from "./zonelessCalendarDate.js";