@northguild/gmt 1.15.0 → 1.17.0

package/dist/interval/compare/intervalsOverlap.js

@@ -0,0 +1,42 @@
+import { parseIntervalNanoseconds } from "../../internal/index.js";
+/**
+ * Return true when two half-open intervals share at least one instant.
+ *
+ * - `a.start < b.end && b.start < a.end`. Touching intervals (`a.end` is `b.start`) do not
+ *   overlap: under `[start, end)` the shared endpoint belongs only to the later interval.
+ * - True exactly when `intersectIntervals(a, b)` is not `null`.
+ * - An empty interval (`start === end`) overlaps an interval it lies strictly inside, and nothing
+ *   else — not at an edge, not another empty interval at the same instant (GMT rule: an empty
+ *   interval covers no time, so only a strictly interior position is shared).
+ * - Compares instants: endpoints may name different zones.
+ * - The positional `intervalsOverlapUtc`, `intervalsOverlapZoned`, `intervalsOverlapDate` (…)
+ *   follow the same half-open rule, so touching intervals do not overlap there either.
+ * - For zone-aligned windows (a local day, a trading session), build the endpoints with
+ *   `floorToZone` first.
+ * - Returns `false` on invalid input — either interval not an `Interval`, or inverted.
+ *
+ * @param a `{ start, end }` record of ISO 8601 instant strings
+ * @param b `{ start, end }` record of ISO 8601 instant strings
+ * @returns true if the intervals share an instant, or false on invalid input
+ *
+ * @example intervalsOverlap({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }) // true
+ * @example intervalsOverlap({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }, { start: "2024-01-01T17:00:00Z", end: "2024-01-01T18:00:00Z" }) // false — touching
+ * @example intervalsOverlap({ start: "2024-01-01T12:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // true — empty, strictly inside
+ * @example intervalsOverlap({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T09:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // false — empty, at the edge
+ * @example intervalsOverlap({ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }, { start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // false — inverted
+ */
+export function intervalsOverlap(a, b) {
+    try {
+        const first = parseIntervalNanoseconds(a);
+        const second = parseIntervalNanoseconds(b);
+        if (first === null || second === null) {
+            return false;
+        }
+        return first.start < second.end && second.start < first.end;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return false;
+    }
+}

package/dist/interval/index.d.ts

@@ -0,0 +1,4 @@
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";
+export * from "./compare/index.js";
+export * from "./validate/index.js";

package/dist/interval/index.js

@@ -0,0 +1,5 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";
+export * from "./compare/index.js";
+export * from "./validate/index.js";

package/dist/interval/validate/index.d.ts

@@ -0,0 +1 @@
+export * from "./isValidInterval.js";

package/dist/interval/validate/index.js

@@ -0,0 +1 @@
+export * from "./isValidInterval.js";

package/dist/interval/validate/isValidInterval.d.ts

@@ -0,0 +1,29 @@
+import type { Interval } from "../../types/index.js";
+/**
+ * Validate whether a value is an `Interval` the `interval/` namespace accepts.
+ *
+ * - True when `start` and `end` are ISO 8601 instant strings (offset required, no leap second)
+ *   and `start` is not after `end`.
+ * - Annotations are read as `Temporal.Instant.from` reads them: a bracketed zone, a calendar
+ *   annotation (`[u-ca=hebrew]`, critical or not) and an elective unknown annotation
+ *   (`[foo=bar]`) are ignored; an unknown critical annotation (`[!foo=bar]`) is rejected.
+ * - Compares instants, not text: `{ start: "2024-01-01T10:00:00+01:00", end: "2024-01-01T09:30:00Z" }`
+ *   is valid even though it sorts backwards as a string.
+ * - `start === end` is valid — an empty interval.
+ * - Use it to tell a legitimate `[]` from `mergeIntervals`, `subtractIntervals` or
+ *   `splitIntervalAt` apart from their invalid-input sentinel, which is also `[]`.
+ * - Returns `false` for non-objects, `null`, and records whose `start`/`end` are not strings.
+ *
+ * @param interval candidate `{ start, end }` record of ISO 8601 instant strings
+ * @returns boolean indicating whether every `interval/` function accepts it
+ *
+ * @example isValidInterval({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // true
+ * @example isValidInterval({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T09:00:00Z" }) // true — empty
+ * @example isValidInterval({ start: "2024-01-01T10:00:00+01:00", end: "2024-01-01T09:30:00Z" }) // true — 09:00Z to 09:30Z
+ * @example isValidInterval({ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }) // false — inverted
+ * @example isValidInterval({ start: "2024-01-01T09:00:00", end: "2024-01-01T17:00:00Z" }) // false — no offset
+ * @example isValidInterval({ start: "2016-12-31T23:59:60Z", end: "2017-01-01T00:00:00Z" }) // false — leap second
+ * @example isValidInterval({ start: "2024-01-01T09:00:00Z[u-ca=iso8601]", end: "2024-01-01T17:00:00Z" }) // true — calendar annotation ignored
+ * @example isValidInterval({ start: "2024-01-01T09:00:00Z[!foo=bar]", end: "2024-01-01T17:00:00Z" }) // false — unknown critical annotation
+ */
+export declare function isValidInterval(interval: Interval): boolean;

