@northguild/gmt 1.15.0 → 1.17.0

package/dist/plain/interval/intervalIntersectionDate.js

@@ -1,14 +1,20 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { calendarOfAllDateValues, formatDateInCalendar, parseCalendarDateValue, } from "../../internal/index.js";
+import { calendarOfAllDateValues, formatDateInCalendar, halfOpenIntersection, parseCalendarDateValue, } from "../../internal/index.js";
 import { isValidCalendarDate } from "../validate/index.js";
 /**
  * Return the overlapping span of two date intervals, or null when they do not overlap.
  *
  * - Uses `Temporal.PlainDate.compare` for comparison.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The intersection is
+ *   `[max(aStart, bStart), min(aEnd, bEnd))` when `aStart < bEnd && bStart < aEnd` (CORE-6's
+ *   `intersectIntervals`), otherwise `null`.
+ * - Touching intervals (`aEnd === bStart`) share no day and return `null`.
+ * - An empty interval (`start === end`) intersects only an interval it lies strictly inside, and
+ *   then returns itself.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Since the result is a
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). Since the result is a
  *   date *value*, all four arguments must carry the *same* calendar tag (or all be bare ISO);
  *   a mismatch returns `null` (E5 decision of record D4). The output's tag is re-derived from
  *   the intersection span, never copied from an input.
@@ -20,8 +26,8 @@ import { isValidCalendarDate } from "../validate/index.js";
  * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap / mismatched calendars
  *
  * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // { start: "2024-04-01", end: "2024-06-30" }
- * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // { start: "2024-06-30", end: "2024-06-30" }
- * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // null
+ * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-06-29", "2024-12-31") // { start: "2024-06-29", end: "2024-06-30" } (one shared day)
+ * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // null (touching)
  * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-02-01", "2024-03-01") // { start: "2024-02-01", end: "2024-03-01" }
  * @example intervalIntersectionDate("invalid", "2024-06-30", "2024-04-01", "2024-12-31") // null
  */
