@northguild/gmt 1.14.2

package/dist/plain/interval/intervalEngulfsDate.js

@@ -0,0 +1,57 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseCalendarDateValue } from "../../internal/index.js";
+import { isValidCalendarDate } from "../validate/index.js";
+/**
+ * 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 function intervalEngulfsDate(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return false;
+    }
+    if (!isValidCalendarDate(aStart) ||
+        !isValidCalendarDate(aEnd) ||
+        !isValidCalendarDate(bStart) ||
+        !isValidCalendarDate(bEnd)) {
+        return false;
+    }
+    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 false;
+        }
+        if (Temporal.PlainDate.compare(bS, bE) > 0) {
+            return false;
+        }
+        return (Temporal.PlainDate.compare(aS, bS) <= 0 &&
+            Temporal.PlainDate.compare(bE, aE) <= 0);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Return true when interval B is fully contained within interval A — every instant of B
+ * falls within A.
+ *
+ * - Uses `Temporal.PlainDateTime.compare` for comparison.
+ * - Equivalent to 4-argument `intervalContainsDateTime(aStart, aEnd, bStart, bEnd)`.
+ * - Returns `false` if either interval is invalid (`start > end`).
+ * - Returns `false` on invalid input (wrong type, malformed strings).
+ *
+ * @param aStart ISO 8601 datetime string for the outer interval start
+ * @param aEnd ISO 8601 datetime string for the outer interval end
+ * @param bStart ISO 8601 datetime string for the inner interval start
+ * @param bEnd ISO 8601 datetime string for the inner interval end
+ * @returns true if B is fully contained in A, or false on invalid input
+ *
+ * @example intervalEngulfsDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // true
+ * @example intervalEngulfsDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-01-01T09:00:00", "2024-12-31T17:00:00") // true (equal intervals)
+ * @example intervalEngulfsDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-01-01T09:00:00", "2024-06-30T12:00:00") // true
+ * @example intervalEngulfsDateTime("2024-06-01T12:00:00", "2024-07-01T13:00:00", "2024-01-01T09:00:00", "2024-12-31T17:00:00") // false
+ * @example intervalEngulfsDateTime("invalid", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // false
+ */
+export declare function intervalEngulfsDateTime(aStart: string, aEnd: string, bStart: string, bEnd: string): boolean;

package/dist/plain/interval/intervalEngulfsDateTime.js

