@northguild/gmt 1.14.2 → 1.16.0

package/dist/zoned/interval/intervalFromDurationZoned.js

@@ -1,7 +1,8 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDuration } from "../../duration/validate/index.js";
-import { calendarSystemOfZonedValue, formatZonedInCalendar, parseCalendarZonedValue, resolveOverflow, } from "../../internal/index.js";
+import { addToZonedDisambiguated, calendarSystemOfZonedValue, formatZonedInCalendar, parseCalendarZonedValue, resolveOverflow, } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Construct a zoned interval from a single point plus an ISO 8601 duration, anchored at either end.
  *
@@ -9,77 +10,93 @@ import { isValidCalendarZonedDateTime } from "../validate/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 function intervalFromDurationZoned(value, duration, anchor, options) {
-    if (!isValidCalendarZonedDateTime(value)) {
-        return null;
-    }
-    if (!isValidDuration(duration)) {
-        return null;
-    }
-    if (anchor !== "start" && anchor !== "end") {
-        return null;
-    }
-    const disambiguation = options?.disambiguation ?? "compatible";
-    const offset = options?.offset ?? "ignore";
-    const overflow = resolveOverflow(options?.overflow);
     try {
-        const calendar = calendarSystemOfZonedValue(value);
-        if (!calendar) {
+        if (!isOptionsArgument(options)) {
             return null;
         }
-        const point = parseCalendarZonedValue(value);
-        const dur = Temporal.Duration.from(duration);
-        const rawOther = anchor === "start"
-            ? point.add(dur, { overflow })
-            : point.subtract(dur, { overflow });
-        // The calendar MUST be stripped before this rebuild string is composed (E7 risk R1) — see
-        // `addZoned`'s equivalent comment. A calendared `.toPlainDateTime().toString()` already
-        // carries Temporal's own `[u-ca=...]` annotation, so appending `[${timeZoneId}]` produces
-        // GMT's forbidden segment ordering and `Temporal.ZonedDateTime.from` rejects it, silently
-        // degrading every non-"compatible" disambiguation to null.
-        const other = disambiguation === "compatible"
-            ? rawOther
-            : Temporal.ZonedDateTime.from(`${rawOther.withCalendar("iso8601").toPlainDateTime().toString()}[${rawOther.timeZoneId}]`, { disambiguation, offset }).withCalendar(rawOther.calendarId);
-        const start = anchor === "start" ? point : other;
-        const end = anchor === "start" ? other : point;
-        if (Temporal.ZonedDateTime.compare(start, end) > 0) {
+        if (!isValidCalendarZonedDateTime(value)) {
+            return null;
+        }
+        if (!isValidDuration(duration)) {
+            return null;
+        }
+        if (anchor !== "start" && anchor !== "end") {
+            return null;
+        }
+        const disambiguation = options?.disambiguation === undefined
+            ? "compatible"
+            : options.disambiguation;
+        const overflow = resolveOverflow(options?.overflow);
+        try {
+            const calendar = calendarSystemOfZonedValue(value);
+            if (!calendar) {
+                return null;
+            }
+            const point = parseCalendarZonedValue(value);
+            const dur = Temporal.Duration.from(duration);
+            const other = addToZonedDisambiguated(point, dur, anchor === "start" ? 1 : -1, { overflow, disambiguation });
+            const start = anchor === "start" ? point : other;
+            const end = anchor === "start" ? other : point;
+            if (Temporal.ZonedDateTime.compare(start, end) > 0) {
+                return null;
+            }
+            return {
+                start: formatZonedInCalendar(start, calendar),
+                end: formatZonedInCalendar(end, calendar),
+            };
+        }
+        catch {
             return null;
         }
-        return {
-            start: formatZonedInCalendar(start, calendar),
-            end: formatZonedInCalendar(end, calendar),
-        };
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -1,11 +1,18 @@
 /**
- * Return the overlapping span of two zoned intervals, or null when they do not overlap.
+ * Return the overlapping span of two half-open zoned intervals `[start, end)`, or null when they
+ * do not overlap.
  *
  * - Uses `Temporal.ZonedDateTime.compare` for comparison (same instant semantics).
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - The result is `[max(aStart, bStart), min(aEnd, bEnd))`, and it exists only when
+ *   `intervalsOverlapZoned` is true — the same rule as `intersectIntervals`. On a tie the first
+ *   interval's boundary wins, so its time zone is the one kept.
+ * - Touching intervals (e.g. `aEnd` the same instant as `bStart`) share no instant, because each
+ *   `end` is excluded, and return `null`.
+ * - An empty interval (`start` and `end` the same instant) strictly inside the other returns
+ *   itself; at either edge, or against another empty interval, it returns `null`.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` 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
@@ -17,8 +24,7 @@
  *   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
@@ -27,7 +33,7 @@
  * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap
  *
  * @example intervalIntersectionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-04-01T00:00:00+00:00[UTC]", end: "2024-06-30T23:59:59+00:00[UTC]" }
- * @example intervalIntersectionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
+ * @example intervalIntersectionZoned("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]") // null (touching: no shared instant)
  * @example intervalIntersectionZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
  */
 export declare function intervalIntersectionZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): {

package/dist/zoned/interval/intervalIntersectionZoned.js

@@ -1,14 +1,22 @@
+// 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, halfOpenIntersection, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 /**
- * Return the overlapping span of two zoned intervals, or null when they do not overlap.
+ * Return the overlapping span of two half-open zoned intervals `[start, end)`, or null when they
+ * do not overlap.
  *
  * - Uses `Temporal.ZonedDateTime.compare` for comparison (same instant semantics).
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - The result is `[max(aStart, bStart), min(aEnd, bEnd))`, and it exists only when
+ *   `intervalsOverlapZoned` is true — the same rule as `intersectIntervals`. On a tie the first
+ *   interval's boundary wins, so its time zone is the one kept.
+ * - Touching intervals (e.g. `aEnd` the same instant as `bStart`) share no instant, because each
+ *   `end` is excluded, and return `null`.
+ * - An empty interval (`start` and `end` the same instant) strictly inside the other returns
+ *   itself; at either edge, or against another empty interval, it returns `null`.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` 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
@@ -20,8 +28,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
@@ -30,13 +37,13 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap
  *
  * @example intervalIntersectionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-04-01T00:00:00+00:00[UTC]", end: "2024-06-30T23:59:59+00:00[UTC]" }
- * @example intervalIntersectionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-07-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
+ * @example intervalIntersectionZoned("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]") // null (touching: no shared instant)
  * @example intervalIntersectionZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
  */
 export function intervalIntersectionZoned(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) ||
@@ -60,16 +67,15 @@ export function intervalIntersectionZoned(aStart, aEnd, bStart, bEnd) {
         if (Temporal.ZonedDateTime.compare(bZdt, bZde) > 0) {
             return null;
         }
-        if (Temporal.ZonedDateTime.compare(aZde, bZdt) < 0 ||
-            Temporal.ZonedDateTime.compare(bZde, aZdt) < 0) {
-            return null;
-        }
-        const start = Temporal.ZonedDateTime.compare(aZdt, bZdt) >= 0 ? aZdt : bZdt;
-        const end = Temporal.ZonedDateTime.compare(aZde, bZde) <= 0 ? aZde : bZde;
-        return {
-            start: formatZonedInCalendar(start, calendar),
-            end: formatZonedInCalendar(end, calendar),
-        };
+        // Null unless each interval starts before the other's exclusive end; on a tie the first
+        // interval's boundary, and so its zone, is kept.
+        const overlap = halfOpenIntersection({ start: aZdt, end: aZde }, { start: bZdt, end: bZde }, Temporal.ZonedDateTime.compare);
+        return overlap === null
+            ? null
+            : {
+                start: formatZonedInCalendar(overlap.start, calendar),
+                end: formatZonedInCalendar(overlap.end, calendar),
+            };
     }
     catch {
         return null;

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

@@ -8,15 +8,21 @@
  * - Uses `Temporal.Duration.prototype.total` with `relativeTo` set to `start`, so the result is
  *   DST-aware: dividing a spring-forward day's length in hours returns `23`, not `24`.
  * - Returns `0` for a zero-length interval (`start === end`).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Two values in different time zones (by TC39 TimeZoneEquals, so `UTC` equals `Etc/UTC`) can
+ *   only be measured in time units: a calendar unit (day, week, month, year) returns null, as
+ *   Temporal's `until` throws, because day lengths differ between zones.
+ * - Compatibility: before 1.16.0 a calendar unit across two zones returned a number. To measure
+ *   such a pair, convert both ends to one zone first with `convertZonedToZoned`.
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152). When BOTH endpoints carry the same calendar tag the
- *   measurement is made in that calendar; when the tags mismatch, or either endpoint is bare ISO,
- *   it falls back to Gregorian/ISO rather than returning the sentinel (E7's D5-zoned). The
- *   fallback is mandatory, not a convenience: `ZonedDateTime.prototype.until` throws across
- *   mismatched calendars for EVERY `largestUnit` — verified, including `"hour"` and
- *   `"nanosecond"`.
+ *   measurement is made in that calendar. When they name different calendars (a bare ISO string
+ *   names `iso8601`) the result is `null` in every unit, `"hour"` included, as
+ *   `ZonedDateTime.prototype.until` throws when TC39 `CalendarEquals` is false (before 1.16.0 it
+ *   was measured in ISO).
  * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
  *   leap-second strings).
+ * - 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 start ISO 8601 zoned datetime string for the interval start
  * @param end ISO 8601 zoned datetime string for the interval end
@@ -26,6 +32,9 @@
  * @example intervalLengthZoned("2024-03-10T00:00:00-05:00[America/New_York]", "2024-03-11T00:00:00-04:00[America/New_York]", "hour") // 23 (spring forward)
  * @example intervalLengthZoned("2024-03-10T00:00:00-05:00[America/New_York]", "2024-03-11T00:00:00-04:00[America/New_York]", "day") // 1
  * @example intervalLengthZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "day") // 0
+ * @example intervalLengthZoned("2024-01-01T00:00:00-05:00[America/New_York]", "2024-01-03T00:00:00+01:00[Europe/Paris]", "hour") // 42
+ * @example intervalLengthZoned("2024-01-01T00:00:00-05:00[America/New_York]", "2024-01-03T00:00:00+01:00[Europe/Paris]", "day") // null (calendar unit across two time zones)
+ * @example intervalLengthZoned("2024-01-01T00:00:00-05:00[America/New_York]", convertZonedToZoned("2024-01-03T00:00:00+01:00[Europe/Paris]", "America/New_York"), "day") // 1.75 (both ends in one zone first)
  * @example intervalLengthZoned("invalid", "2024-01-02T00:00:00+00:00[UTC]", "day") // null
  */
 export declare function intervalLengthZoned(start: string, end: string, unit: string): number | null;

package/dist/zoned/interval/intervalLengthZoned.js

@@ -1,4 +1,4 @@
-import { parseCalendarZonedPairForArithmetic, resolveDateTimeUnit, } from "../../internal/index.js";
+import { durationTotal, isCalendarDifferenceAcrossZones, parseCalendarZonedPairForArithmetic, resolveDateTimeUnit, zonedUntil, } from "../../internal/index.js";
 import { isValidDateTimeUnit } from "../../plain/validate/index.js";
 import { isValidCalendarZonedInterval } from "./validate/index.js";
 /**
@@ -11,15 +11,21 @@ import { isValidCalendarZonedInterval } from "./validate/index.js";
  * - Uses `Temporal.Duration.prototype.total` with `relativeTo` set to `start`, so the result is
  *   DST-aware: dividing a spring-forward day's length in hours returns `23`, not `24`.
  * - Returns `0` for a zero-length interval (`start === end`).
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ * - Two values in different time zones (by TC39 TimeZoneEquals, so `UTC` equals `Etc/UTC`) can
+ *   only be measured in time units: a calendar unit (day, week, month, year) returns null, as
+ *   Temporal's `until` throws, because day lengths differ between zones.
+ * - Compatibility: before 1.16.0 a calendar unit across two zones returned a number. To measure
+ *   such a pair, convert both ends to one zone first with `convertZonedToZoned`.
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
  *   well as bare ISO ones — E7 (issue #152). When BOTH endpoints carry the same calendar tag the
- *   measurement is made in that calendar; when the tags mismatch, or either endpoint is bare ISO,
- *   it falls back to Gregorian/ISO rather than returning the sentinel (E7's D5-zoned). The
- *   fallback is mandatory, not a convenience: `ZonedDateTime.prototype.until` throws across
- *   mismatched calendars for EVERY `largestUnit` — verified, including `"hour"` and
- *   `"nanosecond"`.
+ *   measurement is made in that calendar. When they name different calendars (a bare ISO string
+ *   names `iso8601`) the result is `null` in every unit, `"hour"` included, as
+ *   `ZonedDateTime.prototype.until` throws when TC39 `CalendarEquals` is false (before 1.16.0 it
+ *   was measured in ISO).
  * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
  *   leap-second strings).
+ * - 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 start ISO 8601 zoned datetime string for the interval start
  * @param end ISO 8601 zoned datetime string for the interval end
@@ -29,6 +35,9 @@ import { isValidCalendarZonedInterval } from "./validate/index.js";
  * @example intervalLengthZoned("2024-03-10T00:00:00-05:00[America/New_York]", "2024-03-11T00:00:00-04:00[America/New_York]", "hour") // 23 (spring forward)
  * @example intervalLengthZoned("2024-03-10T00:00:00-05:00[America/New_York]", "2024-03-11T00:00:00-04:00[America/New_York]", "day") // 1
  * @example intervalLengthZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "day") // 0
+ * @example intervalLengthZoned("2024-01-01T00:00:00-05:00[America/New_York]", "2024-01-03T00:00:00+01:00[Europe/Paris]", "hour") // 42
+ * @example intervalLengthZoned("2024-01-01T00:00:00-05:00[America/New_York]", "2024-01-03T00:00:00+01:00[Europe/Paris]", "day") // null (calendar unit across two time zones)
+ * @example intervalLengthZoned("2024-01-01T00:00:00-05:00[America/New_York]", convertZonedToZoned("2024-01-03T00:00:00+01:00[Europe/Paris]", "America/New_York"), "day") // 1.75 (both ends in one zone first)
  * @example intervalLengthZoned("invalid", "2024-01-02T00:00:00+00:00[UTC]", "day") // null
  */
 export function intervalLengthZoned(start, end, unit) {
@@ -44,7 +53,12 @@ export function intervalLengthZoned(start, end, unit) {
     }
     try {
         const { a: startVal, b: endVal } = parseCalendarZonedPairForArithmetic(start, end);
-        const duration = startVal.until(endVal, { largestUnit: resolvedUnit });
+        if (isCalendarDifferenceAcrossZones(startVal, endVal, resolvedUnit)) {
+            return null;
+        }
+        const duration = zonedUntil(startVal, endVal, {
+            largestUnit: resolvedUnit,
+        });
         // total() with relativeTo gives the exact, DST-aware elapsed length, unlike
         // intervalCountZoned's boundary-crossing count — a spring-forward day touches 1 day
         // boundary via intervalCountZoned but is exactly 23/24 days (or 23 hours) here.
@@ -53,7 +67,7 @@ export function intervalLengthZoned(start, end, unit) {
         // `start`. Anchoring to a still-calendar-tagged operand while the duration was measured in
         // ISO does not throw — it returns a plausible-looking WRONG number (verified: 12.586…, sitting
         // between the correct ISO 12.5666… and the correct Hebrew 13), which no sanity check catches.
-        return duration.total({ unit: resolvedUnit, relativeTo: startVal });
+        return durationTotal(duration, resolvedUnit, startVal);
     }
     catch {
         return null;

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

@@ -2,32 +2,39 @@
  * Return how many distinct calendar dates two zoned intervals share, counted in the
  * first interval's zone.
  *
- * - Counts the number of local dates touched by the closed intersection
- *   `[max(aStart, bStart), min(aEnd, bEnd)]` — inclusive of both endpoints.
+ * - Counts the local dates that hold at least one instant of the half-open intersection
+ *   `[max(aStart, bStart), min(aEnd, bEnd))`. The end is excluded, so an intersection ending at
+ *   local midnight does not touch the date that midnight starts.
  * - `aEnd`, `bStart`, and `bEnd` are re-expressed in `aStart`'s time zone before comparing —
  *   Temporal refuses to compute day-granularity differences directly across two zones, since
  *   day length varies with DST/offset changes. As a result this function is NOT commutative:
  *   swapping the two intervals can change the answer when their zones differ.
- * - Zones whose calendar skips a date entirely (e.g. `Pacific/Apia`'s 2011 dateline change)
- *   still count the skipped date — this matches `intervalCountZoned`'s calendar-arithmetic
- *   rule, so the two functions never disagree about what a day is.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one date and count as `1`.
- * - Returns `0` when the intervals do not overlap at all (a well-defined answer, not
- *   invalid input).
+ * - Each instant in the intersection contributes its own local date, and each date counts once.
+ *   A date the zone deleted is not counted, because no instant has it (`Pacific/Apia` skipped
+ *   2011-12-30). A fall-back that sends the clock back into the previous date does not lose that
+ *   date (`America/Goose_Bay` fell back at 00:01 on 2010-11-07 into 2010-11-06).
+ * - Returns `null` when the intersection crosses more than 10,000 zone transitions (the same cap
+ *   as `intervalCountZoned`).
+ * - Compatibility: before 1.16.0 the count was the calendar difference of the two endpoint dates
+ *   plus one, which counts a deleted date and can be 0 or 1 across a fall-back into the previous
+ *   date. To get that number, with `start`/`end` the intersection endpoints in `aStart`'s zone:
+ *   `diffDate(parseDateFromZoned(start), parseDateFromZoned(end), "days") + 1`.
+ * - Returns `0` when the intersection is empty (a well-defined answer, not invalid input): when the
+ *   intervals are disjoint, when they touch (e.g. `aEnd` the same instant as `bStart`), or when
+ *   either is empty.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` 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 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`.
+ * - Accepts RFC 9557 calendar-annotated zoned strings
+ *   (`"2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]"`; E7, issue #152). All four
+ *   arguments must name the same calendar (a bare string names `iso8601`): the count is a day
+ *   difference, so different calendars return `null`, as Temporal's `until` throws when
+ *   `CalendarEquals` is false. Before 1.16.0 the arguments could name different calendars.
  * - Diverges from date-fns's `getOverlappingDaysInIntervals`, which rounds up elapsed
  *   24-hour periods instead of counting calendar dates. To reproduce date-fns's number,
  *   compose `intervalIntersectionZoned` with `intervalCountZoned`:
  *   `const span = intervalIntersectionZoned(aStart, aEnd, bStart, bEnd); span ? intervalCountZoned(span.start, span.end, "day") : 0;`
+ * - 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 first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -36,7 +43,11 @@
  * @returns number of shared calendar dates (counted in aStart's zone), `0` when disjoint, or null on invalid input
  *
  * @example intervalOverlappingDaysZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", "2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]") // 3 (spring-forward, 47 real hours)
- * @example intervalOverlappingDaysZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "2024-01-03T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]") // 0 (disjoint)
+ * @example intervalOverlappingDaysZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "2024-01-03T00:00:00+00:00[UTC]") // 0 (touching: no shared instant)
+ * @example intervalOverlappingDaysZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]") // 1 (the end, 01-02T00:00, is excluded)
+ * @example intervalOverlappingDaysZoned("2011-12-29T23:00:00-10:00[Pacific/Apia]", "2011-12-31T01:00:00+14:00[Pacific/Apia]", "2011-12-29T23:00:00-10:00[Pacific/Apia]", "2011-12-31T01:00:00+14:00[Pacific/Apia]") // 2 (2011-12-30 was deleted)
+ * @example intervalOverlappingDaysZoned("2010-11-07T00:00:30-03:00[America/Goose_Bay]", "2010-11-06T23:30:00-04:00[America/Goose_Bay]", "2010-11-07T00:00:30-03:00[America/Goose_Bay]", "2010-11-06T23:30:00-04:00[America/Goose_Bay]") // 2 (the clock fell back into 2010-11-06)
+ * @example diffDate(parseDateFromZoned("2010-11-07T00:00:30-03:00[America/Goose_Bay]"), parseDateFromZoned("2010-11-06T23:30:00-04:00[America/Goose_Bay]"), "days") + 1 // 0 (pre-1.16.0 count)
  * @example intervalOverlappingDaysZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
  */
 export declare function intervalOverlappingDaysZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): number | null;

package/dist/zoned/interval/intervalOverlappingDaysZoned.js

@@ -1,36 +1,43 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { parseCalendarZonedValue } from "../../internal/index.js";
+import { calendarOfAllZonedValues, countZonedLocalDates, halfOpenIntersection, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 /**
  * Return how many distinct calendar dates two zoned intervals share, counted in the
  * first interval's zone.
  *
- * - Counts the number of local dates touched by the closed intersection
- *   `[max(aStart, bStart), min(aEnd, bEnd)]` — inclusive of both endpoints.
+ * - Counts the local dates that hold at least one instant of the half-open intersection
+ *   `[max(aStart, bStart), min(aEnd, bEnd))`. The end is excluded, so an intersection ending at
+ *   local midnight does not touch the date that midnight starts.
  * - `aEnd`, `bStart`, and `bEnd` are re-expressed in `aStart`'s time zone before comparing —
  *   Temporal refuses to compute day-granularity differences directly across two zones, since
  *   day length varies with DST/offset changes. As a result this function is NOT commutative:
  *   swapping the two intervals can change the answer when their zones differ.
- * - Zones whose calendar skips a date entirely (e.g. `Pacific/Apia`'s 2011 dateline change)
- *   still count the skipped date — this matches `intervalCountZoned`'s calendar-arithmetic
- *   rule, so the two functions never disagree about what a day is.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one date and count as `1`.
- * - Returns `0` when the intervals do not overlap at all (a well-defined answer, not
- *   invalid input).
+ * - Each instant in the intersection contributes its own local date, and each date counts once.
+ *   A date the zone deleted is not counted, because no instant has it (`Pacific/Apia` skipped
+ *   2011-12-30). A fall-back that sends the clock back into the previous date does not lose that
+ *   date (`America/Goose_Bay` fell back at 00:01 on 2010-11-07 into 2010-11-06).
+ * - Returns `null` when the intersection crosses more than 10,000 zone transitions (the same cap
+ *   as `intervalCountZoned`).
+ * - Compatibility: before 1.16.0 the count was the calendar difference of the two endpoint dates
+ *   plus one, which counts a deleted date and can be 0 or 1 across a fall-back into the previous
+ *   date. To get that number, with `start`/`end` the intersection endpoints in `aStart`'s zone:
+ *   `diffDate(parseDateFromZoned(start), parseDateFromZoned(end), "days") + 1`.
+ * - Returns `0` when the intersection is empty (a well-defined answer, not invalid input): when the
+ *   intervals are disjoint, when they touch (e.g. `aEnd` the same instant as `bStart`), or when
+ *   either is empty.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` 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 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`.
+ * - Accepts RFC 9557 calendar-annotated zoned strings
+ *   (`"2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]"`; E7, issue #152). All four
+ *   arguments must name the same calendar (a bare string names `iso8601`): the count is a day
+ *   difference, so different calendars return `null`, as Temporal's `until` throws when
+ *   `CalendarEquals` is false. Before 1.16.0 the arguments could name different calendars.
  * - Diverges from date-fns's `getOverlappingDaysInIntervals`, which rounds up elapsed
  *   24-hour periods instead of counting calendar dates. To reproduce date-fns's number,
  *   compose `intervalIntersectionZoned` with `intervalCountZoned`:
  *   `const span = intervalIntersectionZoned(aStart, aEnd, bStart, bEnd); span ? intervalCountZoned(span.start, span.end, "day") : 0;`
+ * - 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 first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -39,20 +46,29 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * @returns number of shared calendar dates (counted in aStart's zone), `0` when disjoint, or null on invalid input
  *
  * @example intervalOverlappingDaysZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", "2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]") // 3 (spring-forward, 47 real hours)
- * @example intervalOverlappingDaysZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "2024-01-03T00:00:00+00:00[UTC]", "2024-01-04T00:00:00+00:00[UTC]") // 0 (disjoint)
+ * @example intervalOverlappingDaysZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "2024-01-03T00:00:00+00:00[UTC]") // 0 (touching: no shared instant)
+ * @example intervalOverlappingDaysZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]") // 1 (the end, 01-02T00:00, is excluded)
+ * @example intervalOverlappingDaysZoned("2011-12-29T23:00:00-10:00[Pacific/Apia]", "2011-12-31T01:00:00+14:00[Pacific/Apia]", "2011-12-29T23:00:00-10:00[Pacific/Apia]", "2011-12-31T01:00:00+14:00[Pacific/Apia]") // 2 (2011-12-30 was deleted)
+ * @example intervalOverlappingDaysZoned("2010-11-07T00:00:30-03:00[America/Goose_Bay]", "2010-11-06T23:30:00-04:00[America/Goose_Bay]", "2010-11-07T00:00:30-03:00[America/Goose_Bay]", "2010-11-06T23:30:00-04:00[America/Goose_Bay]") // 2 (the clock fell back into 2010-11-06)
+ * @example diffDate(parseDateFromZoned("2010-11-07T00:00:30-03:00[America/Goose_Bay]"), parseDateFromZoned("2010-11-06T23:30:00-04:00[America/Goose_Bay]"), "days") + 1 // 0 (pre-1.16.0 count)
  * @example intervalOverlappingDaysZoned("invalid", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // null
  */
 export function intervalOverlappingDaysZoned(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) ||
         !isValidCalendarZonedDateTime(bEnd)) {
         return null;
     }
+    // The count is a day difference between two of the endpoints, so all four must name one
+    // calendar (TC39 CalendarEquals, which makes ZonedDateTime#until throw across calendars).
+    if (calendarOfAllZonedValues([aStart, aEnd, bStart, bEnd]) === null) {
+        return null;
+    }
     try {
         const aS = parseCalendarZonedValue(aStart);
         // Boundaries are counted in the start's zone, so the others are re-expressed there —
@@ -66,22 +82,18 @@ export function intervalOverlappingDaysZoned(aStart, aEnd, bStart, bEnd) {
         if (Temporal.ZonedDateTime.compare(bS, bE) > 0) {
             return null;
         }
-        if (Temporal.ZonedDateTime.compare(aE, bS) < 0 ||
-            Temporal.ZonedDateTime.compare(bE, aS) < 0) {
+        const overlap = halfOpenIntersection({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.ZonedDateTime.compare);
+        if (overlap === null) {
+            return 0;
+        }
+        // An empty intersection [t, t) (an empty interval strictly inside the other) holds no instant,
+        // so it holds no date.
+        if (Temporal.ZonedDateTime.compare(overlap.start, overlap.end) === 0) {
             return 0;
         }
-        const start = Temporal.ZonedDateTime.compare(aS, bS) >= 0 ? aS : bS;
-        const end = Temporal.ZonedDateTime.compare(aE, bE) <= 0 ? aE : bE;
-        // Both operands are normalized to iso8601 immediately before `.until()`. `.compare` above is
-        // calendar-independent, but `PlainDate.prototype.until` is NOT — it throws
-        // `RangeError: cannot compute difference between dates of hebrew and iso8601 calendars`
-        // whenever the two endpoints came from different calendars, which this function explicitly
-        // accepts (E7's D4-zoned). Counting distinct calendar DATES is a Gregorian/ISO question
-        // regardless of how either endpoint was tagged, so normalizing is the right answer, not just
-        // the safe one. Exactly the same hazard `intervalOverlappingDaysDate` hit in E5 (finding 2).
-        const startDate = start.toPlainDate().withCalendar("iso8601");
-        const endDate = end.toPlainDate().withCalendar("iso8601");
-        return startDate.until(endDate, { largestUnit: "day" }).days + 1;
+        // The last instant the half-open intersection holds is one nanosecond before its end, so the
+        // closed local-date count runs to there.
+        return countZonedLocalDates(overlap.start, overlap.end.subtract({ nanoseconds: 1 }));
     }
     catch {
         return null;