@northguild/gmt 1.14.2 → 1.16.0

package/dist/zoned/get/getZonedNowUnit.d.ts

@@ -1,16 +1,44 @@
-export type ZonedNowUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond";
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Units extractable from the current time in a specific IANA timeZone, as
+ * consumed by `getZonedNowUnit`.
+ *
+ * @remarks Members:
+ *
+ * | Member | Description |
+ * | --- | --- |
+ * | `year` | Full calendar year (e.g. `2024`), no padding. |
+ * | `month` | 1–12, zero-padded to 2 digits (e.g. `02`). |
+ * | `week` | Week-of-year from `parseWeekFromDate`, 1–53. |
+ * | `day` | Day of month 1–31, zero-padded (e.g. `15`). |
+ * | `dayOfWeek` | 1 (Mon)–7 (Sun). |
+ * | `hour` | 0–23, zero-padded. |
+ * | `minute` | 0–59, zero-padded. |
+ * | `second` | 0–59, zero-padded. |
+ * | `millisecond` | 0–999, zero-padded to 3. |
+ * | `microsecond` | Microseconds within the millisecond, 0–999, zero-padded to 3. |
+ * | `nanosecond` | Nanoseconds within the microsecond, 0–999, zero-padded to 3. |
+ *
+ * @example
+ * import { ZonedNowUnit } from "@northguild/gmt/zoned";
+ * const u: ZonedNowUnit = "hour";
+ */
+export type ZonedNowUnit = Temporal.SmallestUnit<"year" | "month" | "week" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"> | "dayOfWeek";
 /**
  * Return the requested current unit value for the specified IANA timeZone.
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
- * - Uses weekOfYear helper for week calculations.
+ * - `week` is the ISO 8601 week number, from `parseWeekFromDate`.
  * - Validation is performed on timezone and unit.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
  *
  * @param ianaTimezone IANA timeZone identifier
  * @param unit unit to extract from current zoned time
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example getZonedNowUnit("America/New_York", "hour") // "07"
+ * @example getZonedNowUnit("UTC", "hours") // "14", if the UTC time is 14:xx (plural unit name)
  * @example getZonedNowUnit("invalid", "hour") // ""
  */
 export declare function getZonedNowUnit(ianaTimezone: string, unit: ZonedNowUnit): string;

package/dist/zoned/get/getZonedNowUnit.js

