@northguild/gmt 1.14.2 → 1.16.0

package/dist/plain/calculate/closestDateTo.js

@@ -3,41 +3,53 @@ import { isValidDate } from "../validate/index.js";
 /**
  * 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 function closestDateTo(target, candidates) {
-    if (!isValidDate(target) ||
-        !candidates.length ||
-        !candidates.some(isValidDate)) {
-        return null;
-    }
     try {
-        const t = Temporal.PlainDate.from(target);
-        const validCandidates = candidates.filter(isValidDate);
-        const parsed = validCandidates.map((c) => ({
-            str: c,
-            date: Temporal.PlainDate.from(c),
-        }));
-        const closest = parsed.reduce((best, candidate) => {
-            const bestDist = Math.abs(t.until(best.date).days);
-            const candDist = Math.abs(t.until(candidate.date).days);
-            return candDist < bestDist ? candidate : best;
-        }, parsed[0]);
-        return closest.str;
+        if (!isValidDate(target) ||
+            !Array.isArray(candidates) ||
+            !candidates.length ||
+            !candidates.some(isValidDate)) {
+            return "";
+        }
+        try {
+            const t = Temporal.PlainDate.from(target);
+            const validCandidates = candidates.filter(isValidDate);
+            const parsed = validCandidates.map((c) => ({
+                str: c,
+                date: Temporal.PlainDate.from(c),
+            }));
+            const closest = parsed.reduce((best, candidate) => {
+                const bestDist = Math.abs(t.until(best.date).days);
+                const candDist = Math.abs(t.until(candidate.date).days);
+                return candDist < bestDist ? candidate : best;
+            }, parsed[0]);
+            return closest.str;
+        }
+        catch {
+            return "";
+        }
     }
     catch {
-        return null;
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
     }
 }

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

@@ -20,7 +20,7 @@ import type { DateCycleField, Overflow } from "../../types/index.js";
  *   `@internationalized/date`'s `CycleOptions.round`. E.g. cycling `year` `2022` by `+5` with
  *   `round: true` lands on `2025` (the next multiple of 5 above 2022), not `2020` (the nearest
  *   multiple).
- * - Returns "" for an invalid `value` or an invalid `field`.
+ * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainDate string
  * @param field the field to cycle: "year" | "month" | "day"

package/dist/plain/calculate/cycleDate.js

@@ -1,7 +1,8 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { cycleFieldValue, dateCycleFieldBounds } from "../../internal/index.js";
+import { cycleFieldValue, dateCycleFieldBounds, isValidAmount, } from "../../internal/index.js";
 import { isValidDate, isValidDateCycleField } from "../validate/index.js";
 import { setDate } from "./setDate.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainDate ISO string with `field` cycled by `amount`, wrapping at that field's own
  * min/max instead of carrying into the next larger field.
@@ -23,7 +24,7 @@ import { setDate } from "./setDate.js";
  *   `@internationalized/date`'s `CycleOptions.round`. E.g. cycling `year` `2022` by `+5` with
  *   `round: true` lands on `2025` (the next multiple of 5 above 2022), not `2020` (the nearest
  *   multiple).
- * - Returns "" for an invalid `value` or an invalid `field`.
+ * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainDate string
  * @param field the field to cycle: "year" | "month" | "day"
@@ -42,8 +43,14 @@ import { setDate } from "./setDate.js";
  * @example cycleDate("invalid", "month", 1) // ""
  */
 export function cycleDate(value, field, amount, options) {
-    if (!isValidDate(value) || !isValidDateCycleField(field))
+    if (!isOptionsArgument(options)) {
         return "";
+    }
+    if (!isValidDate(value) ||
+        !isValidDateCycleField(field) ||
+        !isValidAmount(amount)) {
+        return "";
+    }
     try {
         const date = Temporal.PlainDate.from(value);
         const bounds = dateCycleFieldBounds(field, date);

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

@@ -17,7 +17,7 @@ import type { DateTimeCycleField, Overflow } from "../../types/index.js";
  * - `options.round` steps to the *next* multiple of `amount` in the direction of its sign
  *   (ceiling for positive, floor for negative) — not the nearest one. See `cycleDate`/`cycleTime`'s
  *   docs for worked examples.
- * - Returns "" for an invalid `value` or an invalid `field`.
+ * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainDateTime string
  * @param field the field to cycle: "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"

package/dist/plain/calculate/cycleDateTime.js

@@ -1,7 +1,8 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { cycleFieldValue, dateCycleFieldBounds, timeCycleFieldBounds, } from "../../internal/index.js";
+import { cycleFieldValue, dateCycleFieldBounds, isValidAmount, timeCycleFieldBounds, } from "../../internal/index.js";
 import { isValidDateCycleField, isValidDateTime, isValidDateTimeCycleField, } from "../validate/index.js";
 import { setDateTime } from "./setDateTime.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainDateTime ISO string with `field` cycled by `amount`, wrapping at that field's own
  * min/max instead of carrying into the next larger field.
@@ -20,7 +21,7 @@ import { setDateTime } from "./setDateTime.js";
  * - `options.round` steps to the *next* multiple of `amount` in the direction of its sign
  *   (ceiling for positive, floor for negative) — not the nearest one. See `cycleDate`/`cycleTime`'s
  *   docs for worked examples.
- * - Returns "" for an invalid `value` or an invalid `field`.
+ * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainDateTime string
  * @param field the field to cycle: "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
@@ -36,8 +37,14 @@ import { setDateTime } from "./setDateTime.js";
  * @example cycleDateTime("invalid", "hour", 1) // ""
  */
 export function cycleDateTime(value, field, amount, options) {
-    if (!isValidDateTime(value) || !isValidDateTimeCycleField(field))
+    if (!isOptionsArgument(options)) {
         return "";
+    }
+    if (!isValidDateTime(value) ||
+        !isValidDateTimeCycleField(field) ||
+        !isValidAmount(amount)) {
+        return "";
+    }
     try {
         const dateTime = Temporal.PlainDateTime.from(value);
         const bounds = isValidDateCycleField(field)

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

@@ -1,4 +1,4 @@
-import type { Overflow, TimeCycleField } from "../../types/index.js";
+import type { TimeCycleField } from "../../types/index.js";
 /**
  * Return a PlainTime ISO string with `field` cycled by `amount`, wrapping at that field's own
  * min/max instead of carrying into the next larger field (`hour` 23 `+1` wraps to `0`, it never
@@ -13,16 +13,15 @@ import type { Overflow, TimeCycleField } from "../../types/index.js";
  *   of `amount` in the direction of its sign (ceiling for positive, floor for negative), matching
  *   `@internationalized/date`'s `CycleOptions.round`. E.g. cycling minute `22` by `+15` with
  *   `round: true` lands on `30` (the next multiple of 15 above 22), not `15` (the nearest one).
- * - `options.overflow` is accepted for signature consistency with `cycleDate`/`cycleDateTime`/
- *   `cycleZoned` but is **inert** here: time fields don't share bounds the way `day` shares a
- *   month with `month`/`year`, so the wrapped value `cycleTime` computes is always already valid —
- *   `setTime`'s `.with()` call never has anything to constrain or reject.
- * - Returns "" for an invalid `value` or an invalid `field`.
+ * - There is no `overflow` option (removed in 1.16.0): time fields don't share bounds the way `day`
+ *   shares a month with `month`/`year`, so the wrapped value is always already valid and there is
+ *   nothing to constrain or reject.
+ * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainTime string
  * @param field the field to cycle: "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
  * @param amount signed amount to cycle by
- * @param options optional: round (boolean, default false), overflow ("constrain" | "reject", inert — see above)
+ * @param options optional: round (boolean, default false)
  * @returns ISO PlainTime string with `field` cycled, or "" on invalid input
  *
  * @example cycleTime("09:30:00", "hour", 1) // "10:30:00"
@@ -34,5 +33,4 @@ import type { Overflow, TimeCycleField } from "../../types/index.js";
  */
 export declare function cycleTime(value: string, field: TimeCycleField, amount: number, options?: {
     round?: boolean;
-    overflow?: Overflow;
 }): string;

package/dist/plain/calculate/cycleTime.js

@@ -1,7 +1,8 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { cycleFieldValue, timeCycleFieldBounds } from "../../internal/index.js";
+import { cycleFieldValue, isValidAmount, timeCycleFieldBounds, } from "../../internal/index.js";
 import { isValidTime, isValidTimeCycleField } from "../validate/index.js";
 import { setTime } from "./setTime.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainTime ISO string with `field` cycled by `amount`, wrapping at that field's own
  * min/max instead of carrying into the next larger field (`hour` 23 `+1` wraps to `0`, it never
@@ -16,16 +17,15 @@ import { setTime } from "./setTime.js";
  *   of `amount` in the direction of its sign (ceiling for positive, floor for negative), matching
  *   `@internationalized/date`'s `CycleOptions.round`. E.g. cycling minute `22` by `+15` with
  *   `round: true` lands on `30` (the next multiple of 15 above 22), not `15` (the nearest one).
- * - `options.overflow` is accepted for signature consistency with `cycleDate`/`cycleDateTime`/
- *   `cycleZoned` but is **inert** here: time fields don't share bounds the way `day` shares a
- *   month with `month`/`year`, so the wrapped value `cycleTime` computes is always already valid —
- *   `setTime`'s `.with()` call never has anything to constrain or reject.
- * - Returns "" for an invalid `value` or an invalid `field`.
+ * - There is no `overflow` option (removed in 1.16.0): time fields don't share bounds the way `day`
+ *   shares a month with `month`/`year`, so the wrapped value is always already valid and there is
+ *   nothing to constrain or reject.
+ * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainTime string
  * @param field the field to cycle: "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
  * @param amount signed amount to cycle by
- * @param options optional: round (boolean, default false), overflow ("constrain" | "reject", inert — see above)
+ * @param options optional: round (boolean, default false)
  * @returns ISO PlainTime string with `field` cycled, or "" on invalid input
  *
  * @example cycleTime("09:30:00", "hour", 1) // "10:30:00"
@@ -36,13 +36,19 @@ import { setTime } from "./setTime.js";
  * @example cycleTime("invalid", "hour", 1) // ""
  */
 export function cycleTime(value, field, amount, options) {
-    if (!isValidTime(value) || !isValidTimeCycleField(field))
+    if (!isOptionsArgument(options)) {
         return "";
+    }
+    if (!isValidTime(value) ||
+        !isValidTimeCycleField(field) ||
+        !isValidAmount(amount)) {
+        return "";
+    }
     try {
         const time = Temporal.PlainTime.from(value);
         const bounds = timeCycleFieldBounds(field);
         const newValue = cycleFieldValue(time[field], amount, bounds, options?.round ?? false);
-        return setTime(value, { [field]: newValue }, { overflow: options?.overflow });
+        return setTime(value, { [field]: newValue });
     }
     catch {
         return "";

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

@@ -4,29 +4,46 @@ import type { DateDurationUnit, RoundingOptions } from "../../types/index.js";
  * Return the difference between two PlainDate values using the provided `unit`.
  *
  * - Returns `null` for invalid inputs (negative diffs are valid).
- * - Uses Temporal.PlainDate.until and extracts the requested unit.
- * - Accepts GMT calendar-annotated PlainDate strings (as produced by `convertDateToCalendar`) —
- *   E5 (issue #78). When both `date1` and `date2` carry the *same* calendar tag, the difference
- *   is measured in that calendar (a Hebrew leap year is `P12M12D`, not `P1Y`, in month/day
- *   units — see the roadmap's E5 decisions of record, D5). When they carry different tags (or
- *   either is a bare, untagged ISO string), the difference falls back to measuring in Gregorian.
+ * - Uses Temporal's `until` semantics (TC39 CalendarDateUntil; for non-ISO calendars the Intl
+ *   era/monthCode proposal's NonISODateUntil, e.g. Buddhist Aug 31 to Sep 30 is 30 days, not a
+ *   month) and extracts the requested unit.
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings (as `convertDateToCalendar` writes them).
+ *   When `date1` and `date2` name the *same* calendar, the difference is measured in that
+ *   calendar (a Hebrew leap year has 13 months). When they name different calendars (a bare ISO
+ *   string names `iso8601`), the result is `null`, as TC39 `DifferenceTemporalPlainDate` throws
+ *   when `CalendarEquals` is false.
+ * - Compatibility: before 1.16.0 two different calendars were measured in ISO. To get that value,
+ *   convert both to one calendar first: `convertDateToCalendar(date, "iso8601")`.
  *
  * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result,
  * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "week", roundingMode: "halfExpand" }`
  * rounds the difference to the nearest week before extracting the requested unit.
  * - When `unitArg` is an array, `smallestUnit` must not be coarser than the largest unit in the
- *   array (e.g. `["month", "day"]` with `smallestUnit: "year"`) — this combination is rejected
+ *   array (e.g. `["months", "days"]` with `smallestUnit: "year"`) — this combination is rejected
  *   by Temporal and returns null, same as other invalid input.
+ * - With an array of units, the record is the whole difference: the largest listed unit is
+ *   Temporal's `largestUnit`, and the amount of each unlisted unit between two listed units is
+ *   carried into the next smaller listed unit, measured from the start moved by the larger listed
+ *   amounts (so adding the record to the start reaches the end). Units smaller than the smallest
+ *   listed unit are truncated, as for a single unit. For example, `["years", "days"]` over
+ *   1 year 59 days returns `{ years: 1, days: 59 }`.
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
  *
  * @param date1 ISO PlainDate string for the start, optionally calendar-annotated
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
- * @param unitArg DateDurationUnit | DateDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @param unitArg date unit or units to measure the difference, singular or plural (`"day"` or
+ *   `"days"`); a record result keeps the plural keys
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
- * @example diffDate("2024-03-10", "2024-03-15", "day") // 5
- * @example diffDate("invalid", "2024-03-15", "day") // null
- * @example diffDate("2024-01-01", "2024-01-16", "week", { smallestUnit: "week", roundingMode: "halfExpand" }) // 2
- * @example diffDate("5784-06-15[u-ca=hebrew]", "5784-07-15[u-ca=hebrew]", "months") // 1 (measured in Hebrew, Adar I -> Adar)
+ * @example diffDate("2024-03-10", "2024-03-15", "days") // 5
+ * @example diffDate("2024-01-01", "2024-01-08", ["week", "day"]) // { weeks: 1, days: 0 } (singular names, plural keys)
+ * @example diffDate("invalid", "2024-03-15", "days") // null
+ * @example diffDate("2024-01-01", "2024-01-16", "weeks", { smallestUnit: "week", roundingMode: "halfExpand" }) // 2
+ * @example diffDate("2024-02-24[u-ca=hebrew]", "2024-03-25[u-ca=hebrew]", "months") // 1 (measured in Hebrew, 15 Adar I -> 15 Adar II)
+ * @example diffDate("2023-08-31[u-ca=buddhist]", "2023-09-30[u-ca=buddhist]", "months") // 0 (30 days, not a month)
+ * @example diffDate("2024-10-03[u-ca=hebrew]", "2024-11-03", "days") // null (different calendars)
+ * @example diffDate("2024-01-01", "2025-03-01", ["years", "days"]) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
-export declare function diffDate(date1: string, date2: string, unitArg: DateDurationUnit | DateDurationUnit[], options?: RoundingOptions<Temporal.DateUnit>): number | Record<DateDurationUnit, number> | null;
+export declare function diffDate(date1: string, date2: string, unitArg: DateDurationUnit | Temporal.DateUnit | Array<DateDurationUnit | Temporal.DateUnit>, options?: RoundingOptions<Temporal.DateUnit>): number | Record<DateDurationUnit, number> | null;

package/dist/plain/calculate/diffDate.js

@@ -1,64 +1,99 @@
-import { parseCalendarDatePairForArithmetic } from "../../internal/index.js";
+import { parseCalendarDatePairForArithmetic, plainDateAdd, plainDateUntil, } from "../../internal/index.js";
+import { differenceRecord } from "../../internal/differenceRecord.js";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
 import { getLargestDateDurationUnit } from "./getLargestDateDurationUnit.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the difference between two PlainDate values using the provided `unit`.
  *
  * - Returns `null` for invalid inputs (negative diffs are valid).
- * - Uses Temporal.PlainDate.until and extracts the requested unit.
- * - Accepts GMT calendar-annotated PlainDate strings (as produced by `convertDateToCalendar`) —
- *   E5 (issue #78). When both `date1` and `date2` carry the *same* calendar tag, the difference
- *   is measured in that calendar (a Hebrew leap year is `P12M12D`, not `P1Y`, in month/day
- *   units — see the roadmap's E5 decisions of record, D5). When they carry different tags (or
- *   either is a bare, untagged ISO string), the difference falls back to measuring in Gregorian.
+ * - Uses Temporal's `until` semantics (TC39 CalendarDateUntil; for non-ISO calendars the Intl
+ *   era/monthCode proposal's NonISODateUntil, e.g. Buddhist Aug 31 to Sep 30 is 30 days, not a
+ *   month) and extracts the requested unit.
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings (as `convertDateToCalendar` writes them).
+ *   When `date1` and `date2` name the *same* calendar, the difference is measured in that
+ *   calendar (a Hebrew leap year has 13 months). When they name different calendars (a bare ISO
+ *   string names `iso8601`), the result is `null`, as TC39 `DifferenceTemporalPlainDate` throws
+ *   when `CalendarEquals` is false.
+ * - Compatibility: before 1.16.0 two different calendars were measured in ISO. To get that value,
+ *   convert both to one calendar first: `convertDateToCalendar(date, "iso8601")`.
  *
  * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result,
  * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "week", roundingMode: "halfExpand" }`
  * rounds the difference to the nearest week before extracting the requested unit.
  * - When `unitArg` is an array, `smallestUnit` must not be coarser than the largest unit in the
- *   array (e.g. `["month", "day"]` with `smallestUnit: "year"`) — this combination is rejected
+ *   array (e.g. `["months", "days"]` with `smallestUnit: "year"`) — this combination is rejected
  *   by Temporal and returns null, same as other invalid input.
+ * - With an array of units, the record is the whole difference: the largest listed unit is
+ *   Temporal's `largestUnit`, and the amount of each unlisted unit between two listed units is
+ *   carried into the next smaller listed unit, measured from the start moved by the larger listed
+ *   amounts (so adding the record to the start reaches the end). Units smaller than the smallest
+ *   listed unit are truncated, as for a single unit. For example, `["years", "days"]` over
+ *   1 year 59 days returns `{ years: 1, days: 59 }`.
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
  *
  * @param date1 ISO PlainDate string for the start, optionally calendar-annotated
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
- * @param unitArg DateDurationUnit | DateDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @param unitArg date unit or units to measure the difference, singular or plural (`"day"` or
+ *   `"days"`); a record result keeps the plural keys
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
- * @example diffDate("2024-03-10", "2024-03-15", "day") // 5
- * @example diffDate("invalid", "2024-03-15", "day") // null
- * @example diffDate("2024-01-01", "2024-01-16", "week", { smallestUnit: "week", roundingMode: "halfExpand" }) // 2
- * @example diffDate("5784-06-15[u-ca=hebrew]", "5784-07-15[u-ca=hebrew]", "months") // 1 (measured in Hebrew, Adar I -> Adar)
+ * @example diffDate("2024-03-10", "2024-03-15", "days") // 5
+ * @example diffDate("2024-01-01", "2024-01-08", ["week", "day"]) // { weeks: 1, days: 0 } (singular names, plural keys)
+ * @example diffDate("invalid", "2024-03-15", "days") // null
+ * @example diffDate("2024-01-01", "2024-01-16", "weeks", { smallestUnit: "week", roundingMode: "halfExpand" }) // 2
+ * @example diffDate("2024-02-24[u-ca=hebrew]", "2024-03-25[u-ca=hebrew]", "months") // 1 (measured in Hebrew, 15 Adar I -> 15 Adar II)
+ * @example diffDate("2023-08-31[u-ca=buddhist]", "2023-09-30[u-ca=buddhist]", "months") // 0 (30 days, not a month)
+ * @example diffDate("2024-10-03[u-ca=hebrew]", "2024-11-03", "days") // null (different calendars)
+ * @example diffDate("2024-01-01", "2025-03-01", ["years", "days"]) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
  */
 export function diffDate(date1, date2, unitArg, options) {
-    const validDates = isValidCalendarDate(date1) && isValidCalendarDate(date2);
-    const isSingleUnit = !Array.isArray(unitArg);
-    const validUnits = isSingleUnit
-        ? isValidDateDurationUnit(unitArg)
-        : unitArg.every(isValidDateDurationUnit);
-    if (!validDates || !validUnits) {
-        return null;
-    }
     try {
-        const { a: d1, b: d2 } = parseCalendarDatePairForArithmetic(date1, date2);
-        const duration = d1.until(d2, {
-            largestUnit: isSingleUnit
-                ? unitArg
-                : getLargestDateDurationUnit(unitArg),
-            smallestUnit: options?.smallestUnit,
-            roundingIncrement: options?.roundingIncrement,
-            roundingMode: options?.roundingMode,
-        });
-        // craft record for units passed
-        if (isSingleUnit) {
-            return duration[unitArg] ?? 0;
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const validDates = isValidCalendarDate(date1) && isValidCalendarDate(date2);
+        // Singular names resolve to their plural (Temporal §13.17); record keys are the plural names.
+        const resolved = Array.isArray(unitArg)
+            ? unitArg.map((unit) => resolveDurationUnit(unit))
+            : resolveDurationUnit(unitArg);
+        const isSingleUnit = !Array.isArray(resolved);
+        const validUnits = isSingleUnit
+            ? isValidDateDurationUnit(resolved)
+            : resolved.every(isValidDateDurationUnit);
+        if (!validDates || !validUnits) {
+            return null;
+        }
+        try {
+            // An empty units list names no largest unit, so there is nothing to measure.
+            const largestUnit = isSingleUnit
+                ? resolved
+                : getLargestDateDurationUnit(resolved);
+            if (largestUnit === "")
+                return null;
+            const { a: d1, b: d2 } = parseCalendarDatePairForArithmetic(date1, date2);
+            const duration = plainDateUntil(d1, d2, largestUnit, options);
+            // craft record for units passed
+            if (isSingleUnit) {
+                return duration[resolved] ?? 0;
+            }
+            // An unlisted unit between two listed units is carried into the next smaller listed unit.
+            return differenceRecord(d1, duration, resolved, {
+                add: (from, amount) => plainDateAdd(from, amount),
+                until: (from, to, unit) => plainDateUntil(from, to, unit),
+            });
+        }
+        catch {
+            return null;
         }
-        return unitArg.reduce((result, unit) => {
-            result[unit] = duration[unit] ?? 0;
-            return result;
-        }, {});
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -5,10 +5,11 @@ import type { DateDurationUnit, DurationStringOptions, RoundingOptions } from ".
  * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
  *
  * - Returns `""` for invalid inputs (negative diffs are valid and render with a leading `-`).
- * - Uses Temporal.PlainDate.until with `largestUnit` set to `unit`, then `.toString()`.
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Same shared-vs-mismatched
- *   calendar rule as `diffDate` (see its JSDoc): measured in the shared calendar when `date1`
- *   and `date2` carry the same tag, Gregorian otherwise.
+ * - Uses Temporal's `until` semantics with `largestUnit` set to `unit` (TC39 CalendarDateUntil; for
+ *   non-ISO calendars the Intl era/monthCode proposal's NonISODateUntil), then `.toString()`.
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings. Same calendar rule as `diffDate` (see
+ *   its JSDoc): measured in the shared calendar when `date1` and `date2` name the same calendar,
+ *   `""` when they name different calendars (TC39 `CalendarEquals`; before 1.16.0 measured in ISO).
  * - Unlike `diffDate`, `unit` is a single unit (not an array) — an ISO duration string already
  *   expresses a full multi-unit breakdown via `largestUnit` alone, so there's no array-of-units
  *   overload here.
@@ -20,10 +21,13 @@ import type { DateDurationUnit, DurationStringOptions, RoundingOptions } from ".
  * `parseDuration`'s options) — kept separate from the `.until()` rounding options above because
  * both option sets have colliding `smallestUnit`/`roundingMode` keys with different Temporal types.
  *
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
+ *
  * @param date1 ISO PlainDate string for the start, optionally calendar-annotated
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
- * @param unit DateDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @param unit date unit, singular or plural (`"day"` or `"days"`), to use as the duration's largestUnit
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateAsDuration("2024-03-10", "2024-04-05", "days") // "P26D"
@@ -31,6 +35,7 @@ import type { DateDurationUnit, DurationStringOptions, RoundingOptions } from ".
  * @example diffDateAsDuration("2024-01-01", "2024-01-01", "days") // "PT0S"
  * @example diffDateAsDuration("invalid", "2024-03-15", "days") // ""
  * @example diffDateAsDuration("2024-01-01", "2024-01-16", "weeks", { smallestUnit: "weeks", roundingMode: "halfExpand" }) // "P2W"
- * @example diffDateAsDuration("5784-06-15[u-ca=hebrew]", "5784-07-15[u-ca=hebrew]", "months") // "P1M" (measured in Hebrew, Adar I -> Adar)
+ * @example diffDateAsDuration("2024-02-24[u-ca=hebrew]", "2024-03-25[u-ca=hebrew]", "months") // "P1M" (measured in Hebrew, 15 Adar I -> 15 Adar II)
+ * @example diffDateAsDuration("2023-08-31[u-ca=buddhist]", "2023-09-30[u-ca=buddhist]", "months") // "P30D" (Aug 31 + 1 month would pass Sep 30)
  */
-export declare function diffDateAsDuration(date1: string, date2: string, unit: DateDurationUnit, options?: RoundingOptions<Temporal.DateUnit> & DurationStringOptions): string;
+export declare function diffDateAsDuration(date1: string, date2: string, unit: DateDurationUnit | Temporal.DateUnit, options?: RoundingOptions<Temporal.DateUnit> & DurationStringOptions): string;

package/dist/plain/calculate/diffDateAsDuration.js

@@ -1,14 +1,17 @@
-import { durationUntilString, parseCalendarDatePairForArithmetic } from "../../internal/index.js";
+import { durationUntilString, parseCalendarDatePairForArithmetic, } from "../../internal/index.js";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the difference between two PlainDate values as an ISO 8601 duration string,
  * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
  *
  * - Returns `""` for invalid inputs (negative diffs are valid and render with a leading `-`).
- * - Uses Temporal.PlainDate.until with `largestUnit` set to `unit`, then `.toString()`.
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Same shared-vs-mismatched
- *   calendar rule as `diffDate` (see its JSDoc): measured in the shared calendar when `date1`
- *   and `date2` carry the same tag, Gregorian otherwise.
+ * - Uses Temporal's `until` semantics with `largestUnit` set to `unit` (TC39 CalendarDateUntil; for
+ *   non-ISO calendars the Intl era/monthCode proposal's NonISODateUntil), then `.toString()`.
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings. Same calendar rule as `diffDate` (see
+ *   its JSDoc): measured in the shared calendar when `date1` and `date2` name the same calendar,
+ *   `""` when they name different calendars (TC39 `CalendarEquals`; before 1.16.0 measured in ISO).
  * - Unlike `diffDate`, `unit` is a single unit (not an array) — an ISO duration string already
  *   expresses a full multi-unit breakdown via `largestUnit` alone, so there's no array-of-units
  *   overload here.
@@ -20,10 +23,13 @@ import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.
  * `parseDuration`'s options) — kept separate from the `.until()` rounding options above because
  * both option sets have colliding `smallestUnit`/`roundingMode` keys with different Temporal types.
  *
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
+ *
  * @param date1 ISO PlainDate string for the start, optionally calendar-annotated
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
- * @param unit DateDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @param unit date unit, singular or plural (`"day"` or `"days"`), to use as the duration's largestUnit
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateAsDuration("2024-03-10", "2024-04-05", "days") // "P26D"
@@ -31,17 +37,24 @@ import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.
  * @example diffDateAsDuration("2024-01-01", "2024-01-01", "days") // "PT0S"
  * @example diffDateAsDuration("invalid", "2024-03-15", "days") // ""
  * @example diffDateAsDuration("2024-01-01", "2024-01-16", "weeks", { smallestUnit: "weeks", roundingMode: "halfExpand" }) // "P2W"
- * @example diffDateAsDuration("5784-06-15[u-ca=hebrew]", "5784-07-15[u-ca=hebrew]", "months") // "P1M" (measured in Hebrew, Adar I -> Adar)
+ * @example diffDateAsDuration("2024-02-24[u-ca=hebrew]", "2024-03-25[u-ca=hebrew]", "months") // "P1M" (measured in Hebrew, 15 Adar I -> 15 Adar II)
+ * @example diffDateAsDuration("2023-08-31[u-ca=buddhist]", "2023-09-30[u-ca=buddhist]", "months") // "P30D" (Aug 31 + 1 month would pass Sep 30)
  */
 export function diffDateAsDuration(date1, date2, unit, options) {
+    // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     const validDates = isValidCalendarDate(date1) && isValidCalendarDate(date2);
-    const validUnit = isValidDateDurationUnit(unit);
+    // Singular names resolve to their plural (Temporal §13.17).
+    const resolvedUnit = resolveDurationUnit(unit);
+    const validUnit = isValidDateDurationUnit(resolvedUnit);
     if (!validDates || !validUnit) {
         return "";
     }
     try {
         const { a: d1, b: d2 } = parseCalendarDatePairForArithmetic(date1, date2);
-        return durationUntilString(d1, d2, unit, options);
+        return durationUntilString(d1, d2, resolvedUnit, options);
     }
     catch {
         return "";