@northguild/gmt 1.14.2

package/dist/plain/interval/intervalXorAllDate.js

@@ -0,0 +1,89 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarOfAllDateValues, formatDateInCalendar, parseCalendarDateValue, } from "../../internal/index.js";
+import { isValidDateInterval } from "./validate/index.js";
+/**
+ * Return the symmetric difference across a list of date intervals — the set of dates covered
+ * by an odd number of the input intervals.
+ *
+ * - List-form generalization of `intervalXorDate`, which is pairwise only.
+ * - Implemented as a coverage sweep: each interval contributes a `+1` at its start and a `-1`
+ *   the day after its end; the result is every maximal run where the running coverage count is
+ *   odd. For two intervals this reduces to exactly `intervalXorDate`'s pairwise result.
+ * - Order of the input list does not matter; the result is sorted by start.
+ * - Returns `[]` for an empty list, and `[]` when every date is covered an even number of times
+ *   (e.g. two identical intervals cancel out).
+ * - Returns `[]` when `intervals` is not an array, when any element is not a
+ *   `{ start, end }` record of valid ISO PlainDate strings, or when any element has
+ *   `start > end`.
+ * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Since the result is
+ *   date *values*, every `start`/`end` across the whole list must carry the *same* calendar tag
+ *   (or all be bare ISO); any mismatch returns `[]` (E5 decision of record D4). This also makes
+ *   `.equals()`'s dedup of coincident sweep events safe — same-calendar `PlainDate`s compare
+ *   equal correctly, unlike cross-calendar ones.
+ *
+ * @param intervals array of `{ start, end }` records, optionally calendar-annotated
+ * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input / mismatched calendars
+ *
+ * @example intervalXorAllDate([{ start: "2024-01-01", end: "2024-01-10" }, { start: "2024-01-05", end: "2024-01-15" }, { start: "2024-01-08", end: "2024-01-20" }]) // [{ start: "2024-01-01", end: "2024-01-04" }, { start: "2024-01-08", end: "2024-01-10" }, { start: "2024-01-16", end: "2024-01-20" }]
+ * @example intervalXorAllDate([{ start: "2024-01-01", end: "2024-01-05" }, { start: "2024-01-01", end: "2024-01-05" }]) // [] (identical intervals cancel out)
+ * @example intervalXorAllDate([]) // []
+ * @example intervalXorAllDate([{ start: "2024-01-10", end: "2024-01-01" }]) // []
+ */
+export function intervalXorAllDate(intervals) {
+    if (!Array.isArray(intervals) || intervals.length === 0) {
+        return [];
+    }
+    if (!intervals.every((interval) => interval &&
+        typeof interval === "object" &&
+        isValidDateInterval(interval.start, interval.end))) {
+        return [];
+    }
+    const calendar = calendarOfAllDateValues(intervals.flatMap((interval) => [interval.start, interval.end]));
+    if (!calendar) {
+        return [];
+    }
+    try {
+        const events = [];
+        for (const interval of intervals) {
+            const start = parseCalendarDateValue(interval.start);
+            // The closing event fires the day after `end`, so `end` itself stays covered.
+            const closesAfter = parseCalendarDateValue(interval.end).add({
+                days: 1,
+            });
+            events.push({ point: start, delta: 1 });
+            events.push({ point: closesAfter, delta: -1 });
+        }
+        events.sort((a, b) => Temporal.PlainDate.compare(a.point, b.point));
+        const grouped = [];
+        for (const event of events) {
+            const last = grouped[grouped.length - 1];
+            if (last && last.point.equals(event.point)) {
+                last.delta += event.delta;
+            }
+            else {
+                grouped.push({ point: event.point, delta: event.delta });
+            }
+        }
+        const result = [];
+        let coverage = 0;
+        let runStart = null;
+        for (const group of grouped) {
+            const previousCoverage = coverage;
+            coverage += group.delta;
+            if (previousCoverage % 2 === 0 && coverage % 2 === 1) {
+                runStart = group.point;
+            }
+            else if (previousCoverage % 2 === 1 && coverage % 2 === 0 && runStart) {
+                result.push({
+                    start: formatDateInCalendar(runStart, calendar),
+                    end: formatDateInCalendar(group.point.subtract({ days: 1 }), calendar),
+                });
+                runStart = null;
+            }
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Return the symmetric difference across a list of datetime intervals — the set of instants
+ * covered by an odd number of the input intervals.
+ *
+ * - List-form generalization of `intervalXorDateTime`, which is pairwise only.
+ * - Implemented as a coverage sweep: each interval contributes a `+1` at its start and a `-1`
+ *   one nanosecond after its end; the result is every maximal run where the running coverage
+ *   count is odd. For two intervals this reduces to exactly `intervalXorDateTime`'s pairwise
+ *   result.
+ * - Order of the input list does not matter; the result is sorted by start.
+ * - Returns `[]` for an empty list, and `[]` when every instant is covered an even number of
+ *   times (e.g. two identical intervals cancel out).
+ * - Returns `[]` when `intervals` is not an array, when any element is not a
+ *   `{ start, end }` record of valid ISO PlainDateTime strings, or when any element has
+ *   `start > end`.
+ *
+ * @param intervals array of `{ start, end }` records
+ * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
+ *
+ * @example intervalXorAllDateTime([{ start: "2024-01-01T00:00:00", end: "2024-01-10T00:00:00" }, { start: "2024-01-05T00:00:00", end: "2024-01-15T00:00:00" }]) // [{ start: "2024-01-01T00:00:00", end: "2024-01-04T23:59:59.999999999" }, { start: "2024-01-10T00:00:00.000000001", end: "2024-01-15T00:00:00" }]
+ * @example intervalXorAllDateTime([]) // []
+ */
+export declare function intervalXorAllDateTime(intervals: Array<{
+    start: string;
+    end: string;
+}>): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/plain/interval/intervalXorAllDateTime.js

@@ -0,0 +1,77 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTimeInterval } from "./validate/index.js";
+/**
+ * Return the symmetric difference across a list of datetime intervals — the set of instants
+ * covered by an odd number of the input intervals.
+ *
+ * - List-form generalization of `intervalXorDateTime`, which is pairwise only.
+ * - Implemented as a coverage sweep: each interval contributes a `+1` at its start and a `-1`
+ *   one nanosecond after its end; the result is every maximal run where the running coverage
+ *   count is odd. For two intervals this reduces to exactly `intervalXorDateTime`'s pairwise
+ *   result.
+ * - Order of the input list does not matter; the result is sorted by start.
+ * - Returns `[]` for an empty list, and `[]` when every instant is covered an even number of
+ *   times (e.g. two identical intervals cancel out).
+ * - Returns `[]` when `intervals` is not an array, when any element is not a
+ *   `{ start, end }` record of valid ISO PlainDateTime strings, or when any element has
+ *   `start > end`.
+ *
+ * @param intervals array of `{ start, end }` records
+ * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
+ *
+ * @example intervalXorAllDateTime([{ start: "2024-01-01T00:00:00", end: "2024-01-10T00:00:00" }, { start: "2024-01-05T00:00:00", end: "2024-01-15T00:00:00" }]) // [{ start: "2024-01-01T00:00:00", end: "2024-01-04T23:59:59.999999999" }, { start: "2024-01-10T00:00:00.000000001", end: "2024-01-15T00:00:00" }]
+ * @example intervalXorAllDateTime([]) // []
+ */
+export function intervalXorAllDateTime(intervals) {
+    if (!Array.isArray(intervals) || intervals.length === 0) {
+        return [];
+    }
+    if (!intervals.every((interval) => interval &&
+        typeof interval === "object" &&
+        isValidDateTimeInterval(interval.start, interval.end))) {
+        return [];
+    }
+    try {
+        const events = [];
+        for (const interval of intervals) {
+            const start = Temporal.PlainDateTime.from(interval.start);
+            const closesAfter = Temporal.PlainDateTime.from(interval.end).add({
+                nanoseconds: 1,
+            });
+            events.push({ point: start, delta: 1 });
+            events.push({ point: closesAfter, delta: -1 });
+        }
+        events.sort((a, b) => Temporal.PlainDateTime.compare(a.point, b.point));
+        const grouped = [];
+        for (const event of events) {
+            const last = grouped[grouped.length - 1];
+            if (last && last.point.equals(event.point)) {
+                last.delta += event.delta;
+            }
+            else {
+                grouped.push({ point: event.point, delta: event.delta });
+            }
+        }
+        const result = [];
+        let coverage = 0;
+        let runStart = null;
+        for (const group of grouped) {
+            const previousCoverage = coverage;
+            coverage += group.delta;
+            if (previousCoverage % 2 === 0 && coverage % 2 === 1) {
+                runStart = group.point;
+            }
+            else if (previousCoverage % 2 === 1 && coverage % 2 === 0 && runStart) {
+                result.push({
+                    start: runStart.toString(),
+                    end: group.point.subtract({ nanoseconds: 1 }).toString(),
+                });
+                runStart = null;
+            }
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Return the symmetric difference across a list of time intervals — the set of clock times
+ * covered by an odd number of the input intervals.
+ *
+ * - List-form generalization of `intervalXorTime`, which is pairwise only.
+ * - Implemented as a coverage sweep: each interval contributes a `+1` at its start and a `-1`
+ *   one nanosecond after its end; the result is every maximal run where the running coverage
+ *   count is odd. For two intervals this reduces to exactly `intervalXorTime`'s pairwise result.
+ * - Order of the input list does not matter; the result is sorted by start.
+ * - Returns `[]` for an empty list, and `[]` when every clock time is covered an even number of
+ *   times (e.g. two identical intervals cancel out).
+ * - Returns `[]` when `intervals` is not an array, when any element is not a
+ *   `{ start, end }` record of valid ISO PlainTime strings, or when any element has
+ *   `start > end`.
+ *
+ * @param intervals array of `{ start, end }` records
+ * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
+ *
+ * @example intervalXorAllTime([{ start: "09:00:00", end: "12:00:00" }, { start: "11:00:00", end: "15:00:00" }]) // [{ start: "09:00:00", end: "10:59:59.999999999" }, { start: "12:00:00.000000001", end: "15:00:00" }]
+ * @example intervalXorAllTime([]) // []
+ */
+export declare function intervalXorAllTime(intervals: Array<{
+    start: string;
+    end: string;
+}>): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/plain/interval/intervalXorAllTime.js

@@ -0,0 +1,76 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeInterval } from "./validate/index.js";
+/**
+ * Return the symmetric difference across a list of time intervals — the set of clock times
+ * covered by an odd number of the input intervals.
+ *
+ * - List-form generalization of `intervalXorTime`, which is pairwise only.
+ * - Implemented as a coverage sweep: each interval contributes a `+1` at its start and a `-1`
+ *   one nanosecond after its end; the result is every maximal run where the running coverage
+ *   count is odd. For two intervals this reduces to exactly `intervalXorTime`'s pairwise result.
+ * - Order of the input list does not matter; the result is sorted by start.
+ * - Returns `[]` for an empty list, and `[]` when every clock time is covered an even number of
+ *   times (e.g. two identical intervals cancel out).
+ * - Returns `[]` when `intervals` is not an array, when any element is not a
+ *   `{ start, end }` record of valid ISO PlainTime strings, or when any element has
+ *   `start > end`.
+ *
+ * @param intervals array of `{ start, end }` records
+ * @returns array of `{ start, end }` records covered an odd number of times, or `[]` on invalid input
+ *
+ * @example intervalXorAllTime([{ start: "09:00:00", end: "12:00:00" }, { start: "11:00:00", end: "15:00:00" }]) // [{ start: "09:00:00", end: "10:59:59.999999999" }, { start: "12:00:00.000000001", end: "15:00:00" }]
+ * @example intervalXorAllTime([]) // []
+ */
+export function intervalXorAllTime(intervals) {
+    if (!Array.isArray(intervals) || intervals.length === 0) {
+        return [];
+    }
+    if (!intervals.every((interval) => interval &&
+        typeof interval === "object" &&
+        isValidTimeInterval(interval.start, interval.end))) {
+        return [];
+    }
+    try {
+        const events = [];
+        for (const interval of intervals) {
+            const start = Temporal.PlainTime.from(interval.start);
+            const closesAfter = Temporal.PlainTime.from(interval.end).add({
+                nanoseconds: 1,
+            });
+            events.push({ point: start, delta: 1 });
+            events.push({ point: closesAfter, delta: -1 });
+        }
+        events.sort((a, b) => Temporal.PlainTime.compare(a.point, b.point));
+        const grouped = [];
+        for (const event of events) {
+            const last = grouped[grouped.length - 1];
+            if (last && last.point.equals(event.point)) {
+                last.delta += event.delta;
+            }
+            else {
+                grouped.push({ point: event.point, delta: event.delta });
+            }
+        }
+        const result = [];
+        let coverage = 0;
+        let runStart = null;
+        for (const group of grouped) {
+            const previousCoverage = coverage;
+            coverage += group.delta;
+            if (previousCoverage % 2 === 0 && coverage % 2 === 1) {
+                runStart = group.point;
+            }
+            else if (previousCoverage % 2 === 1 && coverage % 2 === 0 && runStart) {
+                result.push({
+                    start: runStart.toString(),
+                    end: group.point.subtract({ nanoseconds: 1 }).toString(),
+                });
+                runStart = null;
+            }
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Return the symmetric difference of two date intervals — time covered by exactly one interval.
+ *
+ * - Uses `Temporal.PlainDate.compare` for comparison.
+ * - Returns `[]` when intervals are identical or both invalid.
+ * - Returns `[{ start, end }]` when one interval fully contains the other.
+ * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap (two non-overlapping pieces).
+ * - 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 the symmetric difference, or `[]` on invalid input / mismatched calendars
+ *
+ * @example intervalXorDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // [{ start: "2024-01-01", end: "2024-03-31" }, { start: "2024-07-01", end: "2024-12-31" }]
+ * @example intervalXorDate("2024-01-01", "2024-12-31", "2024-04-01", "2024-06-30") // [{ start: "2024-01-01", end: "2024-03-31" }, { start: "2024-07-01", end: "2024-12-31" }]
+ * @example intervalXorDate("2024-01-01", "2024-12-31", "2024-01-01", "2024-12-31") // []
+ * @example intervalXorDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // [{ start: "2024-01-01", end: "2024-06-30" }, { start: "2024-07-01", end: "2024-12-31" }]
+ * @example intervalXorDate("invalid", "2024-06-30", "2024-07-01", "2024-12-31") // []
+ */
+export declare function intervalXorDate(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/plain/interval/intervalXorDate.js

@@ -0,0 +1,106 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarOfAllDateValues, formatDateInCalendar, parseCalendarDateValue, } from "../../internal/index.js";
+import { isValidCalendarDate } from "../validate/index.js";
+/**
+ * Return the symmetric difference of two date intervals — time covered by exactly one interval.
+ *
+ * - Uses `Temporal.PlainDate.compare` for comparison.
+ * - Returns `[]` when intervals are identical or both invalid.
+ * - Returns `[{ start, end }]` when one interval fully contains the other.
+ * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap (two non-overlapping pieces).
+ * - 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 the symmetric difference, or `[]` on invalid input / mismatched calendars
+ *
+ * @example intervalXorDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // [{ start: "2024-01-01", end: "2024-03-31" }, { start: "2024-07-01", end: "2024-12-31" }]
+ * @example intervalXorDate("2024-01-01", "2024-12-31", "2024-04-01", "2024-06-30") // [{ start: "2024-01-01", end: "2024-03-31" }, { start: "2024-07-01", end: "2024-12-31" }]
+ * @example intervalXorDate("2024-01-01", "2024-12-31", "2024-01-01", "2024-12-31") // []
+ * @example intervalXorDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // [{ start: "2024-01-01", end: "2024-06-30" }, { start: "2024-07-01", end: "2024-12-31" }]
+ * @example intervalXorDate("invalid", "2024-06-30", "2024-07-01", "2024-12-31") // []
+ */
+export function intervalXorDate(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 = [];
+        // If intervals don't overlap, return both as-is
+        if (Temporal.PlainDate.compare(aE, bS) < 0 ||
+            Temporal.PlainDate.compare(bE, aS) < 0) {
+            return [
+                {
+                    start: formatDateInCalendar(aS, calendar),
+                    end: formatDateInCalendar(aE, calendar),
+                },
+                {
+                    start: formatDateInCalendar(bS, calendar),
+                    end: formatDateInCalendar(bE, calendar),
+                },
+            ];
+        }
+        // Left piece: A before B starts
+        if (Temporal.PlainDate.compare(aS, bS) < 0) {
+            result.push({
+                start: formatDateInCalendar(aS, calendar),
+                end: formatDateInCalendar(bS.subtract({ days: 1 }), 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),
+            });
+        }
+        // Left piece: B before A starts
+        if (Temporal.PlainDate.compare(bS, aS) < 0) {
+            result.push({
+                start: formatDateInCalendar(bS, calendar),
+                end: formatDateInCalendar(aS.subtract({ days: 1 }), calendar),
+            });
+        }
+        // Right piece: B after A ends
+        if (Temporal.PlainDate.compare(bE, aE) > 0) {
+            result.push({
+                start: formatDateInCalendar(aE.add({ days: 1 }), calendar),
+                end: formatDateInCalendar(bE, calendar),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Return the symmetric difference of two datetime intervals — time covered by exactly one interval.
+ *
+ * - Uses `Temporal.PlainDateTime.compare` for comparison.
+ * - Returns `[]` when intervals are identical or both invalid.
+ * - Returns `[{ start, end }]` when one interval fully contains the other.
+ * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap.
+ * - 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 the symmetric difference, or `[]` on invalid input
+ *
+ * @example intervalXorDateTime("2024-01-01T09:00:00", "2024-06-30T12:00:00", "2024-04-01T11:00:00", "2024-12-31T17:00:00") // [{ start: "2024-01-01T09:00:00", end: "2024-03-31T17:00:00" }, { start: "2024-06-30T12:00:01", end: "2024-12-31T17:00:00" }]
+ * @example intervalXorDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-04-01T11:00:00", "2024-06-30T12:00:00") // [{ start: "2024-01-01T09:00:00", end: "2024-03-31T17:00:00" }, { start: "2024-06-30T12:00:01", end: "2024-12-31T17:00:00" }]
+ * @example intervalXorDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-01-01T09:00:00", "2024-12-31T17:00:00") // []
+ * @example intervalXorDateTime("invalid", "2024-06-30T12:00:00", "2024-07-01T13:00:00", "2024-12-31T17:00:00") // []
+ */
+export declare function intervalXorDateTime(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/plain/interval/intervalXorDateTime.js

@@ -0,0 +1,90 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { plainDateTime } from "../../regex/index.js";
+/**
+ * Return the symmetric difference of two datetime intervals — time covered by exactly one interval.
+ *
+ * - Uses `Temporal.PlainDateTime.compare` for comparison.
+ * - Returns `[]` when intervals are identical or both invalid.
+ * - Returns `[{ start, end }]` when one interval fully contains the other.
+ * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap.
+ * - 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 the symmetric difference, or `[]` on invalid input
+ *
+ * @example intervalXorDateTime("2024-01-01T09:00:00", "2024-06-30T12:00:00", "2024-04-01T11:00:00", "2024-12-31T17:00:00") // [{ start: "2024-01-01T09:00:00", end: "2024-03-31T17:00:00" }, { start: "2024-06-30T12:00:01", end: "2024-12-31T17:00:00" }]
+ * @example intervalXorDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-04-01T11:00:00", "2024-06-30T12:00:00") // [{ start: "2024-01-01T09:00:00", end: "2024-03-31T17:00:00" }, { start: "2024-06-30T12:00:01", end: "2024-12-31T17:00:00" }]
+ * @example intervalXorDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-01-01T09:00:00", "2024-12-31T17:00:00") // []
+ * @example intervalXorDateTime("invalid", "2024-06-30T12:00:00", "2024-07-01T13:00:00", "2024-12-31T17:00:00") // []
+ */
+export function intervalXorDateTime(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 = [];
+        // If intervals don't overlap, return both as-is
+        if (Temporal.PlainDateTime.compare(aE, bS) < 0 ||
+            Temporal.PlainDateTime.compare(bE, aS) < 0) {
+            return [
+                { start: aS.toString(), end: aE.toString() },
+                { start: bS.toString(), end: bE.toString() },
+            ];
+        }
+        // Left piece: A before B starts
+        if (Temporal.PlainDateTime.compare(aS, bS) < 0) {
+            result.push({
+                start: aS.toString(),
+                end: bS.subtract({ nanoseconds: 1 }).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(),
+            });
+        }
+        // Left piece: B before A starts
+        if (Temporal.PlainDateTime.compare(bS, aS) < 0) {
+            result.push({
+                start: bS.toString(),
+                end: aS.subtract({ nanoseconds: 1 }).toString(),
+            });
+        }
+        // Right piece: B after A ends
+        if (Temporal.PlainDateTime.compare(bE, aE) > 0) {
+            result.push({
+                start: aE.add({ nanoseconds: 1 }).toString(),
+                end: bE.toString(),
+            });
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Return the symmetric difference of two time intervals — time covered by exactly one interval.
+ *
+ * - Uses `Temporal.PlainTime.compare` for comparison.
+ * - Returns `[]` when intervals are identical or both invalid.
+ * - Returns `[{ start, end }]` when one interval fully contains the other.
+ * - Returns `[{ start, end }, { start, end }]` when intervals partially overlap.
+ * - 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 the symmetric difference, or `[]` on invalid input
+ *
+ * @example intervalXorTime("09:00:00", "12:00:00", "11:00:00", "17:00:00") // [{ start: "09:00:00", end: "10:59:59" }, { start: "12:00:01", end: "17:00:00" }]
+ * @example intervalXorTime("09:00:00", "17:00:00", "11:00:00", "12:00:00") // [{ start: "09:00:00", end: "10:59:59" }, { start: "12:00:01", end: "17:00:00" }]
+ * @example intervalXorTime("09:00:00", "17:00:00", "09:00:00", "17:00:00") // []
+ * @example intervalXorTime("09:00:00", "12:00:00", "13:00:00", "17:00:00") // [{ start: "09:00:00", end: "12:00:00" }, { start: "13:00:00", end: "17:00:00" }]
+ * @example intervalXorTime("invalid", "12:00:00", "13:00:00", "17:00:00") // []
+ */
+export declare function intervalXorTime(aStart: string, aEnd: string, bStart: string, bEnd: string): Array<{
+    start: string;
+    end: string;
+}>;