@@ -0,0 +1,54 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { plainDateTime } from "../../regex/index.js";
+/**
+ * Return true when interval B is fully contained within interval A — every instant of B
+ * falls within A.
+ *
+ * - Uses `Temporal.PlainDateTime.compare` for comparison.
+ * - Equivalent to 4-argument `intervalContainsDateTime(aStart, aEnd, bStart, bEnd)`.
+ * - Returns `false` if either interval is invalid (`start > end`).
+ * - Returns `false` on invalid input (wrong type, malformed strings).
+ *
+ * @param aStart ISO 8601 datetime string for the outer interval start
+ * @param aEnd ISO 8601 datetime string for the outer interval end
+ * @param bStart ISO 8601 datetime string for the inner interval start
+ * @param bEnd ISO 8601 datetime string for the inner interval end
+ * @returns true if B is fully contained in A, or false on invalid input
+ *
+ * @example intervalEngulfsDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // true
+ * @example intervalEngulfsDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-01-01T09:00:00", "2024-12-31T17:00:00") // true (equal intervals)
+ * @example intervalEngulfsDateTime("2024-01-01T09:00:00", "2024-12-31T17:00:00", "2024-01-01T09:00:00", "2024-06-30T12:00:00") // true
+ * @example intervalEngulfsDateTime("2024-06-01T12:00:00", "2024-07-01T13:00:00", "2024-01-01T09:00:00", "2024-12-31T17:00:00") // false
+ * @example intervalEngulfsDateTime("invalid", "2024-12-31T17:00:00", "2024-06-01T12:00:00", "2024-07-01T13:00:00") // false
+ */
+export function intervalEngulfsDateTime(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return false;
+    }
+    if (!plainDateTime.test(aStart) ||
+        !plainDateTime.test(aEnd) ||
+        !plainDateTime.test(bStart) ||
+        !plainDateTime.test(bEnd)) {
+        return false;
+    }
+    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 false;
+        }
+        if (Temporal.PlainDateTime.compare(bS, bE) > 0) {
+            return false;
+        }
+        return (Temporal.PlainDateTime.compare(aS, bS) <= 0 &&
+            Temporal.PlainDateTime.compare(bE, aE) <= 0);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Return true when interval B is fully contained within interval A — every instant of B
+ * falls within A.
+ *
+ * - Uses `Temporal.PlainTime.compare` for comparison.
+ * - Equivalent to 4-argument `intervalContainsTime(aStart, aEnd, bStart, bEnd)`.
+ * - Returns `false` if either interval is invalid (`start > end`).
+ * - Returns `false` on invalid input (wrong type, malformed strings).
+ *
+ * @param aStart ISO 8601 time string for the outer interval start
+ * @param aEnd ISO 8601 time string for the outer interval end
+ * @param bStart ISO 8601 time string for the inner interval start
+ * @param bEnd ISO 8601 time string for the inner interval end
+ * @returns true if B is fully contained in A, or false on invalid input
+ *
+ * @example intervalEngulfsTime("09:00:00", "17:00:00", "12:00:00", "13:00:00") // true
+ * @example intervalEngulfsTime("09:00:00", "17:00:00", "09:00:00", "17:00:00") // true (equal intervals)
+ * @example intervalEngulfsTime("09:00:00", "17:00:00", "09:00:00", "12:00:00") // true
+ * @example intervalEngulfsTime("12:00:00", "13:00:00", "09:00:00", "17:00:00") // false
+ * @example intervalEngulfsTime("invalid", "17:00:00", "12:00:00", "13:00:00") // false
+ */
+export declare function intervalEngulfsTime(aStart: string, aEnd: string, bStart: string, bEnd: string): boolean;

package/dist/plain/interval/intervalEngulfsTime.js