@@ -53,12 +59,11 @@ export function intervalIntersectionDate(aStart, aEnd, bStart, bEnd) {
         if (Temporal.PlainDate.compare(bS, bE) > 0) {
             return null;
         }
-        if (Temporal.PlainDate.compare(aE, bS) < 0 ||
-            Temporal.PlainDate.compare(bE, aS) < 0) {
+        const shared = halfOpenIntersection({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.PlainDate.compare);
+        if (shared === null) {
             return null;
         }
-        const start = Temporal.PlainDate.compare(aS, bS) >= 0 ? aS : bS;
-        const end = Temporal.PlainDate.compare(aE, bE) <= 0 ? aE : bE;
+        const { start, end } = shared;
         return {
             start: formatDateInCalendar(start, calendar),
             end: formatDateInCalendar(end, calendar),

package/dist/plain/interval/intervalIntersectionDateTime.d.ts

@@ -2,7 +2,12 @@
  * Return the overlapping span of two datetime intervals, or null when they do not overlap.
  *
  * - Uses `Temporal.PlainDateTime.compare` for comparison.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The intersection is
+ *   `[max(aStart, bStart), min(aEnd, bEnd))` when `aStart < bEnd && bStart < aEnd` (CORE-6's
+ *   `intersectIntervals`), otherwise `null`.
+ * - Touching intervals (`aEnd === bStart`) share no moment and return `null`.
+ * - An empty interval (`start === end`) intersects only an interval it lies strictly inside, and
+ *   then returns itself.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
  *
@@ -12,9 +17,9 @@
  * @param bEnd ISO 8601 datetime string for the second interval end
  * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap
  *
- * @example intervalIntersectionDateTime("2024-01-01T10:00:00", "2024-06-30T23:59:59", "2024-04-01T00:00:00", "2024-12-31T23:59:59") // { start: "2024-04-01T00:00:00", end: "2024-06-30T23:59:59" }
- * @example intervalIntersectionDateTime("2024-01-01T10:00:00", "2024-06-30T23:59:59", "2024-07-01T00:00:00", "2024-12-31T23:59:59") // null
- * @example intervalIntersectionDateTime("2024-01-01T10:00:00", "2024-06-30T23:59:59", "2024-07-02T00:00:00", "2024-12-31T23:59:59") // null
+ * @example intervalIntersectionDateTime("2024-01-01T09:00:00", "2024-01-01T13:00:00", "2024-01-01T12:00:00", "2024-01-01T17:00:00") // { start: "2024-01-01T12:00:00", end: "2024-01-01T13:00:00" }
+ * @example intervalIntersectionDateTime("2024-01-01T09:00:00", "2024-01-01T12:00:00", "2024-01-01T12:00:00", "2024-01-01T17:00:00") // null (touching)
+ * @example intervalIntersectionDateTime("2024-01-01T09:00:00", "2024-01-01T17:00:00", "2024-01-01T12:00:00", "2024-01-01T12:00:00") // { start: "2024-01-01T12:00:00", end: "2024-01-01T12:00:00" } (empty interval strictly inside)
  * @example intervalIntersectionDateTime("invalid", "2024-06-30T23:59:59", "2024-04-01T00:00:00", "2024-12-31T23:59:59") // null
  */
 export declare function intervalIntersectionDateTime(aStart: string, aEnd: string, bStart: string, bEnd: string): {

package/dist/plain/interval/intervalIntersectionDateTime.js

@@ -1,10 +1,17 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { plainDateTime } from "../../regex/index.js";
+import { halfOpenIntersection } from "../../internal/index.js";
+import { isValidDateTime } from "../validate/index.js";
 /**
  * Return the overlapping span of two datetime intervals, or null when they do not overlap.
  *
  * - Uses `Temporal.PlainDateTime.compare` for comparison.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The intersection is
+ *   `[max(aStart, bStart), min(aEnd, bEnd))` when `aStart < bEnd && bStart < aEnd` (CORE-6's
+ *   `intersectIntervals`), otherwise `null`.
+ * - Touching intervals (`aEnd === bStart`) share no moment and return `null`.
+ * - An empty interval (`start === end`) intersects only an interval it lies strictly inside, and
+ *   then returns itself.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
  *
@@ -14,9 +21,9 @@ import { plainDateTime } from "../../regex/index.js";
  * @param bEnd ISO 8601 datetime string for the second interval end
  * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap
  *
- * @example intervalIntersectionDateTime("2024-01-01T10:00:00", "2024-06-30T23:59:59", "2024-04-01T00:00:00", "2024-12-31T23:59:59") // { start: "2024-04-01T00:00:00", end: "2024-06-30T23:59:59" }
- * @example intervalIntersectionDateTime("2024-01-01T10:00:00", "2024-06-30T23:59:59", "2024-07-01T00:00:00", "2024-12-31T23:59:59") // null
- * @example intervalIntersectionDateTime("2024-01-01T10:00:00", "2024-06-30T23:59:59", "2024-07-02T00:00:00", "2024-12-31T23:59:59") // null
+ * @example intervalIntersectionDateTime("2024-01-01T09:00:00", "2024-01-01T13:00:00", "2024-01-01T12:00:00", "2024-01-01T17:00:00") // { start: "2024-01-01T12:00:00", end: "2024-01-01T13:00:00" }
+ * @example intervalIntersectionDateTime("2024-01-01T09:00:00", "2024-01-01T12:00:00", "2024-01-01T12:00:00", "2024-01-01T17:00:00") // null (touching)
+ * @example intervalIntersectionDateTime("2024-01-01T09:00:00", "2024-01-01T17:00:00", "2024-01-01T12:00:00", "2024-01-01T12:00:00") // { start: "2024-01-01T12:00:00", end: "2024-01-01T12:00:00" } (empty interval strictly inside)
  * @example intervalIntersectionDateTime("invalid", "2024-06-30T23:59:59", "2024-04-01T00:00:00", "2024-12-31T23:59:59") // null
  */
 export function intervalIntersectionDateTime(aStart, aEnd, bStart, bEnd) {
@@ -26,10 +33,10 @@ export function intervalIntersectionDateTime(aStart, aEnd, bStart, bEnd) {
         typeof bEnd !== "string") {
         return null;
     }
-    if (!plainDateTime.test(aStart) ||
-        !plainDateTime.test(aEnd) ||
-        !plainDateTime.test(bStart) ||
-        !plainDateTime.test(bEnd)) {
+    if (!isValidDateTime(aStart) ||
+        !isValidDateTime(aEnd) ||
+        !isValidDateTime(bStart) ||
+        !isValidDateTime(bEnd)) {
         return null;
     }
     try {
@@ -43,12 +50,11 @@ export function intervalIntersectionDateTime(aStart, aEnd, bStart, bEnd) {
         if (Temporal.PlainDateTime.compare(bS, bE) > 0) {
             return null;
         }
-        if (Temporal.PlainDateTime.compare(aE, bS) < 0 ||
-            Temporal.PlainDateTime.compare(bE, aS) < 0) {
+        const shared = halfOpenIntersection({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.PlainDateTime.compare);
+        if (shared === null) {
             return null;
         }
-        const start = Temporal.PlainDateTime.compare(aS, bS) >= 0 ? aS : bS;
-        const end = Temporal.PlainDateTime.compare(aE, bE) <= 0 ? aE : bE;
+        const { start, end } = shared;
         return { start: start.toString(), end: end.toString() };
     }
     catch {

package/dist/plain/interval/intervalIntersectionTime.d.ts

@@ -2,7 +2,12 @@
  * Return the overlapping span of two time intervals, or null when they do not overlap.
  *
  * - Uses `Temporal.PlainTime.compare` for comparison.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The intersection is
+ *   `[max(aStart, bStart), min(aEnd, bEnd))` when `aStart < bEnd && bStart < aEnd` (CORE-6's
+ *   `intersectIntervals`), otherwise `null`.
+ * - Touching intervals (`aEnd === bStart`) share no clock time and return `null`.
+ * - An empty interval (`start === end`) intersects only an interval it lies strictly inside, and
+ *   then returns itself.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
  *
@@ -13,8 +18,7 @@
  * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap
  *
  * @example intervalIntersectionTime("09:00:00", "17:00:00", "12:00:00", "18:00:00") // { start: "12:00:00", end: "17:00:00" }
- * @example intervalIntersectionTime("09:00:00", "17:00:00", "17:00:00", "18:00:00") // { start: "17:00:00", end: "17:00:00" }
- * @example intervalIntersectionTime("09:00:00", "17:00:00", "18:00:00", "20:00:00") // null
+ * @example intervalIntersectionTime("09:00:00", "17:00:00", "17:00:00", "18:00:00") // null (touching)
  * @example intervalIntersectionTime("09:00:00", "17:00:00", "10:00:00", "11:00:00") // { start: "10:00:00", end: "11:00:00" }
  * @example intervalIntersectionTime("invalid", "17:00:00", "12:00:00", "18:00:00") // null
  */

package/dist/plain/interval/intervalIntersectionTime.js

@@ -1,10 +1,17 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { plainTime } from "../../regex/index.js";
+import { halfOpenIntersection } from "../../internal/index.js";
+import { isValidTime } from "../validate/index.js";
 /**
  * Return the overlapping span of two time intervals, or null when they do not overlap.
  *
  * - Uses `Temporal.PlainTime.compare` for comparison.
- * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The intersection is
+ *   `[max(aStart, bStart), min(aEnd, bEnd))` when `aStart < bEnd && bStart < aEnd` (CORE-6's
+ *   `intersectIntervals`), otherwise `null`.
+ * - Touching intervals (`aEnd === bStart`) share no clock time and return `null`.
+ * - An empty interval (`start === end`) intersects only an interval it lies strictly inside, and
+ *   then returns itself.
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
  *
@@ -15,8 +22,7 @@ import { plainTime } from "../../regex/index.js";
  * @returns `{ start, end }` with the overlapping span, or null on invalid input / no overlap
  *
  * @example intervalIntersectionTime("09:00:00", "17:00:00", "12:00:00", "18:00:00") // { start: "12:00:00", end: "17:00:00" }
- * @example intervalIntersectionTime("09:00:00", "17:00:00", "17:00:00", "18:00:00") // { start: "17:00:00", end: "17:00:00" }
- * @example intervalIntersectionTime("09:00:00", "17:00:00", "18:00:00", "20:00:00") // null
+ * @example intervalIntersectionTime("09:00:00", "17:00:00", "17:00:00", "18:00:00") // null (touching)
  * @example intervalIntersectionTime("09:00:00", "17:00:00", "10:00:00", "11:00:00") // { start: "10:00:00", end: "11:00:00" }
  * @example intervalIntersectionTime("invalid", "17:00:00", "12:00:00", "18:00:00") // null
  */
@@ -27,10 +33,10 @@ export function intervalIntersectionTime(aStart, aEnd, bStart, bEnd) {
         typeof bEnd !== "string") {
         return null;
     }
-    if (!plainTime.test(aStart) ||
-        !plainTime.test(aEnd) ||
-        !plainTime.test(bStart) ||
-        !plainTime.test(bEnd)) {
+    if (!isValidTime(aStart) ||
+        !isValidTime(aEnd) ||
+        !isValidTime(bStart) ||
+        !isValidTime(bEnd)) {
         return null;
     }
     try {
@@ -44,12 +50,11 @@ export function intervalIntersectionTime(aStart, aEnd, bStart, bEnd) {
         if (Temporal.PlainTime.compare(bS, bE) > 0) {
             return null;
         }
-        if (Temporal.PlainTime.compare(aE, bS) < 0 ||
-            Temporal.PlainTime.compare(bE, aS) < 0) {
+        const shared = halfOpenIntersection({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.PlainTime.compare);
+        if (shared === null) {
             return null;
         }
-        const start = Temporal.PlainTime.compare(aS, bS) >= 0 ? aS : bS;
-        const end = Temporal.PlainTime.compare(aE, bE) <= 0 ? aE : bE;
+        const { start, end } = shared;
         return { start: start.toString(), end: end.toString() };
     }
     catch {

package/dist/plain/interval/intervalLengthDate.d.ts

@@ -5,16 +5,19 @@
  *   than measuring exact duration — see `intervalCountDate`'s JSDoc for the canonical
  *   11:59pm→12:01am example of the two diverging. `intervalLengthDate` answers "how long is
  *   this interval", `intervalCountDate` answers "how many boundaries does it touch".
- * - Uses `Temporal.Duration.prototype.total`, which resolves calendar units (month, year)
+ * - Uses `Temporal.Duration.prototype.total` semantics, which resolve calendar units (month, year)
  *   against the interval's own start so a partial month is expressed as a true fraction rather
- *   than truncated.
+ *   than truncated (non-ISO calendars follow the same TC39 NudgeToCalendarUnit steps over
+ *   calendar-correct arithmetic).
  * - Returns `0` for a zero-length interval (`start === end`).
  * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
  *   or a unit that has no effect on `PlainDate`, e.g. `"hours"`).
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). When `start` and `end`
- *   carry the *same* calendar tag, the length is measured in that calendar; otherwise (or if
- *   either is bare ISO) it falls back to Gregorian — same shared-calendar rule as
- *   `intervalCountDate` (E5 decision of record D5).
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). When `start` and `end`
+ *   carry the *same* calendar tag, the length is measured in that calendar; when they name
+ *   different calendars the result is `null` — same calendar rule as `intervalCountDate` (TC39
+ *   `CalendarEquals`; before 1.16.0 measured in ISO).
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
  *
  * @param start ISO PlainDate string for the interval start, optionally calendar-annotated
  * @param end ISO PlainDate string for the interval end, optionally calendar-annotated

package/dist/plain/interval/intervalLengthDate.js

@@ -1,6 +1,32 @@
-import { parseCalendarDatePairForArithmetic, resolveDateTimeUnit, } from "../../internal/index.js";
+import { durationTotal, parseCalendarDatePairForArithmetic, resolveDateTimeUnit, } from "../../internal/index.js";
+import { calendarDateAdd, calendarDateUntil, } from "../../internal/temporalCompat/index.js";
 import { isValidDateUnit } from "../validate/index.js";
 import { isValidDateInterval } from "./validate/index.js";
+const UNIT_FIELD = {
+    year: "years",
+    month: "months",
+    week: "weeks",
+    day: "days",
+};
+function daysBetween(from, to) {
+    return from
+        .withCalendar("iso8601")
+        .until(to.withCalendar("iso8601"), { largestUnit: "days" }).days;
+}
+/**
+ * `Duration.total({ unit, relativeTo: start })` of a non-ISO calendar difference, computed as TC39
+ * `TotalRelativeDuration` → `NudgeToCalendarUnit` does, over the Temporal compat layer's calendar
+ * add and until (CORE-6: the polyfill's own `total` runs its D1/D6/D7-affected arithmetic):
+ * `r1` whole units from `CalendarDateUntil`, plus the days from `start + r1` to `end` over the days
+ * from `start + r1` to `start + (r1 + 1)`, both added with `constrain`. `start <= end`.
+ */
+function calendarLength(start, end, unit) {
+    const field = UNIT_FIELD[unit];
+    const whole = calendarDateUntil(start, end, unit)[field];
+    const lower = calendarDateAdd(start, { [field]: whole }, "constrain");
+    const upper = calendarDateAdd(start, { [field]: whole + 1 }, "constrain");
+    return whole + daysBetween(lower, end) / daysBetween(lower, upper);
+}
 /**
  * Return the exact length of a date interval in `unit`, as a real (possibly fractional) number.
  *
@@ -8,16 +34,19 @@ import { isValidDateInterval } from "./validate/index.js";
  *   than measuring exact duration — see `intervalCountDate`'s JSDoc for the canonical
  *   11:59pm→12:01am example of the two diverging. `intervalLengthDate` answers "how long is
  *   this interval", `intervalCountDate` answers "how many boundaries does it touch".
- * - Uses `Temporal.Duration.prototype.total`, which resolves calendar units (month, year)
+ * - Uses `Temporal.Duration.prototype.total` semantics, which resolve calendar units (month, year)
  *   against the interval's own start so a partial month is expressed as a true fraction rather
- *   than truncated.
+ *   than truncated (non-ISO calendars follow the same TC39 NudgeToCalendarUnit steps over
+ *   calendar-correct arithmetic).
  * - Returns `0` for a zero-length interval (`start === end`).
  * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
  *   or a unit that has no effect on `PlainDate`, e.g. `"hours"`).
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). When `start` and `end`
- *   carry the *same* calendar tag, the length is measured in that calendar; otherwise (or if
- *   either is bare ISO) it falls back to Gregorian — same shared-calendar rule as
- *   `intervalCountDate` (E5 decision of record D5).
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). When `start` and `end`
+ *   carry the *same* calendar tag, the length is measured in that calendar; when they name
+ *   different calendars the result is `null` — same calendar rule as `intervalCountDate` (TC39
+ *   `CalendarEquals`; before 1.16.0 measured in ISO).
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
  *
  * @param start ISO PlainDate string for the interval start, optionally calendar-annotated
  * @param end ISO PlainDate string for the interval end, optionally calendar-annotated
@@ -44,11 +73,14 @@ export function intervalLengthDate(start, end, unit) {
     }
     try {
         const { a: startVal, b: endVal } = parseCalendarDatePairForArithmetic(start, end);
+        if (startVal.calendarId !== "iso8601") {
+            return calendarLength(startVal, endVal, resolvedUnit);
+        }
         const duration = startVal.until(endVal, { largestUnit: resolvedUnit });
         // total() gives the exact (possibly fractional) length, unlike intervalCountDate's
         // boundary-crossing count — e.g. Jan 31 -> Feb 1 is 1 month boundary via intervalCountDate
         // but only a fraction of a month via total().
-        return duration.total({ unit: resolvedUnit, relativeTo: startVal });
+        return durationTotal(duration, resolvedUnit, startVal);
     }
     catch {
         return null;

package/dist/plain/interval/intervalLengthDateTime.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { resolveDateTimeUnit } from "../../internal/index.js";
+import { durationTotal, resolveDateTimeUnit } from "../../internal/index.js";
 import { isValidDateTimeUnit } from "../validate/index.js";
 import { isValidDateTimeInterval } from "./validate/index.js";
 /**
@@ -42,7 +42,7 @@ export function intervalLengthDateTime(start, end, unit) {
         const duration = startVal.until(endVal, { largestUnit: resolvedUnit });
         // total() gives the exact elapsed length, unlike intervalCountDateTime's boundary-crossing
         // count — 23:59 -> 00:01 is 2 day boundaries via intervalCountDateTime but ~0.0014 days here.
-        return duration.total({ unit: resolvedUnit, relativeTo: startVal });
+        return durationTotal(duration, resolvedUnit, startVal);
     }
     catch {
         return null;

package/dist/plain/interval/intervalOverlappingDaysDate.d.ts

@@ -1,22 +1,20 @@
 /**
  * Return how many distinct calendar dates two date intervals share.
  *
- * - Counts the number of dates touched by the closed intersection
- *   `[max(aStart, bStart), min(aEnd, bEnd)]` — inclusive of both endpoints.
- * - 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).
+ * - Half-open: an interval holds every date `d` with `start <= d < end`. The count is the number
+ *   of days in the intersection `[max(aStart, bStart), min(aEnd, bEnd))`, that is
+ *   `min(aEnd, bEnd) - max(aStart, bStart)` in days.
+ * - Touching intervals (`aEnd === bStart`) share no day and count `0`; so does an empty interval.
+ * - Returns `0` when the intervals share no day (a well-defined answer, not invalid input).
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
- * - Diverges from date-fns's `getOverlappingDaysInIntervals`, which rounds up elapsed
- *   24-hour periods instead of counting calendar dates (its own doc example — Jan 10-20 vs
- *   Jan 17-21 — returns 3 there, 4 here). To reproduce date-fns's number, compose
- *   `intervalIntersectionDate` with `intervalCountDate`:
- *   `const span = intervalIntersectionDate(aStart, aEnd, bStart, bEnd); span ? intervalCountDate(span.start, span.end, "day") : 0;`
  *
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). A day is a day in every
- *   supported calendar, so this returns the same count whether or not the endpoints are
- *   calendar-tagged, and arguments may carry different or no tags (D4).
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). All four arguments
+ *   must name the same calendar (a bare ISO string names `iso8601`); different calendars return
+ *   `null`, as Temporal's `until` throws when `CalendarEquals` is false.
+ * - Compatibility: before 1.16.0 arguments could name different calendars. Since 1.16.0 calendar
+ *   strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical calendar ids); see
+ *   `isValidCalendarDate`.
  *
  * @param aStart ISO 8601 date string for the first interval start, optionally calendar-annotated
  * @param aEnd ISO 8601 date string for the first interval end, optionally calendar-annotated
@@ -24,10 +22,11 @@
  * @param bEnd ISO 8601 date string for the second interval end, optionally calendar-annotated
  * @returns number of shared calendar dates, `0` when disjoint, or null on invalid input
  *
- * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // 91
- * @example intervalOverlappingDaysDate("2024-01-01", "2024-12-31", "2024-02-01", "2024-02-29") // 29
- * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // 1 (adjacent)
- * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // 0 (disjoint)
+ * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // 90 (04-01 up to, not including, 06-30)
+ * @example intervalOverlappingDaysDate("2024-01-01", "2024-12-31", "2024-02-01", "2024-02-29") // 28
+ * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-06-29", "2024-12-31") // 1
+ * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // 0 (touching)
+ * @example intervalOverlappingDaysDate("2024-10-01", "2024-10-31", "2024-10-03[u-ca=hebrew]", "2024-11-15") // null (different calendars)
  * @example intervalOverlappingDaysDate("invalid", "2024-06-30", "2024-04-01", "2024-12-31") // null
  */
 export declare function intervalOverlappingDaysDate(aStart: string, aEnd: string, bStart: string, bEnd: string): number | null;

package/dist/plain/interval/intervalOverlappingDaysDate.js

@@ -1,25 +1,24 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { parseCalendarDateValue } from "../../internal/index.js";
+import { calendarOfAllDateValues, halfOpenIntersection, parseCalendarDateValue, } from "../../internal/index.js";
 import { isValidCalendarDate } from "../validate/index.js";
 /**
  * Return how many distinct calendar dates two date intervals share.
  *
- * - Counts the number of dates touched by the closed intersection
- *   `[max(aStart, bStart), min(aEnd, bEnd)]` — inclusive of both endpoints.
- * - 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).
+ * - Half-open: an interval holds every date `d` with `start <= d < end`. The count is the number
+ *   of days in the intersection `[max(aStart, bStart), min(aEnd, bEnd))`, that is
+ *   `min(aEnd, bEnd) - max(aStart, bStart)` in days.
+ * - Touching intervals (`aEnd === bStart`) share no day and count `0`; so does an empty interval.
+ * - Returns `0` when the intervals share no day (a well-defined answer, not invalid input).
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
- * - Diverges from date-fns's `getOverlappingDaysInIntervals`, which rounds up elapsed
- *   24-hour periods instead of counting calendar dates (its own doc example — Jan 10-20 vs
- *   Jan 17-21 — returns 3 there, 4 here). To reproduce date-fns's number, compose
- *   `intervalIntersectionDate` with `intervalCountDate`:
- *   `const span = intervalIntersectionDate(aStart, aEnd, bStart, bEnd); span ? intervalCountDate(span.start, span.end, "day") : 0;`
  *
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). A day is a day in every
- *   supported calendar, so this returns the same count whether or not the endpoints are
- *   calendar-tagged, and arguments may carry different or no tags (D4).
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). All four arguments
+ *   must name the same calendar (a bare ISO string names `iso8601`); different calendars return
+ *   `null`, as Temporal's `until` throws when `CalendarEquals` is false.
+ * - Compatibility: before 1.16.0 arguments could name different calendars. Since 1.16.0 calendar
+ *   strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical calendar ids); see
+ *   `isValidCalendarDate`.
  *
  * @param aStart ISO 8601 date string for the first interval start, optionally calendar-annotated
  * @param aEnd ISO 8601 date string for the first interval end, optionally calendar-annotated
@@ -27,10 +26,11 @@ import { isValidCalendarDate } from "../validate/index.js";
  * @param bEnd ISO 8601 date string for the second interval end, optionally calendar-annotated
  * @returns number of shared calendar dates, `0` when disjoint, or null on invalid input
  *
- * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // 91
- * @example intervalOverlappingDaysDate("2024-01-01", "2024-12-31", "2024-02-01", "2024-02-29") // 29
- * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // 1 (adjacent)
- * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // 0 (disjoint)
+ * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // 90 (04-01 up to, not including, 06-30)
+ * @example intervalOverlappingDaysDate("2024-01-01", "2024-12-31", "2024-02-01", "2024-02-29") // 28
+ * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-06-29", "2024-12-31") // 1
+ * @example intervalOverlappingDaysDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // 0 (touching)
+ * @example intervalOverlappingDaysDate("2024-10-01", "2024-10-31", "2024-10-03[u-ca=hebrew]", "2024-11-15") // null (different calendars)
  * @example intervalOverlappingDaysDate("invalid", "2024-06-30", "2024-04-01", "2024-12-31") // null
  */
 export function intervalOverlappingDaysDate(aStart, aEnd, bStart, bEnd) {
@@ -46,6 +46,11 @@ export function intervalOverlappingDaysDate(aStart, aEnd, bStart, bEnd) {
         !isValidCalendarDate(bEnd)) {
         return null;
     }
+    // The count is a difference between two of the endpoints, so all four must name one calendar
+    // (TC39 CalendarEquals, which makes until throw across calendars).
+    if (calendarOfAllDateValues([aStart, aEnd, bStart, bEnd]) === null) {
+        return null;
+    }
     try {
         const aS = parseCalendarDateValue(aStart);
         const aE = parseCalendarDateValue(aEnd);
@@ -57,20 +62,15 @@ export function intervalOverlappingDaysDate(aStart, aEnd, bStart, bEnd) {
         if (Temporal.PlainDate.compare(bS, bE) > 0) {
             return null;
         }
-        if (Temporal.PlainDate.compare(aE, bS) < 0 ||
-            Temporal.PlainDate.compare(bE, aS) < 0) {
+        const shared = halfOpenIntersection({ start: aS, end: aE }, { start: bS, end: bE }, Temporal.PlainDate.compare);
+        if (shared === null) {
             return 0;
         }
-        const start = Temporal.PlainDate.compare(aS, bS) >= 0 ? aS : bS;
-        const end = Temporal.PlainDate.compare(aE, bE) <= 0 ? aE : bE;
-        // start/end may carry different calendars when the four arguments' tags don't all match
-        // (D4: this function accepts mixed calendars since it returns a count, not a date value) —
-        // Temporal.PlainDate.prototype.until throws outright across two different calendars, even
-        // though .compare above does not, so both are normalized to iso8601 first. A day is the
-        // same length in every supported calendar, so this never changes the answer.
-        return (start.withCalendar("iso8601").until(end.withCalendar("iso8601"), {
-            largestUnit: "day",
-        }).days + 1);
+        // A day is the same length in every supported calendar, so the day count is measured in
+        // iso8601, which never changes the answer.
+        return shared.start
+            .withCalendar("iso8601")
+            .until(shared.end.withCalendar("iso8601"), { largestUnit: "day" }).days;
     }
     catch {
         return null;

package/dist/plain/interval/intervalOverlappingDaysDateTime.d.ts

@@ -1,18 +1,13 @@
 /**
  * Return how many distinct calendar dates two datetime intervals share.
  *
- * - Counts the number of local dates touched by the closed intersection
- *   `[max(aStart, bStart), min(aEnd, bEnd)]` — inclusive of both endpoints.
- * - 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).
+ * - Half-open: an interval holds every `t` with `start <= t < end`. The count is the number of
+ *   calendar days holding at least one moment of the intersection `[max(aStart, bStart),
+ *   min(aEnd, bEnd))`. An intersection ending exactly at midnight does not reach that day.
+ * - Touching intervals (`aEnd === bStart`) share no moment and count `0`; so does an empty interval.
+ * - Returns `0` when the intervals share nothing (a well-defined answer, not invalid input).
  * - Returns `null` if either interval is invalid (`start > end`).
  * - Returns `null` on invalid input (wrong type, malformed strings).
- * - Diverges from date-fns's `getOverlappingDaysInIntervals`, which rounds up elapsed
- *   24-hour periods instead of counting calendar dates (its own doc example — Jan 10-20 vs
- *   Jan 17-21 — returns 3 there, 4 here). To reproduce date-fns's number, compose
- *   `intervalIntersectionDateTime` with `intervalCountDateTime`:
- *   `const span = intervalIntersectionDateTime(aStart, aEnd, bStart, bEnd); span ? intervalCountDateTime(span.start, span.end, "day") : 0;`
  *
  * @param aStart ISO 8601 datetime string for the first interval start
  * @param aEnd ISO 8601 datetime string for the first interval end
@@ -21,8 +16,8 @@
  * @returns number of shared calendar dates, `0` when disjoint, or null on invalid input
  *
  * @example intervalOverlappingDaysDateTime("2024-01-01T23:59:00", "2024-01-02T00:01:00", "2024-01-01T23:59:00", "2024-01-02T00:01:00") // 2
- * @example intervalOverlappingDaysDateTime("2024-01-01T00:00:00", "2024-01-02T00:00:00", "2024-01-02T00:00:00", "2024-01-03T00:00:00") // 1 (adjacent)
- * @example intervalOverlappingDaysDateTime("2024-01-01T00:00:00", "2024-01-02T00:00:00", "2024-01-02T00:00:00.001", "2024-01-03T00:00:00") // 0 (disjoint)
+ * @example intervalOverlappingDaysDateTime("2024-01-01T00:00:00", "2024-01-05T00:00:00", "2024-01-03T12:00:00", "2024-01-09T00:00:00") // 2 (01-03 and 01-04; 01-05T00:00 is excluded)
+ * @example intervalOverlappingDaysDateTime("2024-01-01T00:00:00", "2024-01-02T00:00:00", "2024-01-02T00:00:00", "2024-01-03T00:00:00") // 0 (touching)
  * @example intervalOverlappingDaysDateTime("invalid", "2024-06-30T23:59:59", "2024-04-01T00:00:00", "2024-12-31T23:59:59") // null
  */
 export declare function intervalOverlappingDaysDateTime(aStart: string, aEnd: string, bStart: string, bEnd: string): number | null;