package/dist/interval/validate/isValidInterval.js

@@ -0,0 +1,38 @@
+import { parseIntervalNanoseconds } from "../../internal/index.js";
+/**
+ * Validate whether a value is an `Interval` the `interval/` namespace accepts.
+ *
+ * - True when `start` and `end` are ISO 8601 instant strings (offset required, no leap second)
+ *   and `start` is not after `end`.
+ * - Annotations are read as `Temporal.Instant.from` reads them: a bracketed zone, a calendar
+ *   annotation (`[u-ca=hebrew]`, critical or not) and an elective unknown annotation
+ *   (`[foo=bar]`) are ignored; an unknown critical annotation (`[!foo=bar]`) is rejected.
+ * - Compares instants, not text: `{ start: "2024-01-01T10:00:00+01:00", end: "2024-01-01T09:30:00Z" }`
+ *   is valid even though it sorts backwards as a string.
+ * - `start === end` is valid — an empty interval.
+ * - Use it to tell a legitimate `[]` from `mergeIntervals`, `subtractIntervals` or
+ *   `splitIntervalAt` apart from their invalid-input sentinel, which is also `[]`.
+ * - Returns `false` for non-objects, `null`, and records whose `start`/`end` are not strings.
+ *
+ * @param interval candidate `{ start, end }` record of ISO 8601 instant strings
+ * @returns boolean indicating whether every `interval/` function accepts it
+ *
+ * @example isValidInterval({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T17:00:00Z" }) // true
+ * @example isValidInterval({ start: "2024-01-01T09:00:00Z", end: "2024-01-01T09:00:00Z" }) // true — empty
+ * @example isValidInterval({ start: "2024-01-01T10:00:00+01:00", end: "2024-01-01T09:30:00Z" }) // true — 09:00Z to 09:30Z
+ * @example isValidInterval({ start: "2024-01-01T17:00:00Z", end: "2024-01-01T09:00:00Z" }) // false — inverted
+ * @example isValidInterval({ start: "2024-01-01T09:00:00", end: "2024-01-01T17:00:00Z" }) // false — no offset
+ * @example isValidInterval({ start: "2016-12-31T23:59:60Z", end: "2017-01-01T00:00:00Z" }) // false — leap second
+ * @example isValidInterval({ start: "2024-01-01T09:00:00Z[u-ca=iso8601]", end: "2024-01-01T17:00:00Z" }) // true — calendar annotation ignored
+ * @example isValidInterval({ start: "2024-01-01T09:00:00Z[!foo=bar]", end: "2024-01-01T17:00:00Z" }) // false — unknown critical annotation
+ */
+export function isValidInterval(interval) {
+    try {
+        return parseIntervalNanoseconds(interval) !== null;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return false;
+    }
+}

package/dist/plain/calculate/addBusinessDays.d.ts