@@ -1,6 +1,8 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { zonedNowUnitValue } from "../../internal/zonedNowUnitValue.js";
 import { parseWeekFromDate } from "../../plain/parse/index.js";
 import { isValidTimeZone } from "../validate/index.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 function isValidZonedNowUnit(unit) {
     return [
         "year",
@@ -20,51 +22,33 @@ function isValidZonedNowUnit(unit) {
  * Return the requested current unit value for the specified IANA timeZone.
  *
  * - Uses Temporal.Now.zonedDateTimeISO to get the current time.
- * - Uses weekOfYear helper for week calculations.
+ * - `week` is the ISO 8601 week number, from `parseWeekFromDate`.
  * - Validation is performed on timezone and unit.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
  *
  * @param ianaTimezone IANA timeZone identifier
  * @param unit unit to extract from current zoned time
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example getZonedNowUnit("America/New_York", "hour") // "07"
+ * @example getZonedNowUnit("UTC", "hours") // "14", if the UTC time is 14:xx (plural unit name)
  * @example getZonedNowUnit("invalid", "hour") // ""
  */
 export function getZonedNowUnit(ianaTimezone, unit) {
-    if (!isValidTimeZone(ianaTimezone) ||
-        !isValidZonedNowUnit(String(unit ?? ""))) {
+    if (typeof unit !== "string") {
+        return "";
+    }
+    const resolvedUnit = resolveDateTimeUnit(unit);
+    if (!isValidTimeZone(ianaTimezone) || !isValidZonedNowUnit(resolvedUnit)) {
         return "";
     }
     try {
         const now = Temporal.Now.zonedDateTimeISO(ianaTimezone);
-        switch (unit) {
-            case "year":
-                return now.year.toString();
-            case "month":
-                return now.month.toString().padStart(2, "0");
-            case "week": {
-                const w = parseWeekFromDate(now.toPlainDate().toString());
-                return w === null ? "" : w.toString();
-            }
-            case "day":
-                return now.day.toString().padStart(2, "0");
-            case "dayOfWeek":
-                return now.dayOfWeek.toString();
-            case "hour":
-                return now.hour.toString().padStart(2, "0");
-            case "minute":
-                return now.minute.toString().padStart(2, "0");
-            case "second":
-                return now.second.toString().padStart(2, "0");
-            case "millisecond":
-                return now.millisecond.toString().padStart(3, "0");
-            case "microsecond":
-                return (now.microsecond ?? 0).toString().padStart(3, "0");
-            case "nanosecond":
-                return (now.nanosecond ?? 0).toString().padStart(3, "0");
-            default:
-                return "";
-        }
+        return zonedNowUnitValue(now, resolvedUnit, (zdt) => {
+            const w = parseWeekFromDate(zdt.toPlainDate().toString());
+            return w === null ? "" : w.toString();
+        });
     }
     catch {
         return "";

package/dist/zoned/index.js

@@ -1,4 +1,4 @@
-// Re-export all Temporal polyfill functionality for zoned DateTime operations
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
 export * from "@js-temporal/polyfill";
 export * from "./calculate/index.js";
 export * from "./chop/index.js";

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

@@ -1,19 +1,26 @@
 /**
- * Return true when two zoned intervals are exactly adjacent — one's end equals the other's
- * start with zero gap and zero overlap.
+ * Return true when two half-open zoned intervals `[start, end)` are exactly adjacent — one ends at
+ * the instant the other starts, so they share no instant and leave no gap (Allen's "meets", either
+ * order).
  *
- * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
- * - Returns `true` when `aEnd + 1 nanosecond === bStart` or `bEnd + 1 nanosecond === aStart`.
- * - Returns `false` when intervals overlap, are disjoint with a gap, or are invalid.
+ * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`), so the shared instant may
+ *   be spelled in different zones.
+ * - Returns `true` when `aEnd` is the same instant as `bStart`, or `bEnd` the same instant as
+ *   `aStart`, and neither interval is empty. No instant is stepped by a nanosecond, so an interval
+ *   ending at the last representable instant is handled like any other.
+ * - Returns `false` when intervals overlap, are disjoint with a gap (even one nanosecond), are
+ *   invalid, or when either is empty (`start` and `end` the same instant): an empty interval abuts
+ *   nothing.
  * - 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 first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -21,9 +28,9 @@
  * @param bEnd ISO 8601 zoned datetime string for the second interval end
  * @returns true if intervals are exactly adjacent, or false on invalid input
  *
- * @example intervalAbutsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:00.000000001+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // true
- * @example intervalAbutsZoned("2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00.000000001+00:00[UTC]") // true
- * @example intervalAbutsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:01+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // false (gap)
+ * @example intervalAbutsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // true
+ * @example intervalAbutsZoned("2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T08:00:00-04:00[America/New_York]") // true (the same instant in another zone)
+ * @example intervalAbutsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:00.000000001+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // false (one-nanosecond gap)
  * @example intervalAbutsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T13:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // false (overlap)
  * @example intervalAbutsZoned("invalid", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // false
  */

package/dist/zoned/interval/intervalAbutsZoned.js

@@ -1,22 +1,30 @@
+// 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 { halfOpenAbuts, parseCalendarZonedValue } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 /**
- * Return true when two zoned intervals are exactly adjacent — one's end equals the other's
- * start with zero gap and zero overlap.
+ * Return true when two half-open zoned intervals `[start, end)` are exactly adjacent — one ends at
+ * the instant the other starts, so they share no instant and leave no gap (Allen's "meets", either
+ * order).
  *
- * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`).
- * - Returns `true` when `aEnd + 1 nanosecond === bStart` or `bEnd + 1 nanosecond === aStart`.
- * - Returns `false` when intervals overlap, are disjoint with a gap, or are invalid.
+ * - Uses `Temporal.Instant.compare` for comparison (via `.toInstant()`), so the shared instant may
+ *   be spelled in different zones.
+ * - Returns `true` when `aEnd` is the same instant as `bStart`, or `bEnd` the same instant as
+ *   `aStart`, and neither interval is empty. No instant is stepped by a nanosecond, so an interval
+ *   ending at the last representable instant is handled like any other.
+ * - Returns `false` when intervals overlap, are disjoint with a gap (even one nanosecond), are
+ *   invalid, or when either is empty (`start` and `end` the same instant): an empty interval abuts
+ *   nothing.
  * - 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 first interval start
  * @param aEnd ISO 8601 zoned datetime string for the first interval end
@@ -24,17 +32,17 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * @param bEnd ISO 8601 zoned datetime string for the second interval end
  * @returns true if intervals are exactly adjacent, or false on invalid input
  *
- * @example intervalAbutsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:00.000000001+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // true
- * @example intervalAbutsZoned("2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00.000000001+00:00[UTC]") // true
- * @example intervalAbutsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:01+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // false (gap)
+ * @example intervalAbutsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // true
+ * @example intervalAbutsZoned("2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]", "2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T08:00:00-04:00[America/New_York]") // true (the same instant in another zone)
+ * @example intervalAbutsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:00.000000001+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // false (one-nanosecond gap)
  * @example intervalAbutsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-06-30T13:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // false (overlap)
  * @example intervalAbutsZoned("invalid", "2024-06-30T12:00:00+00:00[UTC]", "2024-06-30T12:00:00+00:00[UTC]", "2024-12-31T17:00:00+00:00[UTC]") // false
  */
 export function intervalAbutsZoned(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,17 +64,8 @@ export function intervalAbutsZoned(aStart, aEnd, bStart, bEnd) {
         if (Temporal.Instant.compare(bS, bE) > 0) {
             return false;
         }
-        // aEnd + 1 nanosecond === bStart
-        const aEndPlusOne = aE.add({ nanoseconds: 1 });
-        if (Temporal.Instant.compare(aEndPlusOne, bS) === 0) {
-            return true;
-        }
-        // bEnd + 1 nanosecond === aStart
-        const bEndPlusOne = bE.add({ nanoseconds: 1 });
-        if (Temporal.Instant.compare(bEndPlusOne, aS) === 0) {
-            return true;
-        }
-        return false;
+        // aEnd is bStart, or bEnd is aStart, between two non-empty intervals.
+        return halfOpenAbuts({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.Instant.compare);
     }
     catch {
         return false;

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

@@ -1,21 +1,28 @@
 /**
- * Return true when `pointOrStart` falls within the interval `[intervalStart, intervalEnd]`
- * (3-arg), or when the inner interval `[innerStart, innerEnd]` is fully contained within
- * the outer interval `[intervalStart, intervalEnd]` (4-arg).
+ * Return true when `pointOrStart` falls within the half-open interval
+ * `[intervalStart, intervalEnd)` (3-arg), or when the inner interval `[innerStart, innerEnd)` lies
+ * within the outer interval `[intervalStart, intervalEnd)` (4-arg).
  *
  * - Uses `Temporal.Instant.compare` for comparison (same instant semantics).
- * - Always-inclusive boundaries: `start <= point <= end`.
+ * - Point mode: `start <= point < end`, the same rule as `intervalContains`. The `end` is
+ *   excluded, so a point at `end`'s instant returns `false`, and an empty interval (`start` and
+ *   `end` the same instant) contains no point.
+ * - Interval mode: the intervals overlap and `start <= innerStart` and `innerEnd <= end`. An inner
+ *   interval may share the outer `end`. An empty inner interval counts only strictly inside the
+ *   outer interval, the same edge rule as `clampInterval`, and an empty outer interval contains
+ *   nothing.
  * - Returns `false` if `intervalStart > intervalEnd` (invalid outer interval).
  * - Returns `false` if `innerStart > innerEnd` in 4-arg mode (invalid inner interval).
  * - 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 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 intervalStart ISO 8601 zoned datetime string for the outer interval start
  * @param intervalEnd ISO 8601 zoned datetime string for the outer interval end
@@ -25,6 +32,8 @@
  *
  * @example intervalContainsZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]", "2024-06-15T12:00:00+00:00[UTC]") // true
  * @example intervalContainsZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]", "2024-06-15T12:00:00+00:00[UTC]", "2024-07-15T12:00:00+00:00[UTC]") // true
+ * @example intervalContainsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]") // false (the end is excluded)
+ * @example intervalContainsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T17:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T17:00:00+00:00[UTC]") // true (the inner interval shares the end)
  * @example intervalContainsZoned("2024-12-31T23:59:59+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "2024-06-15T12:00:00+00:00[UTC]") // false
  * @example intervalContainsZoned("invalid", "2024-12-31T23:59:59+00:00[UTC]", "2024-06-15T12:00:00+00:00[UTC]") // false
  */

package/dist/zoned/interval/intervalContainsZoned.js

@@ -1,24 +1,31 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { parseCalendarZonedValue } from "../../internal/index.js";
+import { halfOpenContainsPoint, halfOpenContainsSpan, parseCalendarZonedValue, } from "../../internal/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
 /**
- * Return true when `pointOrStart` falls within the interval `[intervalStart, intervalEnd]`
- * (3-arg), or when the inner interval `[innerStart, innerEnd]` is fully contained within
- * the outer interval `[intervalStart, intervalEnd]` (4-arg).
+ * Return true when `pointOrStart` falls within the half-open interval
+ * `[intervalStart, intervalEnd)` (3-arg), or when the inner interval `[innerStart, innerEnd)` lies
+ * within the outer interval `[intervalStart, intervalEnd)` (4-arg).
  *
  * - Uses `Temporal.Instant.compare` for comparison (same instant semantics).
- * - Always-inclusive boundaries: `start <= point <= end`.
+ * - Point mode: `start <= point < end`, the same rule as `intervalContains`. The `end` is
+ *   excluded, so a point at `end`'s instant returns `false`, and an empty interval (`start` and
+ *   `end` the same instant) contains no point.
+ * - Interval mode: the intervals overlap and `start <= innerStart` and `innerEnd <= end`. An inner
+ *   interval may share the outer `end`. An empty inner interval counts only strictly inside the
+ *   outer interval, the same edge rule as `clampInterval`, and an empty outer interval contains
+ *   nothing.
  * - Returns `false` if `intervalStart > intervalEnd` (invalid outer interval).
  * - Returns `false` if `innerStart > innerEnd` in 4-arg mode (invalid inner interval).
  * - 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 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 intervalStart ISO 8601 zoned datetime string for the outer interval start
  * @param intervalEnd ISO 8601 zoned datetime string for the outer interval end
@@ -28,14 +35,16 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  *
  * @example intervalContainsZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]", "2024-06-15T12:00:00+00:00[UTC]") // true
  * @example intervalContainsZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]", "2024-06-15T12:00:00+00:00[UTC]", "2024-07-15T12:00:00+00:00[UTC]") // true
+ * @example intervalContainsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]") // false (the end is excluded)
+ * @example intervalContainsZoned("2024-01-01T09:00:00+00:00[UTC]", "2024-01-01T17:00:00+00:00[UTC]", "2024-01-01T12:00:00+00:00[UTC]", "2024-01-01T17:00:00+00:00[UTC]") // true (the inner interval shares the end)
  * @example intervalContainsZoned("2024-12-31T23:59:59+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "2024-06-15T12:00:00+00:00[UTC]") // false
  * @example intervalContainsZoned("invalid", "2024-12-31T23:59:59+00:00[UTC]", "2024-06-15T12:00:00+00:00[UTC]") // false
  */
 export function intervalContainsZoned(intervalStart, intervalEnd, pointOrStart, pointEnd) {
     // One gate per endpoint: `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. `pointEnd` is optional, so it is only checked when supplied.
+    // and a calendar annotation before the zone — and, unlike `isValidZonedDateTime`, accepts
+    // RFC 9557 calendar annotations. `pointEnd` is optional, so it is only checked when supplied.
     if (!isValidCalendarZonedDateTime(intervalStart) ||
         !isValidCalendarZonedDateTime(intervalEnd) ||
         !isValidCalendarZonedDateTime(pointOrStart) ||
@@ -52,17 +61,16 @@ export function intervalContainsZoned(intervalStart, intervalEnd, pointOrStart,
         if (Temporal.Instant.compare(startInstant, endInstant) > 0) {
             return false;
         }
+        const outer = { start: startInstant, end: endInstant };
         if (pointEnd === undefined) {
-            return (Temporal.Instant.compare(startInstant, pointInstant) <= 0 &&
-                Temporal.Instant.compare(pointInstant, endInstant) <= 0);
+            return halfOpenContainsPoint(outer, pointInstant, Temporal.Instant.compare);
         }
         const endPointZdt = parseCalendarZonedValue(pointEnd);
         const endPointInstant = endPointZdt.toInstant();
         if (Temporal.Instant.compare(pointInstant, endPointInstant) > 0) {
             return false;
         }
-        return (Temporal.Instant.compare(startInstant, pointInstant) <= 0 &&
-            Temporal.Instant.compare(endPointInstant, endInstant) <= 0);
+        return halfOpenContainsSpan(outer, { start: pointInstant, end: endPointInstant }, Temporal.Instant.compare);
     }
     catch {
         return false;

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

@@ -4,23 +4,31 @@
  * - Counts local calendar boundaries touched by the half-open interval `[start, end)` —
  *   distinct from `diffZoned`, which measures exact elapsed duration.
  * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
- * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
- *   unit boundary.
+ * - A zero-length interval (`start === end`) returns `0`: the empty `[start, start)` holds no instant,
+ *   so it touches no unit (before 1.16.0 it counted 1 when mid-unit).
  * - DST-aware: a local day that springs forward counts 23 hour boundaries and one that falls
  *   back counts 25. A local day whose midnight is skipped entirely starts at 01:00.
  * - A fixed 24-hour span touches 25 local hour boundaries in zones offset by :30/:45.
+ * - Counts the real local buckets `floorToZone`/`bucketRange` walk: a bucket shorter than its
+ *   unit still counts once (`Pacific/Chatham`'s 15-minute 03:00 hour on its spring-forward),
+ *   and a local day the zone deleted counts not at all (`Pacific/Apia`'s 2011-12-30).
+ * - The count equals `bucketRange(...).length` wherever `bucketRange` is within its 10,000-bucket
+ *   cap. Counting has its own, separate cap of 10,000 zone transitions, so it keeps answering past
+ *   `bucketRange`'s: two years by hour counts 17,544 while `bucketRange` returns `[]`.
+ * - Returns `null` when the span crosses more than 10,000 zone transitions.
  * - When `start` and `end` carry different time zones, boundaries are counted in `start`'s zone.
  * - Weeks start on Monday (ISO 8601).
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
- * - 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). 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
@@ -31,9 +39,9 @@
  * @example intervalCountZoned("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 intervalCountZoned("2024-11-03T00:00:00-04:00[America/New_York]", "2024-11-04T00:00:00-05:00[America/New_York]", "hour") // 25 (fall back)
  * @example intervalCountZoned("2024-01-01T00:00:00-05:00[America/New_York]", "2024-01-03T00:00:00+09:00[Asia/Tokyo]", "day") // 2 (counted in America/New_York)
- * @example intervalCountZoned("2024-01-01T05:00:00+00:00[UTC]", "2024-01-01T05:00:00+00:00[UTC]", "day") // 1 (zero-length, mid-day)
- * @example intervalCountZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "day") // 0 (zero-length, on the boundary)
- * @example intervalCountZoned("5784-01-01T00:00:00-04:00[u-ca=hebrew][America/New_York]", "5785-01-01T00:00:00-04:00[u-ca=hebrew][America/New_York]", "month") // 13 (Hebrew leap year; the ISO equivalent is 14)
+ * @example intervalCountZoned("2024-01-01T05:00:00+00:00[UTC]", "2024-01-01T05:00:00+00:00[UTC]", "day") // 0 (zero-length: holds no instant)
+ * @example intervalCountZoned("2023-09-16T00:00:00-04:00[America/New_York][u-ca=hebrew]", "2024-10-03T00:00:00-04:00[America/New_York][u-ca=hebrew]", "month") // 13 (Hebrew leap year; the ISO equivalent is 14)
  * @example intervalCountZoned("invalid", "2024-01-02T00:00:00+00:00[UTC]", "day") // null
+ * @example intervalCountZoned("-271821-04-20T00:00:00+00:00[UTC]", "-271821-04-20T01:00:00+00:00[UTC]", "week") // 1 (the week began before the first instant, but is still touched)
  */
 export declare function intervalCountZoned(start: string, end: string, unit: string): number | null;

package/dist/zoned/interval/intervalCountZoned.js

@@ -1,5 +1,6 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { getStartOfZonedUnit, getUnitSpan, parseCalendarZonedPairForArithmetic, resolveDateTimeUnit, } from "../../internal/index.js";
+import { countZonedBuckets, parseCalendarZonedPairForArithmetic, resolveDateTimeUnit, } from "../../internal/index.js";
 import { isValidDateTimeUnit } from "../../plain/validate/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/isValidCalendarZonedDateTime.js";
 /**
@@ -8,23 +9,31 @@ import { isValidCalendarZonedDateTime } from "../validate/isValidCalendarZonedDa
  * - Counts local calendar boundaries touched by the half-open interval `[start, end)` —
  *   distinct from `diffZoned`, which measures exact elapsed duration.
  * - The end boundary is excluded: midnight to midnight two days later counts 2 days.
- * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
- *   unit boundary.
+ * - A zero-length interval (`start === end`) returns `0`: the empty `[start, start)` holds no instant,
+ *   so it touches no unit (before 1.16.0 it counted 1 when mid-unit).
  * - DST-aware: a local day that springs forward counts 23 hour boundaries and one that falls
  *   back counts 25. A local day whose midnight is skipped entirely starts at 01:00.
  * - A fixed 24-hour span touches 25 local hour boundaries in zones offset by :30/:45.
+ * - Counts the real local buckets `floorToZone`/`bucketRange` walk: a bucket shorter than its
+ *   unit still counts once (`Pacific/Chatham`'s 15-minute 03:00 hour on its spring-forward),
+ *   and a local day the zone deleted counts not at all (`Pacific/Apia`'s 2011-12-30).
+ * - The count equals `bucketRange(...).length` wherever `bucketRange` is within its 10,000-bucket
+ *   cap. Counting has its own, separate cap of 10,000 zone transitions, so it keeps answering past
+ *   `bucketRange`'s: two years by hour counts 17,544 while `bucketRange` returns `[]`.
+ * - Returns `null` when the span crosses more than 10,000 zone transitions.
  * - When `start` and `end` carry different time zones, boundaries are counted in `start`'s zone.
  * - Weeks start on Monday (ISO 8601).
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
- * - 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). 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
@@ -35,10 +44,10 @@ import { isValidCalendarZonedDateTime } from "../validate/isValidCalendarZonedDa
  * @example intervalCountZoned("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 intervalCountZoned("2024-11-03T00:00:00-04:00[America/New_York]", "2024-11-04T00:00:00-05:00[America/New_York]", "hour") // 25 (fall back)
  * @example intervalCountZoned("2024-01-01T00:00:00-05:00[America/New_York]", "2024-01-03T00:00:00+09:00[Asia/Tokyo]", "day") // 2 (counted in America/New_York)
- * @example intervalCountZoned("2024-01-01T05:00:00+00:00[UTC]", "2024-01-01T05:00:00+00:00[UTC]", "day") // 1 (zero-length, mid-day)
- * @example intervalCountZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "day") // 0 (zero-length, on the boundary)
- * @example intervalCountZoned("5784-01-01T00:00:00-04:00[u-ca=hebrew][America/New_York]", "5785-01-01T00:00:00-04:00[u-ca=hebrew][America/New_York]", "month") // 13 (Hebrew leap year; the ISO equivalent is 14)
+ * @example intervalCountZoned("2024-01-01T05:00:00+00:00[UTC]", "2024-01-01T05:00:00+00:00[UTC]", "day") // 0 (zero-length: holds no instant)
+ * @example intervalCountZoned("2023-09-16T00:00:00-04:00[America/New_York][u-ca=hebrew]", "2024-10-03T00:00:00-04:00[America/New_York][u-ca=hebrew]", "month") // 13 (Hebrew leap year; the ISO equivalent is 14)
  * @example intervalCountZoned("invalid", "2024-01-02T00:00:00+00:00[UTC]", "day") // null
+ * @example intervalCountZoned("-271821-04-20T00:00:00+00:00[UTC]", "-271821-04-20T01:00:00+00:00[UTC]", "week") // 1 (the week began before the first instant, but is still touched)
  */
 export function intervalCountZoned(start, end, unit) {
     if (!isValidCalendarZonedDateTime(start) ||
@@ -53,28 +62,24 @@ export function intervalCountZoned(start, end, unit) {
         return null;
     }
     try {
-        // The pair is resolved BEFORE either endpoint reaches `getStartOfZonedUnit`. Normalizing only
-        // one side would leave `startOfStart.until(startOfEnd)` throwing on a mismatched pair
-        // (verified), so the D5 policy has to be applied to both operands together, up front.
+        // The pair is resolved BEFORE either endpoint reaches `countZonedBuckets`: a pair naming
+        // different calendars throws here (TC39 CalendarEquals) and returns the sentinel.
         const { a: startVal, b: pairedEnd } = parseCalendarZonedPairForArithmetic(start, end);
         // Boundaries are counted in the start's zone, so the end is re-expressed there.
         // Temporal refuses calendar-unit differences across two zones outright. `withTimeZone`
         // preserves the calendar tag (verified), so this does not undo the pair normalization above.
         const endVal = pairedEnd.withTimeZone(startVal.timeZoneId);
-        if (Temporal.ZonedDateTime.compare(startVal, endVal) > 0) {
+        const order = Temporal.ZonedDateTime.compare(startVal, endVal);
+        if (order > 0) {
             return null;
         }
-        const startOfStart = getStartOfZonedUnit(startVal, resolvedUnit);
-        const startOfEnd = getStartOfZonedUnit(endVal, resolvedUnit);
-        const spanned = getUnitSpan(startOfStart.until(startOfEnd, { largestUnit: resolvedUnit }), resolvedUnit);
-        // `.equals()` here IS calendar-sensitive — it is `ZonedDateTime.prototype.equals`, and
-        // `iso.equals(heb)` is `false` even at the same instant (verified). It is safe only by
-        // construction: `startOfEnd` is derived from `endVal` one line above
-        // (`getStartOfZonedUnit(endVal, resolvedUnit)`), so the two always share `endVal`'s calendar
-        // by definition of how `startOfEnd` is built. A refactor that hoists `endVal` out, or that
-        // sources `startOfEnd` from anywhere but `endVal`, breaks this silently — compare instants
-        // (or re-derive `startOfEnd` from `endVal`) if that ever happens.
-        return spanned + (startOfEnd.equals(endVal) ? 0 : 1);
+        // An empty interval [t, t) holds no instant, so it touches no unit (CORE-6 empty-interval rule).
+        if (order === 0) {
+            return 0;
+        }
+        // The walker keeps the pair's calendar, so a Hebrew month or year is counted in Hebrew
+        // months or years, and it compares instants, never calendar-sensitive `.equals()`.
+        return countZonedBuckets(startVal, endVal, resolvedUnit);
     }
     catch {
         return null;

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

@@ -1,13 +1,19 @@
 /**
- * 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.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals 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
@@ -19,8 +25,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
@@ -28,7 +33,8 @@
  * @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-05-31T17:00:00+00:00[UTC]" }, { start: "2024-07-01T13:00:01+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]") // []
  */