@northguild/gmt 1.14.2

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

@@ -0,0 +1,30 @@
+/**
+ * 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).
+ * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - 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
+ *   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.
+ *
+ * @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
+ * @param bStart ISO 8601 date string for the second interval start, optionally calendar-annotated
+ * @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-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<{
+    start: string;
+    end: string;
+}>;

package/dist/plain/interval/intervalDifferenceDate.js

@@ -0,0 +1,87 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarOfAllDateValues, formatDateInCalendar, 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).
+ * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - 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
+ *   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.
+ *
+ * @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
+ * @param bStart ISO 8601 date string for the second interval start, optionally calendar-annotated
+ * @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-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) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return [];
+    }
+    if (!isValidCalendarDate(aStart) ||
+        !isValidCalendarDate(aEnd) ||
+        !isValidCalendarDate(bStart) ||
+        !isValidCalendarDate(bEnd)) {
+        return [];
+    }
+    const calendar = calendarOfAllDateValues([aStart, aEnd, bStart, bEnd]);
+    if (!calendar) {
+        return [];
+    }
+    try {
+        const aS = parseCalendarDateValue(aStart);
+        const aE = parseCalendarDateValue(aEnd);
+        const bS = parseCalendarDateValue(bStart);
+        const bE = parseCalendarDateValue(bEnd);
+        if (Temporal.PlainDate.compare(aS, aE) > 0) {
+            return [];
+        }
+        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;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * 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).
+ * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns `[]` if either interval is invalid (`start > end`).
+ * - Returns `[]` on invalid input (wrong type, malformed strings).
+ *
+ * @param aStart ISO 8601 datetime string for the first interval start
+ * @param aEnd ISO 8601 datetime string for the first interval end
+ * @param bStart ISO 8601 datetime string for the second interval start
+ * @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("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<{
+    start: string;
+    end: string;
+}>;

package/dist/plain/interval/intervalDifferenceDateTime.js

@@ -0,0 +1,69 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { plainDateTime } from "../../regex/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).
+ * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns `[]` if either interval is invalid (`start > end`).
+ * - Returns `[]` on invalid input (wrong type, malformed strings).
+ *
+ * @param aStart ISO 8601 datetime string for the first interval start
+ * @param aEnd ISO 8601 datetime string for the first interval end
+ * @param bStart ISO 8601 datetime string for the second interval start
+ * @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("invalid", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // []
+ */
+export function intervalDifferenceDateTime(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return [];
+    }
+    if (!plainDateTime.test(aStart) ||
+        !plainDateTime.test(aEnd) ||
+        !plainDateTime.test(bStart) ||
+        !plainDateTime.test(bEnd)) {
+        return [];
+    }
+    try {
+        const aS = Temporal.PlainDateTime.from(aStart);
+        const aE = Temporal.PlainDateTime.from(aEnd);
+        const bS = Temporal.PlainDateTime.from(bStart);
+        const bE = Temporal.PlainDateTime.from(bEnd);
+        if (Temporal.PlainDateTime.compare(aS, aE) > 0) {
+            return [];
+        }
+        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;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * 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).
+ * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns `[]` if either interval is invalid (`start > end`).
+ * - Returns `[]` on invalid input (wrong type, malformed strings).
+ *
+ * @param aStart ISO 8601 time string for the first interval start
+ * @param aEnd ISO 8601 time string for the first interval end
+ * @param bStart ISO 8601 time string for the second interval start
+ * @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", "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("invalid", "17:00:00", "12:00:00", "13:00:00") // []
+ */
+export declare function intervalDifferenceTime(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/plain/interval/intervalDifferenceTime.js

@@ -0,0 +1,70 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { plainTime } from "../../regex/index.js";
+/**
+ * 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).
+ * - Returns `[{ start, end }, { start, end }]` when B is fully inside A with gaps on both sides.
+ * - Returns `[]` if either interval is invalid (`start > end`).
+ * - Returns `[]` on invalid input (wrong type, malformed strings).
+ *
+ * @param aStart ISO 8601 time string for the first interval start
+ * @param aEnd ISO 8601 time string for the first interval end
+ * @param bStart ISO 8601 time string for the second interval start
+ * @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", "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("invalid", "17:00:00", "12:00:00", "13:00:00") // []
+ */
+export function intervalDifferenceTime(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return [];
+    }
+    if (!plainTime.test(aStart) ||
+        !plainTime.test(aEnd) ||
+        !plainTime.test(bStart) ||
+        !plainTime.test(bEnd)) {
+        return [];
+    }
+    try {
+        const aS = Temporal.PlainTime.from(aStart);
+        const aE = Temporal.PlainTime.from(aEnd);
+        const bS = Temporal.PlainTime.from(bStart);
+        const bE = Temporal.PlainTime.from(bEnd);
+        if (Temporal.PlainTime.compare(aS, aE) > 0) {
+            return [];
+        }
+        if (Temporal.PlainTime.compare(bS, bE) > 0) {
+            return [];
+        }
+        const result = [];
+        // Left piece: A before B starts
+        if (Temporal.PlainTime.compare(aS, bS) < 0) {
+            const leftEnd = Temporal.PlainTime.compare(aE, bS) < 0
+                ? aE
+                : bS.subtract({ nanoseconds: 1 });
+            if (Temporal.PlainTime.compare(leftEnd, aS) >= 0) {
+                result.push({ start: aS.toString(), end: leftEnd.toString() });
+            }
+        }
+        // Right piece: A after B ends
+        if (Temporal.PlainTime.compare(aE, bE) > 0) {
+            result.push({
+                start: bE.add({ nanoseconds: 1 }).toString(),
+                end: aE.toString(),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Split a date interval into `n` equal-length sub-intervals.
+ *
+ * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
+ *   record's `end` equal to the next record's `start`.
+ * - `PlainDate` has no fractional-day representation, so each internal boundary is rounded to
+ *   the nearest whole day — when `totalDays` isn't evenly divisible by `n`, the resulting
+ *   sub-intervals differ by at most one day rather than being mathematically exact.
+ * - `n === 1` returns the original interval unchanged, as a single-element array.
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
+ * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
+ *   start/end, `start > end`).
+ * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). `start` and `end` must
+ *   carry the *same* calendar tag (or both be bare ISO); a mismatch returns `[]` (E5 decision
+ *   of record D4). Internal boundaries are computed in whole days (calendar-independent), then
+ *   re-formatted in the shared calendar.
+ *
+ * @param start ISO PlainDate string for the interval start, optionally calendar-annotated
+ * @param end ISO PlainDate string for the interval end, optionally calendar-annotated
+ * @param n number of equal sub-intervals to produce (positive integer)
+ * @returns array of `n` `{ start, end }` records, or `[]` on invalid input / mismatched calendars
+ *
+ * @example intervalDivideEquallyDate("2024-01-01", "2024-01-05", 4) // [{ start: "2024-01-01", end: "2024-01-02" }, { start: "2024-01-02", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-04" }, { start: "2024-01-04", end: "2024-01-05" }]
+ * @example intervalDivideEquallyDate("2024-01-01", "2024-01-10", 3) // [{ start: "2024-01-01", end: "2024-01-04" }, { start: "2024-01-04", end: "2024-01-07" }, { start: "2024-01-07", end: "2024-01-10" }]
+ * @example intervalDivideEquallyDate("2024-01-01", "2024-01-10", 1) // [{ start: "2024-01-01", end: "2024-01-10" }]
+ * @example intervalDivideEquallyDate("2024-01-01", "2024-01-01", 3) // [{ start: "2024-01-01", end: "2024-01-01" }, { start: "2024-01-01", end: "2024-01-01" }, { start: "2024-01-01", end: "2024-01-01" }]
+ * @example intervalDivideEquallyDate("2024-01-01", "2024-01-10", 0) // []
+ * @example intervalDivideEquallyDate("invalid", "2024-01-10", 3) // []
+ */
+export declare function intervalDivideEquallyDate(start: string, end: string, n: number): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/plain/interval/intervalDivideEquallyDate.js

@@ -0,0 +1,70 @@
+import { calendarOfAllDateValues, formatDateInCalendar, parseCalendarDateValue, } from "../../internal/index.js";
+import { isValidDateInterval } from "./validate/index.js";
+/**
+ * Split a date interval into `n` equal-length sub-intervals.
+ *
+ * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
+ *   record's `end` equal to the next record's `start`.
+ * - `PlainDate` has no fractional-day representation, so each internal boundary is rounded to
+ *   the nearest whole day — when `totalDays` isn't evenly divisible by `n`, the resulting
+ *   sub-intervals differ by at most one day rather than being mathematically exact.
+ * - `n === 1` returns the original interval unchanged, as a single-element array.
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
+ * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
+ *   start/end, `start > end`).
+ * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). `start` and `end` must
+ *   carry the *same* calendar tag (or both be bare ISO); a mismatch returns `[]` (E5 decision
+ *   of record D4). Internal boundaries are computed in whole days (calendar-independent), then
+ *   re-formatted in the shared calendar.
+ *
+ * @param start ISO PlainDate string for the interval start, optionally calendar-annotated
+ * @param end ISO PlainDate string for the interval end, optionally calendar-annotated
+ * @param n number of equal sub-intervals to produce (positive integer)
+ * @returns array of `n` `{ start, end }` records, or `[]` on invalid input / mismatched calendars
+ *
+ * @example intervalDivideEquallyDate("2024-01-01", "2024-01-05", 4) // [{ start: "2024-01-01", end: "2024-01-02" }, { start: "2024-01-02", end: "2024-01-03" }, { start: "2024-01-03", end: "2024-01-04" }, { start: "2024-01-04", end: "2024-01-05" }]
+ * @example intervalDivideEquallyDate("2024-01-01", "2024-01-10", 3) // [{ start: "2024-01-01", end: "2024-01-04" }, { start: "2024-01-04", end: "2024-01-07" }, { start: "2024-01-07", end: "2024-01-10" }]
+ * @example intervalDivideEquallyDate("2024-01-01", "2024-01-10", 1) // [{ start: "2024-01-01", end: "2024-01-10" }]
+ * @example intervalDivideEquallyDate("2024-01-01", "2024-01-01", 3) // [{ start: "2024-01-01", end: "2024-01-01" }, { start: "2024-01-01", end: "2024-01-01" }, { start: "2024-01-01", end: "2024-01-01" }]
+ * @example intervalDivideEquallyDate("2024-01-01", "2024-01-10", 0) // []
+ * @example intervalDivideEquallyDate("invalid", "2024-01-10", 3) // []
+ */
+export function intervalDivideEquallyDate(start, end, n) {
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+        return [];
+    }
+    if (!isValidDateInterval(start, end)) {
+        return [];
+    }
+    const calendar = calendarOfAllDateValues([start, end]);
+    if (!calendar) {
+        return [];
+    }
+    try {
+        const startVal = parseCalendarDateValue(start);
+        const endVal = parseCalendarDateValue(end);
+        if (startVal.equals(endVal)) {
+            return Array.from({ length: n }, () => ({
+                start: formatDateInCalendar(startVal, calendar),
+                end: formatDateInCalendar(endVal, calendar),
+            }));
+        }
+        const totalDays = startVal.until(endVal, { largestUnit: "day" }).days;
+        const boundaries = [startVal];
+        for (let i = 1; i < n; i++) {
+            boundaries.push(startVal.add({ days: Math.round((totalDays * i) / n) }));
+        }
+        boundaries.push(endVal);
+        const result = [];
+        for (let i = 0; i < boundaries.length - 1; i++) {
+            result.push({
+                start: formatDateInCalendar(boundaries[i], calendar),
+                end: formatDateInCalendar(boundaries[i + 1], calendar),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Split a datetime interval into `n` equal-length sub-intervals.
+ *
+ * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
+ *   record's `end` equal to the next record's `start`.
+ * - Boundaries are computed from the total elapsed nanoseconds (via `Duration.prototype.total`
+ *   with `relativeTo` set to `start`), so the split is exact whenever the total divides evenly
+ *   by `n`, and off by at most one nanosecond otherwise.
+ * - `n === 1` returns the original interval unchanged, as a single-element array.
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
+ * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
+ *   start/end, `start > end`).
+ *
+ * @param start ISO PlainDateTime string for the interval start
+ * @param end ISO PlainDateTime string for the interval end
+ * @param n number of equal sub-intervals to produce (positive integer)
+ * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalDivideEquallyDateTime("2024-01-01T00:00:00", "2024-01-04T00:00:00", 3) // [{ start: "2024-01-01T00:00:00", end: "2024-01-02T00:00:00" }, { start: "2024-01-02T00:00:00", end: "2024-01-03T00:00:00" }, { start: "2024-01-03T00:00:00", end: "2024-01-04T00:00:00" }]
+ * @example intervalDivideEquallyDateTime("2024-01-01T00:00:00", "2024-01-04T00:00:00", 1) // [{ start: "2024-01-01T00:00:00", end: "2024-01-04T00:00:00" }]
+ * @example intervalDivideEquallyDateTime("2024-01-01T00:00:00", "2024-01-04T00:00:00", 0) // []
+ * @example intervalDivideEquallyDateTime("invalid", "2024-01-04T00:00:00", 3) // []
+ */
+export declare function intervalDivideEquallyDateTime(start: string, end: string, n: number): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/plain/interval/intervalDivideEquallyDateTime.js

@@ -0,0 +1,62 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTimeInterval } from "./validate/index.js";
+/**
+ * Split a datetime interval into `n` equal-length sub-intervals.
+ *
+ * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
+ *   record's `end` equal to the next record's `start`.
+ * - Boundaries are computed from the total elapsed nanoseconds (via `Duration.prototype.total`
+ *   with `relativeTo` set to `start`), so the split is exact whenever the total divides evenly
+ *   by `n`, and off by at most one nanosecond otherwise.
+ * - `n === 1` returns the original interval unchanged, as a single-element array.
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
+ * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
+ *   start/end, `start > end`).
+ *
+ * @param start ISO PlainDateTime string for the interval start
+ * @param end ISO PlainDateTime string for the interval end
+ * @param n number of equal sub-intervals to produce (positive integer)
+ * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalDivideEquallyDateTime("2024-01-01T00:00:00", "2024-01-04T00:00:00", 3) // [{ start: "2024-01-01T00:00:00", end: "2024-01-02T00:00:00" }, { start: "2024-01-02T00:00:00", end: "2024-01-03T00:00:00" }, { start: "2024-01-03T00:00:00", end: "2024-01-04T00:00:00" }]
+ * @example intervalDivideEquallyDateTime("2024-01-01T00:00:00", "2024-01-04T00:00:00", 1) // [{ start: "2024-01-01T00:00:00", end: "2024-01-04T00:00:00" }]
+ * @example intervalDivideEquallyDateTime("2024-01-01T00:00:00", "2024-01-04T00:00:00", 0) // []
+ * @example intervalDivideEquallyDateTime("invalid", "2024-01-04T00:00:00", 3) // []
+ */
+export function intervalDivideEquallyDateTime(start, end, n) {
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+        return [];
+    }
+    if (!isValidDateTimeInterval(start, end)) {
+        return [];
+    }
+    try {
+        const startVal = Temporal.PlainDateTime.from(start);
+        const endVal = Temporal.PlainDateTime.from(end);
+        if (startVal.equals(endVal)) {
+            return Array.from({ length: n }, () => ({
+                start: startVal.toString(),
+                end: endVal.toString(),
+            }));
+        }
+        const totalNs = startVal
+            .until(endVal, { largestUnit: "nanosecond" })
+            .total({ unit: "nanosecond", relativeTo: startVal });
+        const boundaries = [startVal];
+        for (let i = 1; i < n; i++) {
+            boundaries.push(startVal.add({ nanoseconds: Math.round((totalNs * i) / n) }));
+        }
+        boundaries.push(endVal);
+        const result = [];
+        for (let i = 0; i < boundaries.length - 1; i++) {
+            result.push({
+                start: boundaries[i].toString(),
+                end: boundaries[i + 1].toString(),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Split a time interval into `n` equal-length sub-intervals.
+ *
+ * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
+ *   record's `end` equal to the next record's `start`.
+ * - Time units are fixed-length, so boundaries are computed to nanosecond precision — the split
+ *   is exact whenever the total nanoseconds divides evenly by `n`, and off by at most one
+ *   nanosecond otherwise.
+ * - `n === 1` returns the original interval unchanged, as a single-element array.
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
+ * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
+ *   start/end, `start > end`).
+ *
+ * @param start ISO PlainTime string for the interval start
+ * @param end ISO PlainTime string for the interval end
+ * @param n number of equal sub-intervals to produce (positive integer)
+ * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalDivideEquallyTime("09:00:00", "17:00:00", 4) // [{ start: "09:00:00", end: "11:00:00" }, { start: "11:00:00", end: "13:00:00" }, { start: "13:00:00", end: "15:00:00" }, { start: "15:00:00", end: "17:00:00" }]
+ * @example intervalDivideEquallyTime("09:00:00", "17:00:00", 3) // [{ start: "09:00:00", end: "11:40:00" }, { start: "11:40:00", end: "14:20:00" }, { start: "14:20:00", end: "17:00:00" }]
+ * @example intervalDivideEquallyTime("09:00:00", "17:00:00", 1) // [{ start: "09:00:00", end: "17:00:00" }]
+ * @example intervalDivideEquallyTime("09:00:00", "17:00:00", 0) // []
+ * @example intervalDivideEquallyTime("invalid", "17:00:00", 3) // []
+ */
+export declare function intervalDivideEquallyTime(start: string, end: string, n: number): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/plain/interval/intervalDivideEquallyTime.js

@@ -0,0 +1,63 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeInterval } from "./validate/index.js";
+/**
+ * Split a time interval into `n` equal-length sub-intervals.
+ *
+ * - Returns an array of `n` `{ start, end }` records that tile the original interval, each
+ *   record's `end` equal to the next record's `start`.
+ * - Time units are fixed-length, so boundaries are computed to nanosecond precision — the split
+ *   is exact whenever the total nanoseconds divides evenly by `n`, and off by at most one
+ *   nanosecond otherwise.
+ * - `n === 1` returns the original interval unchanged, as a single-element array.
+ * - A zero-length interval (`start === end`) returns `n` identical zero-length sub-intervals.
+ * - Returns `[]` when `n` is not a positive integer, or on invalid input (unparseable
+ *   start/end, `start > end`).
+ *
+ * @param start ISO PlainTime string for the interval start
+ * @param end ISO PlainTime string for the interval end
+ * @param n number of equal sub-intervals to produce (positive integer)
+ * @returns array of `n` `{ start, end }` records, or `[]` on invalid input
+ *
+ * @example intervalDivideEquallyTime("09:00:00", "17:00:00", 4) // [{ start: "09:00:00", end: "11:00:00" }, { start: "11:00:00", end: "13:00:00" }, { start: "13:00:00", end: "15:00:00" }, { start: "15:00:00", end: "17:00:00" }]
+ * @example intervalDivideEquallyTime("09:00:00", "17:00:00", 3) // [{ start: "09:00:00", end: "11:40:00" }, { start: "11:40:00", end: "14:20:00" }, { start: "14:20:00", end: "17:00:00" }]
+ * @example intervalDivideEquallyTime("09:00:00", "17:00:00", 1) // [{ start: "09:00:00", end: "17:00:00" }]
+ * @example intervalDivideEquallyTime("09:00:00", "17:00:00", 0) // []
+ * @example intervalDivideEquallyTime("invalid", "17:00:00", 3) // []
+ */
+export function intervalDivideEquallyTime(start, end, n) {
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+        return [];
+    }
+    if (!isValidTimeInterval(start, end)) {
+        return [];
+    }
+    try {
+        const startVal = Temporal.PlainTime.from(start);
+        const endVal = Temporal.PlainTime.from(end);
+        if (startVal.equals(endVal)) {
+            return Array.from({ length: n }, () => ({
+                start: startVal.toString(),
+                end: endVal.toString(),
+            }));
+        }
+        const totalNs = startVal
+            .until(endVal, { largestUnit: "nanosecond" })
+            .total("nanosecond");
+        const boundaries = [startVal];
+        for (let i = 1; i < n; i++) {
+            boundaries.push(startVal.add({ nanoseconds: Math.round((totalNs * i) / n) }));
+        }
+        boundaries.push(endVal);
+        const result = [];
+        for (let i = 0; i < boundaries.length - 1; i++) {
+            result.push({
+                start: boundaries[i].toString(),
+                end: boundaries[i + 1].toString(),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Return true when interval B is fully contained within interval A — every instant of B
+ * falls within A.
+ *
+ * - Uses `Temporal.PlainDate.compare` for comparison.
+ * - Equivalent to 4-argument `intervalContainsDate(aStart, aEnd, bStart, bEnd)`.
+ * - Returns `false` if either interval is invalid (`start > end`).
+ * - Returns `false` on invalid input (wrong type, malformed strings).
+ * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Ordering is
+ *   calendar-independent, so arguments may carry different or no calendar tags (D4).
+ *
+ * @param aStart ISO 8601 date string for the outer interval start, optionally calendar-annotated
+ * @param aEnd ISO 8601 date string for the outer interval end, optionally calendar-annotated
+ * @param bStart ISO 8601 date string for the inner interval start, optionally calendar-annotated
+ * @param bEnd ISO 8601 date string for the inner interval end, optionally calendar-annotated
+ * @returns true if B is fully contained in A, or false on invalid input
+ *
+ * @example intervalEngulfsDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-07-01") // true
+ * @example intervalEngulfsDate("2024-01-01", "2024-12-31", "2024-01-01", "2024-12-31") // true (equal intervals)
+ * @example intervalEngulfsDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-12-31") // true
+ * @example intervalEngulfsDate("2024-06-01", "2024-07-01", "2024-01-01", "2024-12-31") // false
+ * @example intervalEngulfsDate("invalid", "2024-12-31", "2024-06-01", "2024-07-01") // false
+ */
+export declare function intervalEngulfsDate(aStart: string, aEnd: string, bStart: string, bEnd: string): boolean;