@northguild/gmt 1.15.0 → 1.17.0

package/dist/plain/interval/intervalCountDate.js

@@ -1,23 +1,39 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { getUnitSpan, parseCalendarDatePairForArithmetic, resolveDateTimeUnit, } from "../../internal/index.js";
-import { getStartOfDateUnit } from "../../internal/dateUnitHelpers.js";
+import { getStartOfDateUnit, getStartOfNextDateUnit, } from "../../internal/dateUnitHelpers.js";
+import { calendarDateUntil, } from "../../internal/temporalCompat/index.js";
 import { isValidCalendarDate, isValidDateUnit } from "../validate/index.js";
+/** The start of the date `unit` holding `source`, or null when it lies before the representable range. */
+function startOfUnitIfRepresentable(source, unit) {
+    try {
+        return getStartOfDateUnit(source, unit);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Count how many `unit` boundaries a date interval crosses.
  *
  * - Counts calendar boundaries touched by the half-open interval `[start, end)` — distinct
  *   from `diffDate`, which measures exact elapsed duration.
  * - `"2024-01-01"` to `"2024-01-03"` counted in days is 2: the end boundary is excluded.
- * - A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a
- *   unit boundary (e.g. `"2024-01-15"` counts 1 month but 0 days).
+ * - 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).
  * - Weeks start on Monday (ISO 8601).
+ * - A unit that began before the first representable date (`-271821-04-19`) is still counted:
+ *   whole units are measured from the unit after `start`'s, never from `start`'s own start.
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
  * - 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`
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). When `start` and `end`
  *   carry the *same* calendar tag, boundaries are counted in that calendar (a Hebrew leap year
- *   crosses 13 month boundaries, not 12 — see the roadmap's E5 decisions of record, D5). When
- *   they carry different tags (or either is bare ISO), counting falls back to Gregorian.
+ *   crosses 13 month boundaries, not 12). When they name different calendars (a bare ISO string
+ *   names `iso8601`) the result is `null`, as Temporal's `until` throws when `CalendarEquals` is
+ *   false (before 1.16.0 it counted 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
@@ -26,11 +42,11 @@ import { isValidCalendarDate, isValidDateUnit } from "../validate/index.js";
  *
  * @example intervalCountDate("2024-01-01", "2024-01-03", "day") // 2
  * @example intervalCountDate("2024-01-15", "2024-03-10", "month") // 3
- * @example intervalCountDate("2024-01-15", "2024-01-15", "month") // 1 (zero-length, mid-month)
- * @example intervalCountDate("2024-01-01", "2024-01-01", "month") // 0 (zero-length, on the boundary)
+ * @example intervalCountDate("2024-01-15", "2024-01-15", "month") // 0 (zero-length: holds no instant)
  * @example intervalCountDate("2024-01-01", "2024-01-10", "hour") // null
  * @example intervalCountDate("invalid", "2024-01-10", "day") // null
- * @example intervalCountDate("5784-01-01[u-ca=hebrew]", "5785-01-01[u-ca=hebrew]", "month") // 13 (Hebrew leap year, measured in Hebrew)
+ * @example intervalCountDate("2023-09-16[u-ca=hebrew]", "2024-10-03[u-ca=hebrew]", "month") // 13 (Hebrew leap year, measured in Hebrew)
+ * @example intervalCountDate("2024-10-03[u-ca=hebrew]", "2024-11-03", "month") // null (different calendars)
  */
 export function intervalCountDate(start, end, unit) {
     if (typeof start !== "string" || typeof end !== "string") {
@@ -48,13 +64,29 @@ export function intervalCountDate(start, end, unit) {
     }
     try {
         const { a: startVal, b: endVal } = parseCalendarDatePairForArithmetic(start, end);
-        if (Temporal.PlainDate.compare(startVal, endVal) > 0) {
+        const order = Temporal.PlainDate.compare(startVal, endVal);
+        if (order > 0) {
             return null;
         }
-        const startOfStart = getStartOfDateUnit(startVal, resolvedUnit);
-        const startOfEnd = getStartOfDateUnit(endVal, resolvedUnit);
-        const spanned = getUnitSpan(startOfStart.until(startOfEnd, { largestUnit: resolvedUnit }), resolvedUnit);
-        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;
+        }
+        const startOfEnd = startOfUnitIfRepresentable(endVal, resolvedUnit);
+        // `end`'s unit began before the range, so `start` (<= `end`) is in it too, and `end` is not on
+        // a boundary: one bucket.
+        if (startOfEnd === null) {
+            return 1;
+        }
+        const endBucket = startOfEnd.equals(endVal) ? 0 : 1;
+        // `start` is already inside `end`'s unit: no boundary between them.
+        if (Temporal.PlainDate.compare(startOfEnd, startVal) <= 0) {
+            return endBucket;
+        }
+        // `start`'s unit, plus every whole unit from the next start up to `end`'s unit.
+        const spanned = 1 +
+            getUnitSpan(Temporal.Duration.from(calendarDateUntil(getStartOfNextDateUnit(startVal, resolvedUnit), startOfEnd, resolvedUnit)), resolvedUnit);
+        return spanned + endBucket;
     }
     catch {
         return null;

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

@@ -5,9 +5,12 @@
  *   from `diffDateTime`, which measures exact elapsed duration. An interval from 23:59 to
  *   00:01 is two minutes long but touches 2 day boundaries.
  * - The end boundary is excluded: `"2024-01-01T00:00:00"` to `"2024-01-03T00:00:00"` 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).
  * - Weeks start on Monday (ISO 8601).
+ * - A unit that began before the first representable PlainDateTime
+ *   (`-271821-04-19T00:00:00.000000001`) is still counted: whole units are measured from the unit
+ *   after `start`'s, never from `start`'s own start.
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
  * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit).
  *
@@ -19,8 +22,7 @@
  * @example intervalCountDateTime("2024-01-01T23:59:00", "2024-01-02T00:01:00", "day") // 2
  * @example intervalCountDateTime("2024-01-01T00:00:00", "2024-01-03T00:00:00", "day") // 2
  * @example intervalCountDateTime("2024-01-01T10:30:00", "2024-01-01T12:00:00", "hour") // 2
- * @example intervalCountDateTime("2024-01-01T05:00:00", "2024-01-01T05:00:00", "day") // 1 (zero-length, mid-day)
- * @example intervalCountDateTime("2024-01-01T00:00:00", "2024-01-01T00:00:00", "day") // 0 (zero-length, on the boundary)
+ * @example intervalCountDateTime("2024-01-01T05:00:00", "2024-01-01T05:00:00", "day") // 0 (zero-length: holds no instant)
  * @example intervalCountDateTime("invalid", "2024-01-02T00:00:00", "day") // null
  */
 export declare function intervalCountDateTime(start: string, end: string, unit: string): number | null;

package/dist/plain/interval/intervalCountDateTime.js

@@ -1,18 +1,46 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { getUnitSpan, resolveDateTimeUnit } from "../../internal/index.js";
-import { getStartOfDateTimeUnit } from "../../internal/dateTimeUnitHelpers.js";
-import { plainDateTime } from "../../regex/index.js";
+import { getStartOfDateTimeUnit, getStartOfNextDateTimeUnit, } from "../../internal/dateTimeUnitHelpers.js";
 import { isValidDateTime, isValidDateTimeUnit, isValidDateUnit, } from "../validate/index.js";
+/** One of each time unit, for stepping to the next time-unit bucket. */
+const ONE_TIME_UNIT = {
+    hour: { hours: 1 },
+    minute: { minutes: 1 },
+    second: { seconds: 1 },
+    millisecond: { milliseconds: 1 },
+    microsecond: { microseconds: 1 },
+    nanosecond: { nanoseconds: 1 },
+};
 /**
- * Return the start of `unit` for a `Temporal.PlainDateTime`, for every DateTimeUnit.
+ * Return the start of `unit` for a `Temporal.PlainDateTime`, for every DateTimeUnit, or null when
+ * it lies before the representable range (the first PlainDateTime is
+ * `-271821-04-19T00:00:00.000000001`, so even that date's midnight does not exist).
  *
  * Date units delegate to the shared helper; time units truncate via `round`.
  */
-function startOfUnit(source, unit) {
+function startOfUnitIfRepresentable(source, unit) {
+    try {
+        if (isValidDateUnit(unit)) {
+            return getStartOfDateTimeUnit(source, unit);
+        }
+        return source.round({ smallestUnit: unit, roundingMode: "trunc" });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Return the start of the `unit` after the one holding `source`: step first, truncate after, so
+ * `source`'s own start is never materialised.
+ */
+function startOfNextUnit(source, unit) {
     if (isValidDateUnit(unit)) {
-        return getStartOfDateTimeUnit(source, unit);
+        return getStartOfNextDateTimeUnit(source, unit);
     }
-    return source.round({ smallestUnit: unit, roundingMode: "trunc" });
+    return source
+        .add(ONE_TIME_UNIT[unit] ?? { nanoseconds: 1 })
+        .round({ smallestUnit: unit, roundingMode: "trunc" });
 }
 /**
  * Count how many `unit` boundaries a date-time interval crosses.
@@ -21,9 +49,12 @@ function startOfUnit(source, unit) {
  *   from `diffDateTime`, which measures exact elapsed duration. An interval from 23:59 to
  *   00:01 is two minutes long but touches 2 day boundaries.
  * - The end boundary is excluded: `"2024-01-01T00:00:00"` to `"2024-01-03T00:00:00"` 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).
  * - Weeks start on Monday (ISO 8601).
+ * - A unit that began before the first representable PlainDateTime
+ *   (`-271821-04-19T00:00:00.000000001`) is still counted: whole units are measured from the unit
+ *   after `start`'s, never from `start`'s own start.
  * - Accepts singular or plural units (`"day"` and `"days"` behave identically).
  * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit).
  *
@@ -35,17 +66,13 @@ function startOfUnit(source, unit) {
  * @example intervalCountDateTime("2024-01-01T23:59:00", "2024-01-02T00:01:00", "day") // 2
  * @example intervalCountDateTime("2024-01-01T00:00:00", "2024-01-03T00:00:00", "day") // 2
  * @example intervalCountDateTime("2024-01-01T10:30:00", "2024-01-01T12:00:00", "hour") // 2
- * @example intervalCountDateTime("2024-01-01T05:00:00", "2024-01-01T05:00:00", "day") // 1 (zero-length, mid-day)
- * @example intervalCountDateTime("2024-01-01T00:00:00", "2024-01-01T00:00:00", "day") // 0 (zero-length, on the boundary)
+ * @example intervalCountDateTime("2024-01-01T05:00:00", "2024-01-01T05:00:00", "day") // 0 (zero-length: holds no instant)
  * @example intervalCountDateTime("invalid", "2024-01-02T00:00:00", "day") // null
  */
 export function intervalCountDateTime(start, end, unit) {
     if (typeof start !== "string" || typeof end !== "string") {
         return null;
     }
-    if (!plainDateTime.test(start) || !plainDateTime.test(end)) {
-        return null;
-    }
     if (!isValidDateTime(start) || !isValidDateTime(end)) {
         return null;
     }
@@ -59,13 +86,31 @@ export function intervalCountDateTime(start, end, unit) {
     try {
         const startVal = Temporal.PlainDateTime.from(start);
         const endVal = Temporal.PlainDateTime.from(end);
-        if (Temporal.PlainDateTime.compare(startVal, endVal) > 0) {
+        const order = Temporal.PlainDateTime.compare(startVal, endVal);
+        if (order > 0) {
             return null;
         }
-        const startOfStart = startOfUnit(startVal, resolvedUnit);
-        const startOfEnd = startOfUnit(endVal, resolvedUnit);
-        const spanned = getUnitSpan(startOfStart.until(startOfEnd, { largestUnit: resolvedUnit }), resolvedUnit);
-        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;
+        }
+        const startOfEnd = startOfUnitIfRepresentable(endVal, resolvedUnit);
+        // `end`'s unit began before the range, so `start` (<= `end`) is in it too, and `end` is not on
+        // a boundary: one bucket.
+        if (startOfEnd === null) {
+            return 1;
+        }
+        const endBucket = startOfEnd.equals(endVal) ? 0 : 1;
+        // `start` is already inside `end`'s unit: no boundary between them.
+        if (Temporal.PlainDateTime.compare(startOfEnd, startVal) <= 0) {
+            return endBucket;
+        }
+        // `start`'s unit, plus every whole unit from the next start up to `end`'s unit.
+        const spanned = 1 +
+            getUnitSpan(startOfNextUnit(startVal, resolvedUnit).until(startOfEnd, {
+                largestUnit: resolvedUnit,
+            }), resolvedUnit);
+        return spanned + endBucket;
     }
     catch {
         return null;

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

@@ -5,8 +5,8 @@
  *   `diffTime`, which measures exact elapsed duration. An interval from 12:59 to 13:01 is two
  *   minutes long but touches 2 hour boundaries.
  * - The end boundary is excluded: `"12:00:00"` to `"14:00:00"` counts 2 hours.
- * - 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).
  * - Accepts singular or plural units (`"hour"` and `"hours"` behave identically).
  * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
  *   or a unit that has no effect on `PlainTime`, e.g. `"days"`).
@@ -18,8 +18,7 @@
  *
  * @example intervalCountTime("12:00:00", "14:00:00", "hour") // 2
  * @example intervalCountTime("12:30:00", "13:00:00", "hour") // 1
- * @example intervalCountTime("12:30:00", "12:30:00", "hour") // 1 (zero-length, mid-hour)
- * @example intervalCountTime("12:00:00", "12:00:00", "hour") // 0 (zero-length, on the boundary)
+ * @example intervalCountTime("12:30:00", "12:30:00", "hour") // 0 (zero-length: holds no instant)
  * @example intervalCountTime("12:00:00", "14:00:00", "day") // null
  * @example intervalCountTime("invalid", "14:00:00", "hour") // null
  */

package/dist/plain/interval/intervalCountTime.js

@@ -1,6 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { getUnitSpan, resolveDateTimeUnit } from "../../internal/index.js";
-import { plainTime } from "../../regex/index.js";
 import { isValidTime, isValidTimeUnit } from "../validate/index.js";
 /**
  * Count how many `unit` boundaries a time interval crosses.
@@ -9,8 +8,8 @@ import { isValidTime, isValidTimeUnit } from "../validate/index.js";
  *   `diffTime`, which measures exact elapsed duration. An interval from 12:59 to 13:01 is two
  *   minutes long but touches 2 hour boundaries.
  * - The end boundary is excluded: `"12:00:00"` to `"14:00:00"` counts 2 hours.
- * - 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).
  * - Accepts singular or plural units (`"hour"` and `"hours"` behave identically).
  * - Returns `null` on invalid input (unparseable start/end, `start > end`, unsupported unit,
  *   or a unit that has no effect on `PlainTime`, e.g. `"days"`).
@@ -22,8 +21,7 @@ import { isValidTime, isValidTimeUnit } from "../validate/index.js";
  *
  * @example intervalCountTime("12:00:00", "14:00:00", "hour") // 2
  * @example intervalCountTime("12:30:00", "13:00:00", "hour") // 1
- * @example intervalCountTime("12:30:00", "12:30:00", "hour") // 1 (zero-length, mid-hour)
- * @example intervalCountTime("12:00:00", "12:00:00", "hour") // 0 (zero-length, on the boundary)
+ * @example intervalCountTime("12:30:00", "12:30:00", "hour") // 0 (zero-length: holds no instant)
  * @example intervalCountTime("12:00:00", "14:00:00", "day") // null
  * @example intervalCountTime("invalid", "14:00:00", "hour") // null
  */
@@ -31,9 +29,6 @@ export function intervalCountTime(start, end, unit) {
     if (typeof start !== "string" || typeof end !== "string") {
         return null;
     }
-    if (!plainTime.test(start) || !plainTime.test(end)) {
-        return null;
-    }
     if (!isValidTime(start) || !isValidTime(end)) {
         return null;
     }
@@ -47,9 +42,14 @@ export function intervalCountTime(start, end, unit) {
     try {
         const startVal = Temporal.PlainTime.from(start);
         const endVal = Temporal.PlainTime.from(end);
-        if (Temporal.PlainTime.compare(startVal, endVal) > 0) {
+        const order = Temporal.PlainTime.compare(startVal, endVal);
+        if (order > 0) {
             return null;
         }
+        // An empty interval [t, t) holds no instant, so it touches no unit (CORE-6 empty-interval rule).
+        if (order === 0) {
+            return 0;
+        }
         const startOfStart = startVal.round({
             smallestUnit: resolvedUnit,
             roundingMode: "trunc",

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

@@ -2,12 +2,20 @@
  * Return the portion(s) of interval A not covered by interval B.
  *
  * - Uses `Temporal.PlainDate.compare` for comparison.
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Half-open: an interval holds every date `d` with `start <= d < end`. A returned piece ends exactly
+ *   where B starts, or starts exactly where B ends, because B's `end` is not in B (CORE-6's
+ *   `subtractIntervals`). No piece is stepped by one day.
+ * - B touching A (`bStart === aEnd` or `bEnd === aStart`), or empty, removes nothing.
+ * - An empty A (`aStart === aEnd`) has nothing left: returns `[]`. Every returned piece is non-empty.
+ * - `end` is the first day after the period: for a period whose last day is `last`, pass
+ *   `addDate(last, { days: 1 })`.
+ * - Returns `[]` when B fully covers A, which includes B equal to A.
+ * - Returns `[{ start, end }]` when B overlaps exactly one edge of A, leaving one piece.
  * - 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.
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings).
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Since the result is
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). Since the result is
  *   date *values*, all four arguments must carry the *same* calendar tag (or all be bare ISO);
  *   a mismatch returns `[]` (E5 decision of record D4). Each output piece's tag is re-derived,
  *   never copied from an input.
@@ -18,10 +26,9 @@
  * @param bEnd ISO 8601 date string for the second interval end, optionally calendar-annotated
  * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input / mismatched calendars
  *
- * @example intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-07-01") // [{ start: "2024-01-01", end: "2024-05-31" }, { start: "2024-07-02", end: "2024-12-31" }]
- * @example intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-03-01", "2024-10-31") // [{ start: "2024-01-01", end: "2024-02-29" }, { start: "2024-11-01", end: "2024-12-31" }]
+ * @example intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-07-01") // [{ start: "2024-01-01", end: "2024-06-01" }, { start: "2024-07-01", end: "2024-12-31" }]
+ * @example intervalDifferenceDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // [{ start: "2024-01-01", end: "2024-06-30" }] (touching B removes nothing)
  * @example intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-01-01", "2024-12-31") // []
- * @example intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-12-31") // [{ start: "2024-01-01", end: "2024-05-31" }]
  * @example intervalDifferenceDate("invalid", "2024-12-31", "2024-06-01", "2024-07-01") // []
  */
 export declare function intervalDifferenceDate(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{

package/dist/plain/interval/intervalDifferenceDate.js

@@ -1,16 +1,25 @@
+// 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, halfOpenDifference, parseCalendarDateValue, } from "../../internal/index.js";
 import { isValidCalendarDate } from "../validate/index.js";
 /**
  * Return the portion(s) of interval A not covered by interval B.
  *
  * - Uses `Temporal.PlainDate.compare` for comparison.
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Half-open: an interval holds every date `d` with `start <= d < end`. A returned piece ends exactly
+ *   where B starts, or starts exactly where B ends, because B's `end` is not in B (CORE-6's
+ *   `subtractIntervals`). No piece is stepped by one day.
+ * - B touching A (`bStart === aEnd` or `bEnd === aStart`), or empty, removes nothing.
+ * - An empty A (`aStart === aEnd`) has nothing left: returns `[]`. Every returned piece is non-empty.
+ * - `end` is the first day after the period: for a period whose last day is `last`, pass
+ *   `addDate(last, { days: 1 })`.
+ * - Returns `[]` when B fully covers A, which includes B equal to A.
+ * - Returns `[{ start, end }]` when B overlaps exactly one edge of A, leaving one piece.
  * - 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.
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings).
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Since the result is
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). Since the result is
  *   date *values*, all four arguments must carry the *same* calendar tag (or all be bare ISO);
  *   a mismatch returns `[]` (E5 decision of record D4). Each output piece's tag is re-derived,
  *   never copied from an input.
@@ -21,10 +30,9 @@ import { isValidCalendarDate } from "../validate/index.js";
  * @param bEnd ISO 8601 date string for the second interval end, optionally calendar-annotated
  * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input / mismatched calendars
  *
- * @example intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-07-01") // [{ start: "2024-01-01", end: "2024-05-31" }, { start: "2024-07-02", end: "2024-12-31" }]
- * @example intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-03-01", "2024-10-31") // [{ start: "2024-01-01", end: "2024-02-29" }, { start: "2024-11-01", end: "2024-12-31" }]
+ * @example intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-07-01") // [{ start: "2024-01-01", end: "2024-06-01" }, { start: "2024-07-01", end: "2024-12-31" }]
+ * @example intervalDifferenceDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // [{ start: "2024-01-01", end: "2024-06-30" }] (touching B removes nothing)
  * @example intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-01-01", "2024-12-31") // []
- * @example intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-12-31") // [{ start: "2024-01-01", end: "2024-05-31" }]
  * @example intervalDifferenceDate("invalid", "2024-12-31", "2024-06-01", "2024-07-01") // []
  */
 export function intervalDifferenceDate(aStart, aEnd, bStart, bEnd) {
@@ -55,31 +63,10 @@ export function intervalDifferenceDate(aStart, aEnd, bStart, bEnd) {
         if (Temporal.PlainDate.compare(bS, bE) > 0) {
             return [];
         }
-        const result = [];
-        // Left piece: A before B starts
-        if (Temporal.PlainDate.compare(aS, bS) < 0) {
-            const leftEnd = Temporal.PlainDate.compare(Temporal.PlainDate.compare(aE, bS) < 0
-                ? aE
-                : bS.subtract({ days: 1 }), aS) >= 0
-                ? Temporal.PlainDate.compare(aE, bS) < 0
-                    ? aE
-                    : bS.subtract({ days: 1 })
-                : null;
-            if (leftEnd !== null && Temporal.PlainDate.compare(leftEnd, aS) >= 0) {
-                result.push({
-                    start: formatDateInCalendar(aS, calendar),
-                    end: formatDateInCalendar(leftEnd, calendar),
-                });
-            }
-        }
-        // Right piece: A after B ends
-        if (Temporal.PlainDate.compare(aE, bE) > 0) {
-            result.push({
-                start: formatDateInCalendar(bE.add({ days: 1 }), calendar),
-                end: formatDateInCalendar(aE, calendar),
-            });
-        }
-        return result;
+        return halfOpenDifference({ start: aS, end: aE }, [{ start: bS, end: bE }], Temporal.PlainDate.compare).map(({ start, end }) => ({
+            start: formatDateInCalendar(start, calendar),
+            end: formatDateInCalendar(end, calendar),
+        }));
     }
     catch {
         return [];

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

@@ -2,9 +2,15 @@
  * Return the portion(s) of interval A not covered by interval B.
  *
  * - Uses `Temporal.PlainDateTime.compare` for comparison.
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Half-open: an interval holds every `t` with `start <= t < end`. A returned piece ends exactly
+ *   where B starts, or starts exactly where B ends, because B's `end` is not in B (CORE-6's
+ *   `subtractIntervals`). No piece is stepped by one unit.
+ * - B touching A (`bStart === aEnd` or `bEnd === aStart`), or empty, removes nothing.
+ * - An empty A (`aStart === aEnd`) has nothing left: returns `[]`. Every returned piece is non-empty.
+ * - Returns `[]` when B fully covers A, which includes B equal to A.
+ * - Returns `[{ start, end }]` when B overlaps exactly one edge of A, leaving one piece.
  * - 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.
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings).
  *
@@ -14,8 +20,8 @@
  * @param bEnd ISO 8601 datetime string for the second interval end
  * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
  *
- * @example intervalDifferenceDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // [{ start: "2024-01-01T09:00:00", end: "2024-05-31T17:00:00" }, { start: "2024-07-01T13:00:01", end: "2024-12-31T17:00:00" }]
- * @example intervalDifferenceDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-01-01T09:00:00", "2024-12-31T17:00:00") // []
+ * @example intervalDifferenceDateTime("2024-01-01T09:00:00", "2024-01-01T17:00:00", "2024-01-01T12:00:00", "2024-01-01T13:00:00") // [{ start: "2024-01-01T09:00:00", end: "2024-01-01T12:00:00" }, { start: "2024-01-01T13:00:00", end: "2024-01-01T17:00:00" }]
+ * @example intervalDifferenceDateTime("2024-01-01T09:00:00", "2024-01-01T17:00:00", "2024-01-01T09:00:00", "2024-01-01T17:00:00") // []
  * @example intervalDifferenceDateTime("invalid", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // []
  */
 export declare function intervalDifferenceDateTime(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{

package/dist/plain/interval/intervalDifferenceDateTime.js

@@ -1,12 +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 { plainDateTime } from "../../regex/index.js";
+import { halfOpenDifference } from "../../internal/index.js";
+import { isValidDateTime } from "../validate/index.js";
 /**
  * Return the portion(s) of interval A not covered by interval B.
  *
  * - Uses `Temporal.PlainDateTime.compare` for comparison.
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Half-open: an interval holds every `t` with `start <= t < end`. A returned piece ends exactly
+ *   where B starts, or starts exactly where B ends, because B's `end` is not in B (CORE-6's
+ *   `subtractIntervals`). No piece is stepped by one unit.
+ * - B touching A (`bStart === aEnd` or `bEnd === aStart`), or empty, removes nothing.
+ * - An empty A (`aStart === aEnd`) has nothing left: returns `[]`. Every returned piece is non-empty.
+ * - Returns `[]` when B fully covers A, which includes B equal to A.
+ * - Returns `[{ start, end }]` when B overlaps exactly one edge of A, leaving one piece.
  * - 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.
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings).
  *
@@ -16,8 +24,8 @@ import { plainDateTime } from "../../regex/index.js";
  * @param bEnd ISO 8601 datetime string for the second interval end
  * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
  *
- * @example intervalDifferenceDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // [{ start: "2024-01-01T09:00:00", end: "2024-05-31T17:00:00" }, { start: "2024-07-01T13:00:01", end: "2024-12-31T17:00:00" }]
- * @example intervalDifferenceDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-01-01T09:00:00", "2024-12-31T17:00:00") // []
+ * @example intervalDifferenceDateTime("2024-01-01T09:00:00", "2024-01-01T17:00:00", "2024-01-01T12:00:00", "2024-01-01T13:00:00") // [{ start: "2024-01-01T09:00:00", end: "2024-01-01T12:00:00" }, { start: "2024-01-01T13:00:00", end: "2024-01-01T17:00:00" }]
+ * @example intervalDifferenceDateTime("2024-01-01T09:00:00", "2024-01-01T17:00:00", "2024-01-01T09:00:00", "2024-01-01T17:00:00") // []
  * @example intervalDifferenceDateTime("invalid", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // []
  */
 export function intervalDifferenceDateTime(aStart, aEnd, bStart, bEnd) {
@@ -27,10 +35,10 @@ export function intervalDifferenceDateTime(aStart, aEnd, bStart, bEnd) {
         typeof bEnd !== "string") {
         return [];
     }
-    if (!plainDateTime.test(aStart) ||
-        !plainDateTime.test(aEnd) ||
-        !plainDateTime.test(bStart) ||
-        !plainDateTime.test(bEnd)) {
+    if (!isValidDateTime(aStart) ||
+        !isValidDateTime(aEnd) ||
+        !isValidDateTime(bStart) ||
+        !isValidDateTime(bEnd)) {
         return [];
     }
     try {
@@ -44,24 +52,10 @@ export function intervalDifferenceDateTime(aStart, aEnd, bStart, bEnd) {
         if (Temporal.PlainDateTime.compare(bS, bE) > 0) {
             return [];
         }
-        const result = [];
-        // Left piece: A before B starts
-        if (Temporal.PlainDateTime.compare(aS, bS) < 0) {
-            const leftEnd = Temporal.PlainDateTime.compare(aE, bS) < 0
-                ? aE
-                : bS.subtract({ nanoseconds: 1 });
-            if (Temporal.PlainDateTime.compare(leftEnd, aS) >= 0) {
-                result.push({ start: aS.toString(), end: leftEnd.toString() });
-            }
-        }
-        // Right piece: A after B ends
-        if (Temporal.PlainDateTime.compare(aE, bE) > 0) {
-            result.push({
-                start: bE.add({ nanoseconds: 1 }).toString(),
-                end: aE.toString(),
-            });
-        }
-        return result;
+        return halfOpenDifference({ start: aS, end: aE }, [{ start: bS, end: bE }], Temporal.PlainDateTime.compare).map(({ start, end }) => ({
+            start: start.toString(),
+            end: end.toString(),
+        }));
     }
     catch {
         return [];

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

@@ -2,9 +2,15 @@
  * Return the portion(s) of interval A not covered by interval B.
  *
  * - Uses `Temporal.PlainTime.compare` for comparison.
- * - Returns `[]` when B fully covers A.
- * - Returns `[{ start, end }]` when B overlaps one edge of A (or equals A).
+ * - Half-open: an interval holds every `t` with `start <= t < end`. A returned piece ends exactly
+ *   where B starts, or starts exactly where B ends, because B's `end` is not in B (CORE-6's
+ *   `subtractIntervals`). No piece is stepped by one unit.
+ * - B touching A (`bStart === aEnd` or `bEnd === aStart`), or empty, removes nothing.
+ * - An empty A (`aStart === aEnd`) has nothing left: returns `[]`. Every returned piece is non-empty.
+ * - Returns `[]` when B fully covers A, which includes B equal to A.
+ * - Returns `[{ start, end }]` when B overlaps exactly one edge of A, leaving one piece.
  * - 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.
  * - Returns `[]` if either interval is invalid (`start > end`).
  * - Returns `[]` on invalid input (wrong type, malformed strings).
  *
@@ -14,9 +20,10 @@
  * @param bEnd ISO 8601 time string for the second interval end
  * @returns array of `{ start, end }` records representing A minus B, or `[]` on invalid input
  *
- * @example intervalDifferenceTime("09:00:00", "17:00:00", "12:00:00", "13:00:00") // [{ start: "09:00:00", end: "11:59:59" }, { start: "13:00:01", end: "17:00:00" }]
+ * @example intervalDifferenceTime("09:00:00", "17:00:00", "12:00:00", "13:00:00") // [{ start: "09:00:00", end: "12:00:00" }, { start: "13:00:00", end: "17:00:00" }]
  * @example intervalDifferenceTime("09:00:00", "17:00:00", "09:00:00", "17:00:00") // []
- * @example intervalDifferenceTime("09:00:00", "17:00:00", "12:00:00", "17:00:00") // [{ start: "09:00:00", end: "11:59:59" }]
+ * @example intervalDifferenceTime("09:00:00", "17:00:00", "12:00:00", "17:00:00") // [{ start: "09:00:00", end: "12:00:00" }]
+ * @example intervalDifferenceTime("12:00:00", "17:00:00", "09:00:00", "12:00:00") // [{ start: "12:00:00", end: "17:00:00" }] (touching B removes nothing)
  * @example intervalDifferenceTime("invalid", "17:00:00", "12:00:00", "13:00:00") // []
  */
 export declare function intervalDifferenceTime(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{