@@ -1,17 +1,34 @@
+import type { BusinessCalendar } from "../../types/index.js";
 /**
- * Return a PlainDate ISO string with `amount` business days added to `value`.
+ * Return a PlainDate ISO string with `amount` working days added to `value`.
  *
- * - Uses fixed ISO Monday–Friday business days (no locale awareness).
- * - Saturday and Sunday are skipped during the count.
- * - Returns "" on invalid input.
+ * - `calendar` names the weekend days and holidays to skip. Omit it and GMT keeps its original
+ *   fixed Monday–Friday week with no holidays. Pass one anywhere the weekend is not
+ *   Saturday–Sunday — much of the Middle East is Friday–Saturday.
+ * - Negative `amount` walks backwards, so `addBusinessDays(value, -3, cal)` and
+ *   `subtractBusinessDays(value, 3, cal)` agree.
+ * - `amount` of 0 returns `value` unchanged — including when `value` is not itself a working
+ *   day. Use `rollDate` to move a non-working day onto one.
+ * - `value` is never counted, so adding 1 from a holiday lands on the next working day after
+ *   it.
+ * - `value` and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A caller
+ *   holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns "" on invalid input — including a fractional `amount`, which names no whole
+ *   number of working days — on an invalid `calendar`, and when the walk runs past
+ *   200,000 calendar days (about 547 years) without finishing.
  *
  * @param value ISO PlainDate string
- * @param amount number of business days to add
- * @returns ISO PlainDate string after adding business days, or "" on invalid input
+ * @param amount whole number of working days to add; negative walks backwards
+ * @param calendar optional BusinessCalendar; defaults to Monday–Friday with no holidays
+ * @returns ISO PlainDate string after adding working days, or "" on invalid input
  *
- * @example addBusinessDays("2024-03-15", 1) // "2024-03-18"
- * @example addBusinessDays("2024-03-16", 1) // "2024-03-18"
+ * @example addBusinessDays("2024-03-15", 1) // "2024-03-18" (Friday to Monday)
+ * @example addBusinessDays("2024-03-16", 1) // "2024-03-18" (from a Saturday)
  * @example addBusinessDays("2024-03-15", 0) // "2024-03-15"
+ * @example addBusinessDays("2024-07-03", 1, { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-05" (skips the holiday)
+ * @example addBusinessDays("2024-07-03", -1, { weekend: [6, 7], holidays: ["2024-07-02"], timeZone: "America/New_York" }) // "2024-07-01"
+ * @example addBusinessDays("2024-07-04", 1, { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-07" (Friday–Saturday weekend)
  * @example addBusinessDays("invalid", 1) // ""
+ * @example addBusinessDays("2024-03-15", 1, { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // "" (bad calendar)
  */
-export declare function addBusinessDays(value: string, amount: number): string;
+export declare function addBusinessDays(value: string, amount: number, calendar?: BusinessCalendar): string;

package/dist/plain/calculate/addBusinessDays.js