@@ -0,0 +1,54 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { plainTime } from "../../regex/index.js";
+/**
+ * Return true when interval B is fully contained within interval A — every instant of B
+ * falls within A.
+ *
+ * - Uses `Temporal.PlainTime.compare` for comparison.
+ * - Equivalent to 4-argument `intervalContainsTime(aStart, aEnd, bStart, bEnd)`.
+ * - Returns `false` if either interval is invalid (`start > end`).
+ * - Returns `false` on invalid input (wrong type, malformed strings).
+ *
+ * @param aStart ISO 8601 time string for the outer interval start
+ * @param aEnd ISO 8601 time string for the outer interval end
+ * @param bStart ISO 8601 time string for the inner interval start
+ * @param bEnd ISO 8601 time string for the inner interval end
+ * @returns true if B is fully contained in A, or false on invalid input
+ *
+ * @example intervalEngulfsTime("09:00:00", "17:00:00", "12:00:00", "13:00:00") // true
+ * @example intervalEngulfsTime("09:00:00", "17:00:00", "09:00:00", "17:00:00") // true (equal intervals)
+ * @example intervalEngulfsTime("09:00:00", "17:00:00", "09:00:00", "12:00:00") // true
+ * @example intervalEngulfsTime("12:00:00", "13:00:00", "09:00:00", "17:00:00") // false
+ * @example intervalEngulfsTime("invalid", "17:00:00", "12:00:00", "13:00:00") // false
+ */
+export function intervalEngulfsTime(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return false;
+    }
+    if (!plainTime.test(aStart) ||
+        !plainTime.test(aEnd) ||
+        !plainTime.test(bStart) ||
+        !plainTime.test(bEnd)) {
+        return false;
+    }
+    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 false;
+        }
+        if (Temporal.PlainTime.compare(bS, bE) > 0) {
+            return false;
+        }
+        return (Temporal.PlainTime.compare(aS, bS) <= 0 &&
+            Temporal.PlainTime.compare(bE, aE) <= 0);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { Overflow } from "../../types/index.js";
+/**
+ * Construct a date interval from a single point plus an ISO 8601 duration, anchored at either end.
+ *
+ * - `anchor: "start"` treats `value` as the interval start and adds `duration` to get the end.
+ * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
+ * - Uses `Temporal.PlainDate.prototype.add`/`.subtract`, so calendar units (years/months/weeks)
+ *   resolve against `value` itself — no separate `relativeTo` is needed, unlike `addDuration`.
+ * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
+ *   happens, mirroring `intervalIntersectionDate`'s `start > end` rejection.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
+ * - Accepts a GMT calendar-annotated PlainDate string — E5 (issue #78). The computed endpoint
+ *   is resolved in `value`'s own calendar (no `relativeTo`/pair-matching question, since there
+ *   is only one calendar-tagged input) and both endpoints are re-formatted in that calendar,
+ *   re-derived from the actual result rather than copied from `value`'s tag (a leap-month or
+ *   era boundary can fall between them).
+ * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
+ *   than `"start"`/`"end"`).
+ *
+ * @param value ISO PlainDate string, optionally calendar-annotated
+ * @param duration ISO 8601 duration string
+ * @param anchor "start" | "end" — which endpoint `value` represents
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns `{ start, end }` with the constructed span, or null on invalid input
+ *
+ * @example intervalFromDurationDate("2024-01-01", "P1M", "start") // { start: "2024-01-01", end: "2024-02-01" }
+ * @example intervalFromDurationDate("2024-02-01", "P1M", "end") // { start: "2024-01-01", end: "2024-02-01" }
+ * @example intervalFromDurationDate("2024-01-31", "P1M", "start", { overflow: "reject" }) // null
+ * @example intervalFromDurationDate("2024-01-05", "-P10D", "start") // null (inverted span)
+ * @example intervalFromDurationDate("invalid", "P1M", "start") // null
+ * @example intervalFromDurationDate("5784-06-15[u-ca=hebrew]", "P1M", "start") // { start: "5784-06-15[u-ca=hebrew]", end: "5784-07-15[u-ca=hebrew]" } (Adar I -> Adar)
+ */
+export declare function intervalFromDurationDate(value: string, duration: string, anchor: "start" | "end", options?: {
+    overflow?: Overflow;
+}): {
+    start: string;
+    end: string;
+} | null;

package/dist/plain/interval/intervalFromDurationDate.js

