@northguild/gmt 1.15.0 → 1.16.0

package/dist/zoned/interval/intervalDifferenceZoned.js

@@ -1,16 +1,23 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { calendarOfAllZonedValues, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
+import { calendarOfAllZonedValues, formatZonedInCalendar, halfOpenDifference, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 /**
- * Return the portion(s) of interval A not covered by interval B.
+ * Return the portion(s) of the half-open interval A `[aStart, aEnd)` not covered by the half-open
+ * interval B `[bStart, bEnd)`.
  *
- * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
- * - Returns `[]` when B fully covers A (this includes B being identical to A).
+ * - Compares instants, with the same rule as `subtractIntervals`.
+ * - Every cut lands exactly on B's own `start` or `end`: the piece before B ends at `bStart`, which
+ *   it excludes, and the piece after B starts at `bEnd`, which B excludes. No boundary is stepped
+ *   by a nanosecond. A boundary A supplies keeps A's time zone; a cut keeps B's.
+ * - Returns `[]` when B fully covers A (this includes B being identical to A), and when A is empty
+ *   (`aStart` and `aEnd` the same instant).
  * - Returns `[{ start, end }]` when B overlaps exactly one edge of A.
  * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns A unchanged when B lies entirely before or after it, touches it, or is empty.
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings, leap seconds).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched pair**: every endpoint
  *   must name the same calendar system (E7's D4-zoned). Unlike the ordering functions, this one
  *   returns a *value* the caller reads back as a datetime, and there is no principled way to pick
@@ -22,8 +29,7 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  *   answer.) A mismatch returns the sentinel.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
- * - Still rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering — see
- *   `regex/calendar-zoned-date-time.ts`.
+ * - Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.
  *
  * @param aStart ISO 8601 zoned datetime string for the first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -31,14 +37,15 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * @param bEnd ISO 8601 zoned datetime string for the second interval end
  * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
  *
- * @example intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-06-01T11:59:59.999999999+00:00[UTC]" }, { start: "2024-07-01T13:00:00.000000001+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-06-01T12:00:00+00:00[UTC]" }, { start: "2024-07-01T13:00:00+00:00[UTC]", end: "2024-12-31T17:00:00+00:00[UTC]" }]
+ * @example intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T17:00:00+00:00[UTC]") // [{ start: "2024-01-01T09:00:00+00:00[UTC]", end: "2024-01-01T12:00:00+00:00[UTC]" }] (touching: B removes nothing)
  * @example intervalDifferenceZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // []
  * @example intervalDifferenceZoned("invalid", "2024-12-31T17:00:00+00:00[UTC]", "2024-06-01T12:00:00+00:00[UTC]", "2024-07-01T13:00:00+00:00[UTC]") // []
  */
 export function intervalDifferenceZoned(aStart, aEnd, bStart, bEnd) {
     // One gate for all four endpoints: `isValidCalendarZonedDateTime` covers non-strings, empty
     // strings, leap seconds (which Temporal would otherwise silently clamp to :59), unknown zones
-    // and Temporal's forbidden segment ordering, while accepting GMT's calendar-annotated grammar.
+    // and a calendar annotation before the zone, while accepting RFC 9557 calendar annotations.
     if (!isValidCalendarZonedDateTime(aStart) ||
         !isValidCalendarZonedDateTime(aEnd) ||
         !isValidCalendarZonedDateTime(bStart) ||
@@ -56,37 +63,18 @@ export function intervalDifferenceZoned(aStart, aEnd, bStart, bEnd) {
         const aEZdt = parseCalendarZonedValue(aEnd);
         const bSZdt = parseCalendarZonedValue(bStart);
         const bEZdt = parseCalendarZonedValue(bEnd);
-        const aS = aSZdt.toInstant();
-        const aE = aEZdt.toInstant();
-        const bS = bSZdt.toInstant();
-        const bE = bEZdt.toInstant();
-        if (Temporal.Instant.compare(aS, aE) > 0) {
+        if (Temporal.ZonedDateTime.compare(aSZdt, aEZdt) > 0) {
             return [];
         }
-        if (Temporal.Instant.compare(bS, bE) > 0) {
+        if (Temporal.ZonedDateTime.compare(bSZdt, bEZdt) > 0) {
             return [];
         }
-        const result = [];
-        // Left piece: A before B starts
-        if (Temporal.Instant.compare(aS, bS) < 0) {
-            const leftEnd = Temporal.Instant.compare(aE, bS) < 0
-                ? aE
-                : bS.subtract({ nanoseconds: 1 });
-            if (Temporal.Instant.compare(leftEnd, aS) >= 0) {
-                result.push({
-                    start: formatZonedInCalendar(aSZdt, calendar),
-                    end: formatZonedInCalendar(leftEnd.toZonedDateTimeISO(bEZdt.timeZoneId), calendar),
-                });
-            }
-        }
-        // Right piece: A after B ends
-        if (Temporal.Instant.compare(aE, bE) > 0) {
-            result.push({
-                start: formatZonedInCalendar(bE.add({ nanoseconds: 1 }).toZonedDateTimeISO(aEZdt.timeZoneId), calendar),
-                end: formatZonedInCalendar(aEZdt, calendar),
-            });
-        }
-        return result;
+        // The non-empty parts of A before B starts and after B ends; an empty B removes nothing. Each
+        // boundary is the ZonedDateTime that supplied it, so it keeps that input's zone.
+        return halfOpenDifference({ start: aSZdt, end: aEZdt }, [{ start: bSZdt, end: bEZdt }], Temporal.ZonedDateTime.compare).map(({ start, end }) => ({
+            start: formatZonedInCalendar(start, calendar),
+            end: formatZonedInCalendar(end, calendar),
+        }));
     }
     catch {
         return [];

package/dist/zoned/interval/intervalDivideEquallyZoned.d.ts

@@ -1,35 +1,44 @@
 /**
  * Split a zoned interval into `n` equal-length sub-intervals.
  *
- * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
- *   record's `end` equal to the next record's `start`.
- * - Boundaries are computed from the total elapsed real time (nanoseconds, via
- *   `Duration.prototype.total` with `relativeTo` set to `start`), so a spring-forward day split
- *   in half lands exactly on the DST transition's real midpoint rather than the local-clock
- *   midpoint.
+ * - Returns an array of `n` half-open `[start, end)` records that tile the original interval: each
+ *   record's `end` is the next record's `start` and belongs only to that next record, so the
+ *   pieces share no instant and together cover `[start, end)` exactly once.
+ * - Each boundary is `start + round((end - start) · i / n)` in integer epoch nanoseconds (real
+ *   elapsed time, exact at any span length), so a spring-forward day split in half lands exactly
+ *   on the DST transition's real midpoint rather than the local-clock midpoint.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
- * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals, each
+ *   an empty `[start, start)` that holds no instant.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`, leap-second strings).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched pair**: `start` and `end`
  *   must name the same calendar system (E7's D4-zoned), since the synthesized boundaries are
  *   values the caller reads back as datetimes and an array of differently-tagged records would be
  *   unreadable as a set. A mismatch returns `[]`.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
+ * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
+ *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
+ *   before building any piece. An invalid `maxPieces` also returns `[]`.
  *
  * @param start ISO 8601 zoned datetime string for the interval start
  * @param end ISO 8601 zoned datetime string for the interval end
  * @param n number of equal sub-intervals to produce (positive integer)
+ * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", 2) // [{ start: "2024-03-09T12:00:00-05:00[America/New_York]", end: "2024-03-10T12:30:00-04:00[America/New_York]" }, { start: "2024-03-10T12:30:00-04:00[America/New_York]", end: "2024-03-11T12:00:00-04:00[America/New_York]" }] (47 real hours split in half)
  * @example intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 1) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-04T00:00:00+00:00[UTC]" }]
  * @example intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 0) // []
  * @example intervalDivideEquallyZoned("invalid", "2024-01-04T00:00:00+00:00[UTC]", 3) // []
+ * @example intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 3, { maxPieces: 2 }) // [] (3 pieces exceed the limit)
+ * @example intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 3, { maxPieces: 3 }) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }, { start: "2024-01-02T00:00:00+00:00[UTC]", end: "2024-01-03T00:00:00+00:00[UTC]" }, { start: "2024-01-03T00:00:00+00:00[UTC]", end: "2024-01-04T00:00:00+00:00[UTC]" }]
  */
-export declare function intervalDivideEquallyZoned(start: string, end: string, n: number): Array<{
+export declare function intervalDivideEquallyZoned(start: string, end: string, n: number, options?: {
+    maxPieces?: number;
+}): Array<{
     start: string;
     end: string;
 }>;

package/dist/zoned/interval/intervalDivideEquallyZoned.js

@@ -1,80 +1,101 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
+import { Temporal } from "@js-temporal/polyfill";
 import { calendarOfAllZonedValues, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedInterval } from "./validate/index.js";
+import { divisionBoundary } from "../../internal/divisionBoundary.js";
+import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js";
 /**
  * Split a zoned interval into `n` equal-length sub-intervals.
  *
- * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
- *   record's `end` equal to the next record's `start`.
- * - Boundaries are computed from the total elapsed real time (nanoseconds, via
- *   `Duration.prototype.total` with `relativeTo` set to `start`), so a spring-forward day split
- *   in half lands exactly on the DST transition's real midpoint rather than the local-clock
- *   midpoint.
+ * - Returns an array of `n` half-open `[start, end)` records that tile the original interval: each
+ *   record's `end` is the next record's `start` and belongs only to that next record, so the
+ *   pieces share no instant and together cover `[start, end)` exactly once.
+ * - Each boundary is `start + round((end - start) · i / n)` in integer epoch nanoseconds (real
+ *   elapsed time, exact at any span length), so a spring-forward day split in half lands exactly
+ *   on the DST transition's real midpoint rather than the local-clock midpoint.
  * - `n === 1` returns the original interval unchanged, as a single-element array.
- * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals, each
+ *   an empty `[start, start)` that holds no instant.
  * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
  *   start/end, `start > end`, leap-second strings).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched pair**: `start` and `end`
  *   must name the same calendar system (E7's D4-zoned), since the synthesized boundaries are
  *   values the caller reads back as datetimes and an array of differently-tagged records would be
  *   unreadable as a set. A mismatch returns `[]`.
  * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
  *   copied from an input string (E7's D7-zoned).
+ * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: when `n`
+ *   exceeds it, or exceeds the longest possible array (2^32 - 1), the function returns `[]`
+ *   before building any piece. An invalid `maxPieces` also returns `[]`.
  *
  * @param start ISO 8601 zoned datetime string for the interval start
  * @param end ISO 8601 zoned datetime string for the interval end
  * @param n number of equal sub-intervals to produce (positive integer)
+ * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
  * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
  *
  * @example intervalDivideEquallyZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", 2) // [{ start: "2024-03-09T12:00:00-05:00[America/New_York]", end: "2024-03-10T12:30:00-04:00[America/New_York]" }, { start: "2024-03-10T12:30:00-04:00[America/New_York]", end: "2024-03-11T12:00:00-04:00[America/New_York]" }] (47 real hours split in half)
  * @example intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 1) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-04T00:00:00+00:00[UTC]" }]
  * @example intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 0) // []
  * @example intervalDivideEquallyZoned("invalid", "2024-01-04T00:00:00+00:00[UTC]", 3) // []
+ * @example intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 3, { maxPieces: 2 }) // [] (3 pieces exceed the limit)
+ * @example intervalDivideEquallyZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]", 3, { maxPieces: 3 }) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }, { start: "2024-01-02T00:00:00+00:00[UTC]", end: "2024-01-03T00:00:00+00:00[UTC]" }, { start: "2024-01-03T00:00:00+00:00[UTC]", end: "2024-01-04T00:00:00+00:00[UTC]" }]
  */
-export function intervalDivideEquallyZoned(start, end, n) {
-    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
-        return [];
-    }
-    if (!isValidCalendarZonedInterval(start, end)) {
-        return [];
-    }
-    // D4-zoned reject gate: both endpoints must agree on a calendar, or there is no calendar to
-    // express the synthesized boundaries in.
-    const calendar = calendarOfAllZonedValues([start, end]);
-    if (!calendar) {
-        return [];
-    }
+export function intervalDivideEquallyZoned(start, end, n, options) {
     try {
-        const startVal = parseCalendarZonedValue(start);
-        const endVal = parseCalendarZonedValue(end);
-        // Safe: `.equals()` here is `Temporal.Instant.prototype.equals`, and `Instant` carries no
-        // calendar field at all — verified calendar-blind. E7 re-audited this site rather than
-        // inheriting E5's "structurally unreachable" verdict, which depended on mixed calendars never
-        // reaching `zoned/` at all.
-        if (startVal.toInstant().equals(endVal.toInstant())) {
-            return Array.from({ length: n }, () => ({
-                start: formatZonedInCalendar(startVal, calendar),
-                end: formatZonedInCalendar(endVal, calendar),
-            }));
+        if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+            return [];
+        }
+        const maxPieces = resolveMaxPieces(options);
+        if (maxPieces === null || exceedsPieceLimit(n, maxPieces)) {
+            return [];
+        }
+        if (!isValidCalendarZonedInterval(start, end)) {
+            return [];
+        }
+        // D4-zoned reject gate: both endpoints must agree on a calendar, or there is no calendar to
+        // express the synthesized boundaries in.
+        const calendar = calendarOfAllZonedValues([start, end]);
+        if (!calendar) {
+            return [];
         }
-        const totalNs = startVal
-            .until(endVal, { largestUnit: "nanosecond" })
-            .total({ unit: "nanosecond", relativeTo: startVal });
-        const boundaries = [startVal];
-        for (let i = 1; i < n; i++) {
-            boundaries.push(startVal.add({ nanoseconds: Math.round((totalNs * i) / n) }));
+        try {
+            const startVal = parseCalendarZonedValue(start);
+            const endVal = parseCalendarZonedValue(end);
+            // Safe: `.equals()` here is `Temporal.Instant.prototype.equals`, and `Instant` carries no
+            // calendar field at all — verified calendar-blind. E7 re-audited this site rather than
+            // inheriting E5's "structurally unreachable" verdict, which depended on mixed calendars never
+            // reaching `zoned/` at all.
+            if (startVal.toInstant().equals(endVal.toInstant())) {
+                return Array.from({ length: n }, () => ({
+                    start: formatZonedInCalendar(startVal, calendar),
+                    end: formatZonedInCalendar(endVal, calendar),
+                }));
+            }
+            const startNs = startVal.epochNanoseconds;
+            const totalNs = endVal.epochNanoseconds - startNs;
+            const boundaries = [startVal];
+            for (let i = 1; i < n; i++) {
+                boundaries.push(new Temporal.ZonedDateTime(startNs + divisionBoundary(totalNs, i, n), startVal.timeZoneId, startVal.calendarId));
+            }
+            boundaries.push(endVal);
+            const result = [];
+            for (let i = 0; i < boundaries.length - 1; i++) {
+                result.push({
+                    start: formatZonedInCalendar(boundaries[i], calendar),
+                    end: formatZonedInCalendar(boundaries[i + 1], calendar),
+                });
+            }
+            return result;
         }
-        boundaries.push(endVal);
-        const result = [];
-        for (let i = 0; i < boundaries.length - 1; i++) {
-            result.push({
-                start: formatZonedInCalendar(boundaries[i], calendar),
-                end: formatZonedInCalendar(boundaries[i + 1], calendar),
-            });
+        catch {
+            return [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/zoned/interval/intervalEngulfsZoned.d.ts

@@ -1,19 +1,24 @@
 /**
- * Return true when interval B is fully contained within interval A — every instant of B
- * falls within A.
+ * Return true when the half-open interval B `[bStart, bEnd)` lies within the half-open interval
+ * A `[aStart, aEnd)` — every instant of B falls within A.
  *
  * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
+ * - B is inside A when the intervals overlap and `aStart <= bStart` and `bEnd <= aEnd` by
+ *   instant. Both ends are exclusive, so B may start at A's start and end at A's end.
+ * - An empty B counts only strictly inside A, the same edge rule as `clampInterval`; at either edge
+ *   of A it returns `false`, and an empty A engulfs nothing.
  * - Equivalent to 4-argument `intervalContainsZoned(aStart, aEnd, bStart, bEnd)`.
  * - Returns `false` if either interval is invalid (`start > end`).
  * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
  * - **Accepts mixed calendar systems** (E7's D4-zoned, issue #152): both bare ISO zoned strings
- *   and GMT calendar-annotated ones (`"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`),
+ *   and RFC 9557 calendar-annotated ones (`"2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]"`),
  *   and the two endpoints need not agree on a calendar. Ordering is calendar-independent —
  *   verified that `Temporal.Instant` carries no calendar field at all and that
  *   `Instant.compare`/`ZonedDateTime.compare` both return `0` for the same instant expressed in
  *   hebrew, islamic-civil, japanese and iso8601.
- * - Still rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering, which reads GMT's
- *   calendar-native digits as ISO digits — see `regex/calendar-zoned-date-time.ts`.
+ * - Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, the `[u-ca=<id>]`
+ *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
  *
  * @param aStart ISO 8601 zoned datetime string for the outer interval start
  * @param aEnd ISO 8601 zoned datetime string for the outer interval end

package/dist/zoned/interval/intervalEngulfsZoned.js

@@ -1,22 +1,28 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { parseCalendarZonedValue } from "../../internal/index.js";
+import { halfOpenContainsSpan, parseCalendarZonedValue } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 /**
- * Return true when interval B is fully contained within interval A — every instant of B
- * falls within A.
+ * Return true when the half-open interval B `[bStart, bEnd)` lies within the half-open interval
+ * A `[aStart, aEnd)` — every instant of B falls within A.
  *
  * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
+ * - B is inside A when the intervals overlap and `aStart <= bStart` and `bEnd <= aEnd` by
+ *   instant. Both ends are exclusive, so B may start at A's start and end at A's end.
+ * - An empty B counts only strictly inside A, the same edge rule as `clampInterval`; at either edge
+ *   of A it returns `false`, and an empty A engulfs nothing.
  * - Equivalent to 4-argument `intervalContainsZoned(aStart, aEnd, bStart, bEnd)`.
  * - Returns `false` if either interval is invalid (`start > end`).
  * - Returns `false` on invalid input (wrong type, malformed strings, leap seconds).
  * - **Accepts mixed calendar systems** (E7's D4-zoned, issue #152): both bare ISO zoned strings
- *   and GMT calendar-annotated ones (`"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`),
+ *   and RFC 9557 calendar-annotated ones (`"2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]"`),
  *   and the two endpoints need not agree on a calendar. Ordering is calendar-independent —
  *   verified that `Temporal.Instant` carries no calendar field at all and that
  *   `Instant.compare`/`ZonedDateTime.compare` both return `0` for the same instant expressed in
  *   hebrew, islamic-civil, japanese and iso8601.
- * - Still rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering, which reads GMT's
- *   calendar-native digits as ISO digits — see `regex/calendar-zoned-date-time.ts`.
+ * - Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, the `[u-ca=<id>]`
+ *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
  *
  * @param aStart ISO 8601 zoned datetime string for the outer interval start
  * @param aEnd ISO 8601 zoned datetime string for the outer interval end
@@ -33,8 +39,8 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
 export function intervalEngulfsZoned(aStart, aEnd, bStart, bEnd) {
     // One gate for all four endpoints: `isValidCalendarZonedDateTime` already covers non-strings,
     // empty strings, leap seconds (which Temporal would otherwise silently clamp to :59), unknown
-    // zones and Temporal's forbidden segment ordering — and, unlike `isValidZonedDateTime`, accepts
-    // GMT's calendar-annotated grammar.
+    // zones and a calendar annotation before the zone — and, unlike `isValidZonedDateTime`, accepts
+    // RFC 9557 calendar annotations.
     if (!isValidCalendarZonedDateTime(aStart) ||
         !isValidCalendarZonedDateTime(aEnd) ||
         !isValidCalendarZonedDateTime(bStart) ||
@@ -56,8 +62,8 @@ export function intervalEngulfsZoned(aStart, aEnd, bStart, bEnd) {
         if (Temporal.Instant.compare(bS, bE) > 0) {
             return false;
         }
-        return (Temporal.Instant.compare(aS, bS) <= 0 &&
-            Temporal.Instant.compare(bE, aE) <= 0);
+        // B overlaps A, and B's start and exclusive end both lie within A's bounds.
+        return halfOpenContainsSpan({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.Instant.compare);
     }
     catch {
         return false;

package/dist/zoned/interval/intervalFromDurationZoned.d.ts

@@ -1,4 +1,4 @@
-import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
+import type { Disambiguation, Overflow } from "../../types/index.js";
 /**
  * Construct a zoned interval from a single point plus an ISO 8601 duration, anchored at either end.
  *
@@ -6,38 +6,52 @@ import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
  * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
  * - Uses `Temporal.ZonedDateTime.prototype.add`/`.subtract`, so calendar units (years/months/weeks)
  *   resolve against `value` itself — no separate `relativeTo` is needed.
- * - `disambiguation` controls DST resolution ONLY when the arithmetic result lands on an ambiguous
- *   local time from a fall-back (DST-end) overlap: "compatible" (default), "earlier", "later", or
- *   "reject" (returns null). Mirrors `addZoned`'s exact semantics — has no effect on a spring-forward
- *   (DST-start) gap landing, which Temporal's arithmetic always resolves before disambiguation runs.
- * - `offset` is accepted for API consistency with `addZoned` but has **no effect here** for the same
- *   reason documented there: the disambiguation rebuild has no stored offset to prefer/use/ignore/reject.
+ * - Follows Temporal's AddZonedDateTime: the date portion of the duration (years, months, weeks,
+ *   days) moves the wall-clock date, then the time portion (hours and smaller) is added (subtracted
+ *   for `anchor: "end"`) in exact time. `disambiguation` ("compatible" (default), "earlier",
+ *   "later", or "reject" (returns null)) applies ONLY to the intermediate wall-clock date-time after
+ *   the date portion, exactly as Temporal's GetEpochNanosecondsFor resolves it: in a fall-back
+ *   (DST-end) overlap "compatible" and "earlier" take the earlier instant and "later" the later
+ *   one; in a spring-forward (DST-start) gap "compatible" and "later" move the wall clock forward by
+ *   the gap length and "earlier" back by it; "reject" returns null for both. It never re-resolves
+ *   the exact-time result, so a time-only duration ignores it.
+ * - Compatibility: before 1.16.0 a date portion landing in a spring-forward gap was always moved
+ *   forward, whatever `disambiguation` said. Pass "compatible" (or omit it) to keep that result.
+ * - Compatibility: before 1.16.0 a non-"compatible" `disambiguation` re-resolved the final wall
+ *   clock (so `+ { minutes: 10 }` from `01:30-05:00` with "earlier" returned `01:40-04:00`, 50
+ *   minutes earlier in exact time). To get that value, re-resolve the result's wall clock:
+ *   `setZoned(result, { hour, minute, second }, { disambiguation, offset: "ignore" })`.
+ * - There is no `offset` option (removed in 1.16.0): the computed endpoint's wall clock is resolved
+ *   from a plain date-time, which has no UTC offset for it to act on.
  * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
  *   happens, mirroring `intervalIntersectionZoned`'s `start > end` rejection.
  * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
  *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
- * - Accepts a GMT calendar-annotated zoned string (as produced by `convertZonedToCalendar`) as
+ * - Accepts a RFC 9557 calendar-annotated zoned string (as produced by `convertZonedToCalendar`) as
  *   well as a bare ISO one — E7 (issue #152). Calendar units in `duration` resolve against that
  *   calendar, and both returned endpoints are re-derived in it via `formatZonedInCalendar`. There
- *   is only ONE calendar-tagged input here, so no D5 pair policy applies — nothing can mismatch.
+ *   is only ONE calendar-tagged input here, so there is no second calendar to mismatch.
  * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
  *   than `"start"`/`"end"`).
  *
  * @param value ISO 8601 zoned datetime string, optionally calendar-annotated
  * @param duration ISO 8601 duration string
  * @param anchor "start" | "end" — which endpoint `value` represents
- * @param options optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject" — accepted but inert, see above), overflow ("constrain" | "reject")
+ * @param options optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), overflow ("constrain" | "reject")
  * @returns `{ start, end }` with the constructed span, or null on invalid input
  *
  * @example intervalFromDurationZoned("2024-01-01T00:00:00+00:00[UTC]", "P1D", "start") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }
  * @example intervalFromDurationZoned("2024-01-02T00:00:00+00:00[UTC]", "P1D", "end") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }
  * @example intervalFromDurationZoned("2024-11-02T01:30:00-04:00[America/New_York]", "P1D", "start", { disambiguation: "later" }) // { start: "2024-11-02T01:30:00-04:00[America/New_York]", end: "2024-11-03T01:30:00-05:00[America/New_York]" } (fall-back overlap resolved; default "compatible" would return the -04:00 instant instead)
+ * @example intervalFromDurationZoned("2024-03-09T02:30:00-05:00[America/New_York]", "P1D", "start", { disambiguation: "earlier" }) // { start: "2024-03-09T02:30:00-05:00[America/New_York]", end: "2024-03-10T01:30:00-05:00[America/New_York]" } (spring-forward gap; "earlier" moves the end back an hour)
+ * @example intervalFromDurationZoned("2024-03-09T02:30:00-05:00[America/New_York]", "P1D", "start", { disambiguation: "reject" }) // null (spring-forward gap rejected)
+ * @example intervalFromDurationZoned("2024-11-03T00:30:00-04:00[America/New_York]", "PT1H", "start", { disambiguation: "later" }) // { start: "2024-11-03T00:30:00-04:00[America/New_York]", end: "2024-11-03T01:30:00-04:00[America/New_York]" } (exact time — disambiguation never re-resolves it)
+ * @example setZoned(intervalFromDurationZoned("2024-11-03T00:30:00-04:00[America/New_York]", "PT1H", "start")?.end ?? "", { hour: 1, minute: 30, second: 0 }, { disambiguation: "later", offset: "ignore" }) // "2024-11-03T01:30:00-05:00[America/New_York]" (pre-1.16.0 end)
  * @example intervalFromDurationZoned("2024-01-31T12:00:00-05:00[America/New_York]", "P1M", "start", { overflow: "reject" }) // null
  * @example intervalFromDurationZoned("invalid", "P1D", "start") // null
  */
 export declare function intervalFromDurationZoned(value: string, duration: string, anchor: "start" | "end", options?: {
     disambiguation?: Disambiguation;
-    offset?: Offset;
     overflow?: Overflow;
 }): {
     start: string;