@@ -1,35 +1,43 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { advanceBusinessDays, isValidAmount } from "../../internal/index.js";
-import { isValidDate } from "../validate/index.js";
+import { stepBusinessDaysValue } from "../../internal/businessDayValues.js";
 /**
- * Return a PlainDate ISO string with `amount` business days added to `value`.
+ * Return a PlainDate ISO string with `amount` working days added to `value`.
  *
- * - Uses fixed ISO Monday–Friday business days (no locale awareness).
- * - Saturday and Sunday are skipped during the count.
- * - Returns "" on invalid input.
+ * - `calendar` names the weekend days and holidays to skip. Omit it and GMT keeps its original
+ *   fixed Monday–Friday week with no holidays. Pass one anywhere the weekend is not
+ *   Saturday–Sunday — much of the Middle East is Friday–Saturday.
+ * - Negative `amount` walks backwards, so `addBusinessDays(value, -3, cal)` and
+ *   `subtractBusinessDays(value, 3, cal)` agree.
+ * - `amount` of 0 returns `value` unchanged — including when `value` is not itself a working
+ *   day. Use `rollDate` to move a non-working day onto one.
+ * - `value` is never counted, so adding 1 from a holiday lands on the next working day after
+ *   it.
+ * - `value` and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A caller
+ *   holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns "" on invalid input — including a fractional `amount`, which names no whole
+ *   number of working days — on an invalid `calendar`, and when the walk runs past
+ *   200,000 calendar days (about 547 years) without finishing.
  *
  * @param value ISO PlainDate string
- * @param amount number of business days to add
- * @returns ISO PlainDate string after adding business days, or "" on invalid input
+ * @param amount whole number of working days to add; negative walks backwards
+ * @param calendar optional BusinessCalendar; defaults to Monday–Friday with no holidays
+ * @returns ISO PlainDate string after adding working days, or "" on invalid input
  *
- * @example addBusinessDays("2024-03-15", 1) // "2024-03-18"
- * @example addBusinessDays("2024-03-16", 1) // "2024-03-18"
+ * @example addBusinessDays("2024-03-15", 1) // "2024-03-18" (Friday to Monday)
+ * @example addBusinessDays("2024-03-16", 1) // "2024-03-18" (from a Saturday)
  * @example addBusinessDays("2024-03-15", 0) // "2024-03-15"
+ * @example addBusinessDays("2024-07-03", 1, { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-05" (skips the holiday)
+ * @example addBusinessDays("2024-07-03", -1, { weekend: [6, 7], holidays: ["2024-07-02"], timeZone: "America/New_York" }) // "2024-07-01"
+ * @example addBusinessDays("2024-07-04", 1, { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-07" (Friday–Saturday weekend)
  * @example addBusinessDays("invalid", 1) // ""
+ * @example addBusinessDays("2024-03-15", 1, { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // "" (bad calendar)
  */