@@ -0,0 +1,71 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDuration } from "../../duration/validate/index.js";
+import { calendarSystemOfDateValue, formatDateInCalendar, parseCalendarDateValue, resolveOverflow, } from "../../internal/index.js";
+import { isValidCalendarDate } from "../validate/index.js";
+/**
+ * Construct a date interval from a single point plus an ISO 8601 duration, anchored at either end.
+ *
+ * - `anchor: "start"` treats `value` as the interval start and adds `duration` to get the end.
+ * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
+ * - Uses `Temporal.PlainDate.prototype.add`/`.subtract`, so calendar units (years/months/weeks)
+ *   resolve against `value` itself — no separate `relativeTo` is needed, unlike `addDuration`.
+ * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
+ *   happens, mirroring `intervalIntersectionDate`'s `start > end` rejection.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
+ * - Accepts a GMT calendar-annotated PlainDate string — E5 (issue #78). The computed endpoint
+ *   is resolved in `value`'s own calendar (no `relativeTo`/pair-matching question, since there
+ *   is only one calendar-tagged input) and both endpoints are re-formatted in that calendar,
+ *   re-derived from the actual result rather than copied from `value`'s tag (a leap-month or
+ *   era boundary can fall between them).
+ * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
+ *   than `"start"`/`"end"`).
+ *
+ * @param value ISO PlainDate string, optionally calendar-annotated
+ * @param duration ISO 8601 duration string
+ * @param anchor "start" | "end" — which endpoint `value` represents
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns `{ start, end }` with the constructed span, or null on invalid input
+ *
+ * @example intervalFromDurationDate("2024-01-01", "P1M", "start") // { start: "2024-01-01", end: "2024-02-01" }
+ * @example intervalFromDurationDate("2024-02-01", "P1M", "end") // { start: "2024-01-01", end: "2024-02-01" }
+ * @example intervalFromDurationDate("2024-01-31", "P1M", "start", { overflow: "reject" }) // null
+ * @example intervalFromDurationDate("2024-01-05", "-P10D", "start") // null (inverted span)
+ * @example intervalFromDurationDate("invalid", "P1M", "start") // null
+ * @example intervalFromDurationDate("5784-06-15[u-ca=hebrew]", "P1M", "start") // { start: "5784-06-15[u-ca=hebrew]", end: "5784-07-15[u-ca=hebrew]" } (Adar I -> Adar)
+ */
+export function intervalFromDurationDate(value, duration, anchor, options) {
+    if (typeof value !== "string" || !isValidCalendarDate(value)) {
+        return null;
+    }
+    if (!isValidDuration(duration)) {
+        return null;
+    }
+    if (anchor !== "start" && anchor !== "end") {
+        return null;
+    }
+    try {
+        const calendar = calendarSystemOfDateValue(value);
+        if (!calendar) {
+            return null;
+        }
+        const point = parseCalendarDateValue(value);
+        const dur = Temporal.Duration.from(duration);
+        const overflow = resolveOverflow(options?.overflow);
+        const other = anchor === "start"
+            ? point.add(dur, { overflow })
+            : point.subtract(dur, { overflow });
+        const start = anchor === "start" ? point : other;
+        const end = anchor === "start" ? other : point;
+        if (Temporal.PlainDate.compare(start, end) > 0) {
+            return null;
+        }
+        return {
+            start: formatDateInCalendar(start, calendar),
+            end: formatDateInCalendar(end, calendar),
+        };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,33 @@
+import type { Overflow } from "../../types/index.js";
+/**
+ * Construct a datetime interval from a single point plus an ISO 8601 duration, anchored at either end.
+ *
+ * - `anchor: "start"` treats `value` as the interval start and adds `duration` to get the end.
+ * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
+ * - Uses `Temporal.PlainDateTime.prototype.add`/`.subtract`, so calendar units (years/months/weeks)
+ *   resolve against `value` itself — no separate `relativeTo` is needed, unlike `addDuration`.
+ * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
+ *   happens, mirroring `intervalIntersectionDateTime`'s `start > end` rejection.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
+ * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
+ *   than `"start"`/`"end"`).
+ *
+ * @param value ISO PlainDateTime string
+ * @param duration ISO 8601 duration string
+ * @param anchor "start" | "end" — which endpoint `value` represents
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns `{ start, end }` with the constructed span, or null on invalid input
+ *
+ * @example intervalFromDurationDateTime("2024-01-01T00:00:00", "P1DT2H", "start") // { start: "2024-01-01T00:00:00", end: "2024-01-02T02:00:00" }
+ * @example intervalFromDurationDateTime("2024-01-02T02:00:00", "P1DT2H", "end") // { start: "2024-01-01T00:00:00", end: "2024-01-02T02:00:00" }
+ * @example intervalFromDurationDateTime("2024-01-31T12:00:00", "P1M", "start", { overflow: "reject" }) // null
+ * @example intervalFromDurationDateTime("2024-01-05T00:00:00", "-P10D", "start") // null (inverted span)
+ * @example intervalFromDurationDateTime("invalid", "P1D", "start") // null
+ */
+export declare function intervalFromDurationDateTime(value: string, duration: string, anchor: "start" | "end", options?: {
+    overflow?: Overflow;
+}): {
+    start: string;
+    end: string;
+} | null;

package/dist/plain/interval/intervalFromDurationDateTime.js

@@ -0,0 +1,58 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDuration } from "../../duration/validate/index.js";
+import { resolveOverflow } from "../../internal/index.js";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Construct a datetime interval from a single point plus an ISO 8601 duration, anchored at either end.
+ *
+ * - `anchor: "start"` treats `value` as the interval start and adds `duration` to get the end.
+ * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
+ * - Uses `Temporal.PlainDateTime.prototype.add`/`.subtract`, so calendar units (years/months/weeks)
+ *   resolve against `value` itself — no separate `relativeTo` is needed, unlike `addDuration`.
+ * - A negative `duration` (e.g. `"-P1D"`) can invert the computed span; returns null when that
+ *   happens, mirroring `intervalIntersectionDateTime`'s `start > end` rejection.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" returns null.
+ * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
+ *   than `"start"`/`"end"`).
+ *
+ * @param value ISO PlainDateTime string
+ * @param duration ISO 8601 duration string
+ * @param anchor "start" | "end" — which endpoint `value` represents
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns `{ start, end }` with the constructed span, or null on invalid input
+ *
+ * @example intervalFromDurationDateTime("2024-01-01T00:00:00", "P1DT2H", "start") // { start: "2024-01-01T00:00:00", end: "2024-01-02T02:00:00" }
+ * @example intervalFromDurationDateTime("2024-01-02T02:00:00", "P1DT2H", "end") // { start: "2024-01-01T00:00:00", end: "2024-01-02T02:00:00" }
+ * @example intervalFromDurationDateTime("2024-01-31T12:00:00", "P1M", "start", { overflow: "reject" }) // null
+ * @example intervalFromDurationDateTime("2024-01-05T00:00:00", "-P10D", "start") // null (inverted span)
+ * @example intervalFromDurationDateTime("invalid", "P1D", "start") // null
+ */
+export function intervalFromDurationDateTime(value, duration, anchor, options) {
+    if (typeof value !== "string" || !isValidDateTime(value)) {
+        return null;
+    }
+    if (!isValidDuration(duration)) {
+        return null;
+    }
+    if (anchor !== "start" && anchor !== "end") {
+        return null;
+    }
+    try {
+        const point = Temporal.PlainDateTime.from(value);
+        const dur = Temporal.Duration.from(duration);
+        const overflow = resolveOverflow(options?.overflow);
+        const other = anchor === "start"
+            ? point.add(dur, { overflow })
+            : point.subtract(dur, { overflow });
+        const start = anchor === "start" ? point : other;
+        const end = anchor === "start" ? other : point;
+        if (Temporal.PlainDateTime.compare(start, end) > 0) {
+            return null;
+        }
+        return { start: start.toString(), end: end.toString() };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,38 @@
+import type { Overflow } from "../../types/index.js";
+/**
+ * Construct a time interval from a single point plus an ISO 8601 duration, anchored at either end.
+ *
+ * - `anchor: "start"` treats `value` as the interval start and adds `duration` to get the end.
+ * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
+ * - `PlainTime` has no calendar, so a `duration` with a nonzero years/months/weeks/days component
+ *   cannot be resolved against a bare clock time — there is no `relativeTo` to supply (mirrors
+ *   A2/A3's documented `relativeTo` gap). `Temporal.PlainTime.prototype.add` silently discards
+ *   those fields rather than throwing, so this is checked explicitly and returns null.
+ * - A `duration` that wraps past midnight (e.g. `"23:00:00"` + `"PT2H"`) produces a span PlainTime
+ *   can't represent (no date component for the day rollover) and returns null, same as any other
+ *   inverted span.
+ * - `overflow` ("constrain" (default) | "reject") is accepted for API consistency with sibling
+ *   `intervalFromDuration*` functions, but `PlainTime` arithmetic always wraps around the clock
+ *   rather than producing an out-of-range value, so it has no observable effect here (mirrors
+ *   `addTime`'s own documented no-op).
+ * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
+ *   than `"start"`/`"end"`).
+ *
+ * @param value ISO PlainTime string
+ * @param duration ISO 8601 duration string
+ * @param anchor "start" | "end" — which endpoint `value` represents
+ * @param options optional: overflow ("constrain" | "reject" — accepted but inert, see above)
+ * @returns `{ start, end }` with the constructed span, or null on invalid input
+ *
+ * @example intervalFromDurationTime("12:00:00", "PT1H", "start") // { start: "12:00:00", end: "13:00:00" }
+ * @example intervalFromDurationTime("13:00:00", "PT1H", "end") // { start: "12:00:00", end: "13:00:00" }
+ * @example intervalFromDurationTime("12:00:00", "P1D", "start") // null (date units need relativeTo, unsupported)
+ * @example intervalFromDurationTime("23:00:00", "PT2H", "start") // null (wraps past midnight, inverted span)
+ * @example intervalFromDurationTime("invalid", "PT1H", "start") // null
+ */
+export declare function intervalFromDurationTime(value: string, duration: string, anchor: "start" | "end", options?: {
+    overflow?: Overflow;
+}): {
+    start: string;
+    end: string;
+} | null;

package/dist/plain/interval/intervalFromDurationTime.js

@@ -0,0 +1,69 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDuration } from "../../duration/validate/index.js";
+import { resolveOverflow } from "../../internal/index.js";
+import { isValidTime } from "../validate/index.js";
+/**
+ * Construct a time interval from a single point plus an ISO 8601 duration, anchored at either end.
+ *
+ * - `anchor: "start"` treats `value` as the interval start and adds `duration` to get the end.
+ * - `anchor: "end"` treats `value` as the interval end and subtracts `duration` to get the start.
+ * - `PlainTime` has no calendar, so a `duration` with a nonzero years/months/weeks/days component
+ *   cannot be resolved against a bare clock time — there is no `relativeTo` to supply (mirrors
+ *   A2/A3's documented `relativeTo` gap). `Temporal.PlainTime.prototype.add` silently discards
+ *   those fields rather than throwing, so this is checked explicitly and returns null.
+ * - A `duration` that wraps past midnight (e.g. `"23:00:00"` + `"PT2H"`) produces a span PlainTime
+ *   can't represent (no date component for the day rollover) and returns null, same as any other
+ *   inverted span.
+ * - `overflow` ("constrain" (default) | "reject") is accepted for API consistency with sibling
+ *   `intervalFromDuration*` functions, but `PlainTime` arithmetic always wraps around the clock
+ *   rather than producing an out-of-range value, so it has no observable effect here (mirrors
+ *   `addTime`'s own documented no-op).
+ * - Returns null on invalid input (unparseable `value`, invalid `duration`, or an `anchor` other
+ *   than `"start"`/`"end"`).
+ *
+ * @param value ISO PlainTime string
+ * @param duration ISO 8601 duration string
+ * @param anchor "start" | "end" — which endpoint `value` represents
+ * @param options optional: overflow ("constrain" | "reject" — accepted but inert, see above)
+ * @returns `{ start, end }` with the constructed span, or null on invalid input
+ *
+ * @example intervalFromDurationTime("12:00:00", "PT1H", "start") // { start: "12:00:00", end: "13:00:00" }
+ * @example intervalFromDurationTime("13:00:00", "PT1H", "end") // { start: "12:00:00", end: "13:00:00" }
+ * @example intervalFromDurationTime("12:00:00", "P1D", "start") // null (date units need relativeTo, unsupported)
+ * @example intervalFromDurationTime("23:00:00", "PT2H", "start") // null (wraps past midnight, inverted span)
+ * @example intervalFromDurationTime("invalid", "PT1H", "start") // null
+ */
+export function intervalFromDurationTime(value, duration, anchor, options) {
+    if (typeof value !== "string" || !isValidTime(value)) {
+        return null;
+    }
+    if (!isValidDuration(duration)) {
+        return null;
+    }
+    if (anchor !== "start" && anchor !== "end") {
+        return null;
+    }
+    try {
+        const dur = Temporal.Duration.from(duration);
+        if (dur.years !== 0 ||
+            dur.months !== 0 ||
+            dur.weeks !== 0 ||
+            dur.days !== 0) {
+            return null;
+        }
+        const point = Temporal.PlainTime.from(value);
+        const overflow = resolveOverflow(options?.overflow);
+        const other = anchor === "start"
+            ? point.add(dur, { overflow })
+            : point.subtract(dur, { overflow });
+        const start = anchor === "start" ? point : other;
+        const end = anchor === "start" ? other : point;
+        if (Temporal.PlainTime.compare(start, end) > 0) {
+            return null;
+        }
+        return { start: start.toString(), end: end.toString() };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Return the overlapping span of two date intervals, or null when they do not overlap.
+ *
+ * - Uses `Temporal.PlainDate.compare` for comparison.
+ * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (wrong type, malformed strings).
+ * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Since the result is a
+ *   date *value*, all four arguments must carry the *same* calendar tag (or all be bare ISO);
+ *   a mismatch returns `null` (E5 decision of record D4). The output's tag is re-derived from
+ *   the intersection span, never copied from an input.
+ *
+ * @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 `{ start, end }` with the overlapping span, or null on invalid input / no overlap / mismatched calendars
+ *
+ * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // { start: "2024-04-01", end: "2024-06-30" }
+ * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // { start: "2024-06-30", end: "2024-06-30" }
+ * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // null
+ * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-02-01", "2024-03-01") // { start: "2024-02-01", end: "2024-03-01" }
+ * @example intervalIntersectionDate("invalid", "2024-06-30", "2024-04-01", "2024-12-31") // null
+ */
+export declare function intervalIntersectionDate(aStart: string, aEnd: string, bStart: string, bEnd: string): {
+    start: string;
+    end: string;
+} | null;

package/dist/plain/interval/intervalIntersectionDate.js

@@ -0,0 +1,70 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarOfAllDateValues, formatDateInCalendar, parseCalendarDateValue, } from "../../internal/index.js";
+import { isValidCalendarDate } from "../validate/index.js";
+/**
+ * Return the overlapping span of two date intervals, or null when they do not overlap.
+ *
+ * - Uses `Temporal.PlainDate.compare` for comparison.
+ * - Adjacent intervals (e.g. `aEnd === bStart`) share one instant and DO overlap.
+ * - Returns `null` if either interval is invalid (`start > end`).
+ * - Returns `null` on invalid input (wrong type, malformed strings).
+ * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Since the result is a
+ *   date *value*, all four arguments must carry the *same* calendar tag (or all be bare ISO);
+ *   a mismatch returns `null` (E5 decision of record D4). The output's tag is re-derived from
+ *   the intersection span, never copied from an input.
+ *
+ * @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 `{ start, end }` with the overlapping span, or null on invalid input / no overlap / mismatched calendars
+ *
+ * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // { start: "2024-04-01", end: "2024-06-30" }
+ * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // { start: "2024-06-30", end: "2024-06-30" }
+ * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // null
+ * @example intervalIntersectionDate("2024-01-01", "2024-06-30", "2024-02-01", "2024-03-01") // { start: "2024-02-01", end: "2024-03-01" }
+ * @example intervalIntersectionDate("invalid", "2024-06-30", "2024-04-01", "2024-12-31") // null
+ */
+export function intervalIntersectionDate(aStart, aEnd, bStart, bEnd) {
+    if (typeof aStart !== "string" ||
+        typeof aEnd !== "string" ||
+        typeof bStart !== "string" ||
+        typeof bEnd !== "string") {
+        return null;
+    }
+    if (!isValidCalendarDate(aStart) ||
+        !isValidCalendarDate(aEnd) ||
+        !isValidCalendarDate(bStart) ||
+        !isValidCalendarDate(bEnd)) {
+        return null;
+    }
+    const calendar = calendarOfAllDateValues([aStart, aEnd, bStart, bEnd]);
+    if (!calendar) {
+        return null;
+    }
+    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 null;
+        }
+        if (Temporal.PlainDate.compare(bS, bE) > 0) {
+            return null;
+        }
+        if (Temporal.PlainDate.compare(aE, bS) < 0 ||
+            Temporal.PlainDate.compare(bE, aS) < 0) {
+            return null;
+        }
+        const start = Temporal.PlainDate.compare(aS, bS) >= 0 ? aS : bS;
+        const end = Temporal.PlainDate.compare(aE, bE) <= 0 ? aE : bE;
+        return {
+            start: formatDateInCalendar(start, calendar),
+            end: formatDateInCalendar(end, calendar),
+        };
+    }
+    catch {
+        return null;
+    }
+}