-export function addBusinessDays(value, amount) {
-    if (!isValidDate(value) || !isValidAmount(amount)) {
-        return "";
-    }
-    if (amount === 0) {
-        return value;
-    }
+export function addBusinessDays(value, amount, calendar) {
     try {
-        const date = Temporal.PlainDate.from(value);
-        const direction = amount > 0 ? 1 : -1;
-        return advanceBusinessDays(date, direction, Math.abs(amount)).toString();
+        return stepBusinessDaysValue(value, amount, 1, calendar);
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/calculate/addDate.d.ts

@@ -3,13 +3,13 @@ import type { DateDurationUnit, Overflow } from "../../types/index.js";
  * Return a PlainDate ISO string with `amount` added according to `units`.
  *
  * - Validates `value`, `units`, and `amount` before performing the add.
- * - Accepts a GMT calendar-annotated PlainDate string (as produced by `convertDateToCalendar`,
- *   e.g. `"5784-06-15[u-ca=hebrew]"`), not just a bare ISO string — E5 (issue #78). Calendar-unit
- *   arithmetic ("add 1 month") resolves against that calendar (a Hebrew leap month, a Persian
- *   leap year), and the result is re-formatted in the same calendar — re-derived from the
- *   arithmetic result, never copied from the input tag, since arithmetic can cross a leap-month
- *   or era boundary (e.g. Adar I -> Adar). A bare ISO string is unaffected — always treated as,
- *   and always returns, `"gregorian"`.
+ * - Accepts an RFC 9557 calendar-annotated PlainDate string (as `Temporal.PlainDate#toString()` and
+ *   `convertDateToCalendar` write it, e.g. `"2024-02-24[u-ca=hebrew]"`), not just a bare ISO
+ *   string. Calendar-unit arithmetic ("add 1 month") resolves against that calendar (a Hebrew leap
+ *   month, a Persian leap year), and the result carries the same calendar annotation. A bare ISO
+ *   string is the `"iso8601"` calendar and returns a bare ISO string.
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
  * - Returns "" for invalid inputs.
  *
  * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
@@ -28,7 +28,8 @@ import type { DateDurationUnit, Overflow } from "../../types/index.js";
  * @example addDate("invalid", { days: 5 }) // ""
  * @example addDate("2024-01-31", { months: 1 }, { overflow: "constrain" }) // "2024-02-29"
  * @example addDate("2024-01-31", { months: 1 }, { overflow: "reject" }) // ""
- * @example addDate("5784-06-15[u-ca=hebrew]", { months: 1 }) // "5784-07-15[u-ca=hebrew]" (Adar I -> Adar, both 30 days)
+ * @example addDate("2024-02-24[u-ca=hebrew]", { months: 1 }) // "2024-03-25[u-ca=hebrew]" (15 Adar I 5784 -> 15 Adar II)
+ * @example addDate("2024-10-03[u-ca=japanese;era=reiwa]", { days: 1 }) // "" (not RFC 9557)
  */
 export declare function addDate(value: string, units: Partial<Record<DateDurationUnit, number>>, options?: {
     overflow?: Overflow;

package/dist/plain/calculate/addDate.js

@@ -1,16 +1,18 @@
-import { calendarSystemOfDateValue, formatDateInCalendar, isValidAmount, parseCalendarDateValue, resolveOverflow, } from "../../internal/index.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { calendarSystemOfDateValue, formatDateInCalendar, isValidAmount, parseCalendarDateValue, plainDateAdd, resolveOverflow, } from "../../internal/index.js";
 import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainDate ISO string with `amount` added according to `units`.
  *
  * - Validates `value`, `units`, and `amount` before performing the add.
- * - Accepts a GMT calendar-annotated PlainDate string (as produced by `convertDateToCalendar`,
- *   e.g. `"5784-06-15[u-ca=hebrew]"`), not just a bare ISO string — E5 (issue #78). Calendar-unit
- *   arithmetic ("add 1 month") resolves against that calendar (a Hebrew leap month, a Persian
- *   leap year), and the result is re-formatted in the same calendar — re-derived from the
- *   arithmetic result, never copied from the input tag, since arithmetic can cross a leap-month
- *   or era boundary (e.g. Adar I -> Adar). A bare ISO string is unaffected — always treated as,
- *   and always returns, `"gregorian"`.
+ * - Accepts an RFC 9557 calendar-annotated PlainDate string (as `Temporal.PlainDate#toString()` and
+ *   `convertDateToCalendar` write it, e.g. `"2024-02-24[u-ca=hebrew]"`), not just a bare ISO
+ *   string. Calendar-unit arithmetic ("add 1 month") resolves against that calendar (a Hebrew leap
+ *   month, a Persian leap year), and the result carries the same calendar annotation. A bare ISO
+ *   string is the `"iso8601"` calendar and returns a bare ISO string.
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
  * - Returns "" for invalid inputs.
  *
  * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
@@ -29,27 +31,38 @@ import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.
  * @example addDate("invalid", { days: 5 }) // ""
  * @example addDate("2024-01-31", { months: 1 }, { overflow: "constrain" }) // "2024-02-29"
  * @example addDate("2024-01-31", { months: 1 }, { overflow: "reject" }) // ""
- * @example addDate("5784-06-15[u-ca=hebrew]", { months: 1 }) // "5784-07-15[u-ca=hebrew]" (Adar I -> Adar, both 30 days)
+ * @example addDate("2024-02-24[u-ca=hebrew]", { months: 1 }) // "2024-03-25[u-ca=hebrew]" (15 Adar I 5784 -> 15 Adar II)
+ * @example addDate("2024-10-03[u-ca=japanese;era=reiwa]", { days: 1 }) // "" (not RFC 9557)
  */
 export function addDate(value /* ISO 8601 date */, units, options) {
-    const validDate = isValidCalendarDate(value);
-    const validUnits = Object.keys(units).every(isValidDateDurationUnit);
-    const validAmounts = Object.values(units).every(isValidAmount);
-    if (!validDate || !validUnits || !validAmounts) {
-        return "";
-    }
     try {
-        const calendar = calendarSystemOfDateValue(value);
-        if (!calendar) {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const validDate = isValidCalendarDate(value);
+        const validUnits = typeof units === "object" &&
+            units !== null &&
+            Object.keys(units).every(isValidDateDurationUnit);
+        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
+        if (!validDate || !validUnits || !validAmounts) {
+            return "";
+        }
+        try {
+            const calendar = calendarSystemOfDateValue(value);
+            if (!calendar) {
+                return "";
+            }
+            const date = parseCalendarDateValue(value);
+            const result = plainDateAdd(date, units, resolveOverflow(options?.overflow));
+            return formatDateInCalendar(result, calendar);
+        }
+        catch {
             return "";
         }
-        const date = parseCalendarDateValue(value);
-        const result = date.add(units, {
-            overflow: resolveOverflow(options?.overflow),
-        });
-        return formatDateInCalendar(result, calendar);
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/calculate/addDateTime.js

@@ -1,6 +1,8 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidAmount, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainDateTime ISO string with `units` added to `value`.
  *
@@ -20,19 +22,31 @@ import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.
  * @example addDateTime("2024-01-31T12:00:00", { months: 1 }, { overflow: "reject" }) // ""
  */
 export function addDateTime(value, units, options) {
-    const validDateTime = isValidDateTime(value);
-    const validUnits = Object.keys(units).every(isValidDateTimeDurationUnit);
-    const validAmounts = Object.values(units).every(isValidAmount);
-    if (!validDateTime || !validUnits || !validAmounts) {
-        return "";
-    }
     try {
-        const dateTime = Temporal.PlainDateTime.from(value);
-        return dateTime
-            .add(units, { overflow: resolveOverflow(options?.overflow) })
-            .toString();
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const validDateTime = isValidDateTime(value);
+        const validUnits = typeof units === "object" &&
+            units !== null &&
+            Object.keys(units).every(isValidDateTimeDurationUnit);
+        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
+        if (!validDateTime || !validUnits || !validAmounts) {
+            return "";
+        }
+        try {
+            const dateTime = Temporal.PlainDateTime.from(value);
+            return dateTime
+                .add(units, { overflow: resolveOverflow(options?.overflow) })
+                .toString();
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/calculate/addTime.d.ts

@@ -1,22 +1,19 @@
-import type { Overflow, TimeDurationUnit } from "../../types/index.js";
+import type { TimeDurationUnit } from "../../types/index.js";
 /**
  * Return a PlainTime ISO string with `units` added to `value`.
  *
  * - Validates `value`, `units`, and `amount` before performing the add.
  * - Returns "" for invalid inputs.
  *
- * `overflow` ("constrain" (default) | "reject") is accepted for API consistency with sibling
- * add functions, but PlainTime arithmetic always wraps around the clock (e.g. 23:00 + 2 hours
- * = 01:00) rather than producing an out-of-range value, so it has no observable effect here.
+ * There is no options argument (its only member, `overflow`, was removed in 1.16.0): Temporal
+ * `PlainTime#add` takes no options and always wraps around the clock (e.g. 23:00 + 2 hours
+ * = 01:00).
  *
  * @param value ISO PlainTime string
  * @param units Partial<Record<TimeDurationUnit, number>> object specifying units to add
- * @param options optional: overflow ("constrain" | "reject" — accepted but inert, see above)
  * @returns ISO PlainTime string after addition, or "" on invalid input
  *
  * @example addTime("12:00:00", { hours: 1 }) // "13:00:00"
  * @example addTime("invalid", { hours: 1 }) // ""
  */
-export declare function addTime(value: string, units: Partial<Record<TimeDurationUnit, number>>, options?: {
-    overflow?: Overflow;
-}): string;
+export declare function addTime(value: string, units: Partial<Record<TimeDurationUnit, number>>): string;

package/dist/plain/calculate/addTime.js

@@ -1,5 +1,6 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { isValidAmount } from "../../internal/index.js";
 import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
 /**
  * Return a PlainTime ISO string with `units` added to `value`.
@@ -7,32 +8,38 @@ import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
  * - Validates `value`, `units`, and `amount` before performing the add.
  * - Returns "" for invalid inputs.
  *
- * `overflow` ("constrain" (default) | "reject") is accepted for API consistency with sibling
- * add functions, but PlainTime arithmetic always wraps around the clock (e.g. 23:00 + 2 hours
- * = 01:00) rather than producing an out-of-range value, so it has no observable effect here.
+ * There is no options argument (its only member, `overflow`, was removed in 1.16.0): Temporal
+ * `PlainTime#add` takes no options and always wraps around the clock (e.g. 23:00 + 2 hours
+ * = 01:00).
  *
  * @param value ISO PlainTime string
  * @param units Partial<Record<TimeDurationUnit, number>> object specifying units to add
- * @param options optional: overflow ("constrain" | "reject" — accepted but inert, see above)
  * @returns ISO PlainTime string after addition, or "" on invalid input
  *
  * @example addTime("12:00:00", { hours: 1 }) // "13:00:00"
  * @example addTime("invalid", { hours: 1 }) // ""
  */
-export function addTime(value, units, options) {
-    const validTime = isValidTime(value);
-    const validUnits = Object.keys(units).every(isValidTimeDurationUnit);
-    const validAmounts = Object.values(units).every(isValidAmount);
-    if (!validTime || !validUnits || !validAmounts) {
-        return "";
-    }
+export function addTime(value, units) {
     try {
-        const time = Temporal.PlainTime.from(value);
-        return time
-            .add(units, { overflow: resolveOverflow(options?.overflow) })
-            .toString();
+        const validTime = isValidTime(value);
+        const validUnits = typeof units === "object" &&
+            units !== null &&
+            Object.keys(units).every(isValidTimeDurationUnit);
+        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
+        if (!validTime || !validUnits || !validAmounts) {
+            return "";
+        }
+        try {
+            const time = Temporal.PlainTime.from(value);
+            return time.add(units).toString();
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/calculate/clampDate.js

@@ -33,12 +33,12 @@ export function clampDate(value, min, max) {
         const cmpMin = Temporal.PlainDate.compare(v, mn);
         const cmpMax = Temporal.PlainDate.compare(v, mx);
         if (cmpMin < 0) {
-            return min;
+            return mn.toString();
         }
         if (cmpMax > 0) {
-            return max;
+            return mx.toString();
         }
-        return value;
+        return v.toString();
     }
     catch {
         return "";

package/dist/plain/calculate/closestDateTo.d.ts

@@ -1,18 +1,22 @@
 /**
  * Return the candidate date nearest to `target` by calendar distance.
  *
- * - Distance is measured in whole days using `Temporal.PlainDate.compare`.
- * - Returns `null` if the candidates array is empty or contains no valid dates.
- * - Returns `null` if `target` is invalid.
+ * - Distance is the absolute whole-day count `Math.abs(target.until(candidate).days)`.
+ *   `Temporal.PlainDate.compare` is not used for it: `compare` orders two dates (`-1`, `0`,
+ *   `1`), it does not measure between them. `until()` on a `PlainDate` defaults to
+ *   `largestUnit: "day"`, so the count runs across month and year boundaries —
+ *   `2024-03-15` to `2026-01-01` is `657`.
+ * - Returns `""` if the candidates array is empty or contains no valid dates, or `target` is invalid.
+ * - **Compatibility:** before 1.16.0 invalid input returned `null`.
  * - On a tie (two equidistant candidates), returns the first one in array order.
  *
  * @param target ISO PlainDate string to measure distance from
  * @param candidates Array of ISO PlainDate strings to choose from
- * @returns The nearest candidate date string, or null on invalid input
+ * @returns The nearest candidate date string, or "" on invalid input
  *
  * @example closestDateTo("2024-03-15", ["2024-03-01", "2024-03-20", "2024-03-18"]) // "2024-03-18"
  * @example closestDateTo("2024-03-15", ["2024-03-01", "2024-03-29"]) // "2024-03-01"
- * @example closestDateTo("2024-03-15", []) // null
- * @example closestDateTo("invalid", ["2024-03-01"]) // null
+ * @example closestDateTo("2024-03-15", []) // ""
+ * @example closestDateTo("invalid", ["2024-03-01"]) // ""
  */
-export declare function closestDateTo(target: string, candidates: string[]): string | null;
+export declare function closestDateTo(target: string, candidates: string[]): string;