@northguild/gmt 1.14.2

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

@@ -0,0 +1,38 @@
+import type { DateTimeCycleField, Overflow } from "../../types/index.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.
+ *
+ * - `cycleDateTime` is not `addDateTime`: cycling December's `month` by `+1` stays in the same
+ *   year, and cycling `hour` `23` by `+1` stays on the same day. Reach for `addDateTime` for
+ *   calendar/clock arithmetic; reach for `cycleDateTime` when a single field (e.g. a datepicker
+ *   segment) must stay isolated from the others.
+ * - Date fields (`year`/`month`/`day`) wrap the same way `cycleDate` does — `year` is unbounded,
+ *   `month` wraps `1–12`, `day` wraps `1`–the current month's day count. Time fields
+ *   (`hour`/`minute`/`second`/`millisecond`/`microsecond`/`nanosecond`) wrap the same way
+ *   `cycleTime` does — `hour` always `0–23` (no `hourCycle: 12` option; see `cycleTime`'s doc for
+ *   why).
+ * - Cycling `month` or `year` can still shift `day` via `overflow`, exactly as `setDateTime`'s
+ *   `.with()` call does.
+ * - `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`.
+ *
+ * @param value ISO PlainDateTime string
+ * @param field the field to cycle: "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
+ * @param amount signed amount to cycle by
+ * @param options optional: round (boolean, default false), overflow ("constrain" | "reject")
+ * @returns ISO PlainDateTime string with `field` cycled, or "" on invalid input
+ *
+ * @example cycleDateTime("2024-06-15T09:30:00", "hour", 1) // "2024-06-15T10:30:00"
+ * @example cycleDateTime("2024-12-15T23:30:00", "month", 1) // "2024-01-15T23:30:00" (wraps, stays in the same year)
+ * @example cycleDateTime("2024-12-15T23:30:00", "hour", 1) // "2024-12-15T00:30:00" (wraps, stays on the same day)
+ * @example cycleDateTime("2024-06-15T09:22:00", "minute", 15, { round: true }) // "2024-06-15T09:30:00"
+ * @example cycleDateTime("2024-06-15T09:30:00", "week", 1) // "" ("week" is not a cyclable field)
+ * @example cycleDateTime("invalid", "hour", 1) // ""
+ */
+export declare function cycleDateTime(value: string, field: DateTimeCycleField, amount: number, options?: {
+    round?: boolean;
+    overflow?: Overflow;
+}): string;

package/dist/plain/calculate/cycleDateTime.js

@@ -0,0 +1,52 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { cycleFieldValue, dateCycleFieldBounds, timeCycleFieldBounds, } from "../../internal/index.js";
+import { isValidDateCycleField, isValidDateTime, isValidDateTimeCycleField, } from "../validate/index.js";
+import { setDateTime } from "./setDateTime.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.
+ *
+ * - `cycleDateTime` is not `addDateTime`: cycling December's `month` by `+1` stays in the same
+ *   year, and cycling `hour` `23` by `+1` stays on the same day. Reach for `addDateTime` for
+ *   calendar/clock arithmetic; reach for `cycleDateTime` when a single field (e.g. a datepicker
+ *   segment) must stay isolated from the others.
+ * - Date fields (`year`/`month`/`day`) wrap the same way `cycleDate` does — `year` is unbounded,
+ *   `month` wraps `1–12`, `day` wraps `1`–the current month's day count. Time fields
+ *   (`hour`/`minute`/`second`/`millisecond`/`microsecond`/`nanosecond`) wrap the same way
+ *   `cycleTime` does — `hour` always `0–23` (no `hourCycle: 12` option; see `cycleTime`'s doc for
+ *   why).
+ * - Cycling `month` or `year` can still shift `day` via `overflow`, exactly as `setDateTime`'s
+ *   `.with()` call does.
+ * - `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`.
+ *
+ * @param value ISO PlainDateTime string
+ * @param field the field to cycle: "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
+ * @param amount signed amount to cycle by
+ * @param options optional: round (boolean, default false), overflow ("constrain" | "reject")
+ * @returns ISO PlainDateTime string with `field` cycled, or "" on invalid input
+ *
+ * @example cycleDateTime("2024-06-15T09:30:00", "hour", 1) // "2024-06-15T10:30:00"
+ * @example cycleDateTime("2024-12-15T23:30:00", "month", 1) // "2024-01-15T23:30:00" (wraps, stays in the same year)
+ * @example cycleDateTime("2024-12-15T23:30:00", "hour", 1) // "2024-12-15T00:30:00" (wraps, stays on the same day)
+ * @example cycleDateTime("2024-06-15T09:22:00", "minute", 15, { round: true }) // "2024-06-15T09:30:00"
+ * @example cycleDateTime("2024-06-15T09:30:00", "week", 1) // "" ("week" is not a cyclable field)
+ * @example cycleDateTime("invalid", "hour", 1) // ""
+ */
+export function cycleDateTime(value, field, amount, options) {
+    if (!isValidDateTime(value) || !isValidDateTimeCycleField(field))
+        return "";
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        const bounds = isValidDateCycleField(field)
+            ? dateCycleFieldBounds(field, dateTime)
+            : timeCycleFieldBounds(field);
+        const newValue = cycleFieldValue(dateTime[field], amount, bounds, options?.round ?? false);
+        return setDateTime(value, { [field]: newValue }, { overflow: options?.overflow });
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,38 @@
+import type { Overflow, 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
+ * changes a date — `cycleTime` has no date component to carry into in the first place).
+ *
+ * - `hour` always cycles `0–23`. GMT has no `hourCycle: 12` option — a 12-hour, AM/PM-preserving
+ *   wrap is a display/formatting concern (locale-driven, via `Intl`), not a value-layer one: there
+ *   is no ISO representation for "this hour, but staying AM" to round-trip through GMT's string
+ *   contract.
+ * - `minute`/`second` wrap `0–59`; `millisecond`/`microsecond`/`nanosecond` wrap `0–999`.
+ * - `options.round` does **not** round to the nearest increment — it steps to the *next* multiple
+ *   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`.
+ *
+ * @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)
+ * @returns ISO PlainTime string with `field` cycled, or "" on invalid input
+ *
+ * @example cycleTime("09:30:00", "hour", 1) // "10:30:00"
+ * @example cycleTime("23:00:00", "hour", 1) // "00:00:00" (wraps)
+ * @example cycleTime("00:00:00", "hour", 25) // "01:00:00" (amount larger than the range)
+ * @example cycleTime("09:22:00", "minute", 15, { round: true }) // "09:30:00"
+ * @example cycleTime("09:30:00", "year", 1) // "" ("year" is not a cyclable time field)
+ * @example cycleTime("invalid", "hour", 1) // ""
+ */
+export declare function cycleTime(value: string, field: TimeCycleField, amount: number, options?: {
+    round?: boolean;
+    overflow?: Overflow;
+}): string;

package/dist/plain/calculate/cycleTime.js

@@ -0,0 +1,50 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { cycleFieldValue, timeCycleFieldBounds } from "../../internal/index.js";
+import { isValidTime, isValidTimeCycleField } from "../validate/index.js";
+import { setTime } from "./setTime.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
+ * changes a date — `cycleTime` has no date component to carry into in the first place).
+ *
+ * - `hour` always cycles `0–23`. GMT has no `hourCycle: 12` option — a 12-hour, AM/PM-preserving
+ *   wrap is a display/formatting concern (locale-driven, via `Intl`), not a value-layer one: there
+ *   is no ISO representation for "this hour, but staying AM" to round-trip through GMT's string
+ *   contract.
+ * - `minute`/`second` wrap `0–59`; `millisecond`/`microsecond`/`nanosecond` wrap `0–999`.
+ * - `options.round` does **not** round to the nearest increment — it steps to the *next* multiple
+ *   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`.
+ *
+ * @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)
+ * @returns ISO PlainTime string with `field` cycled, or "" on invalid input
+ *
+ * @example cycleTime("09:30:00", "hour", 1) // "10:30:00"
+ * @example cycleTime("23:00:00", "hour", 1) // "00:00:00" (wraps)
+ * @example cycleTime("00:00:00", "hour", 25) // "01:00:00" (amount larger than the range)
+ * @example cycleTime("09:22:00", "minute", 15, { round: true }) // "09:30:00"
+ * @example cycleTime("09:30:00", "year", 1) // "" ("year" is not a cyclable time field)
+ * @example cycleTime("invalid", "hour", 1) // ""
+ */
+export function cycleTime(value, field, amount, options) {
+    if (!isValidTime(value) || !isValidTimeCycleField(field))
+        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 });
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { Temporal } from "@js-temporal/polyfill";
+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.
+ *
+ * `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
+ *   by Temporal and returns null, same as other invalid input.
+ *
+ * @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)
+ * @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)
+ */
+export declare function diffDate(date1: string, date2: string, unitArg: DateDurationUnit | DateDurationUnit[], options?: RoundingOptions<Temporal.DateUnit>): number | Record<DateDurationUnit, number> | null;

package/dist/plain/calculate/diffDate.js

@@ -0,0 +1,64 @@
+import { parseCalendarDatePairForArithmetic } from "../../internal/index.js";
+import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
+import { getLargestDateDurationUnit } from "./getLargestDateDurationUnit.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.
+ *
+ * `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
+ *   by Temporal and returns null, same as other invalid input.
+ *
+ * @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)
+ * @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)
+ */
+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;
+        }
+        return unitArg.reduce((result, unit) => {
+            result[unit] = duration[unit] ?? 0;
+            return result;
+        }, {});
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,36 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import type { DateDurationUnit, DurationStringOptions, RoundingOptions } from "../../types/index.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.
+ * - 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.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the
+ * underlying difference before it's rendered, per Temporal's DifferenceOptions — same as `diffDate`.
+ * `toStringSmallestUnit`, `fractionalSecondDigits`, and `toStringRoundingMode` control the
+ * precision of the rendered string itself, per Temporal's ToStringPrecisionOptions (mirroring
+ * `parseDuration`'s options) — kept separate from the `.until()` rounding options above because
+ * both option sets have colliding `smallestUnit`/`roundingMode` keys with different Temporal types.
+ *
+ * @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)
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example diffDateAsDuration("2024-03-10", "2024-04-05", "days") // "P26D"
+ * @example diffDateAsDuration("2024-01-01", "2023-01-01", "days") // "-P365D"
+ * @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)
+ */
+export declare function diffDateAsDuration(date1: string, date2: string, unit: DateDurationUnit, options?: RoundingOptions<Temporal.DateUnit> & DurationStringOptions): string;

package/dist/plain/calculate/diffDateAsDuration.js

@@ -0,0 +1,49 @@
+import { durationUntilString, parseCalendarDatePairForArithmetic } from "../../internal/index.js";
+import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.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.
+ * - 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.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the
+ * underlying difference before it's rendered, per Temporal's DifferenceOptions — same as `diffDate`.
+ * `toStringSmallestUnit`, `fractionalSecondDigits`, and `toStringRoundingMode` control the
+ * precision of the rendered string itself, per Temporal's ToStringPrecisionOptions (mirroring
+ * `parseDuration`'s options) — kept separate from the `.until()` rounding options above because
+ * both option sets have colliding `smallestUnit`/`roundingMode` keys with different Temporal types.
+ *
+ * @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)
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example diffDateAsDuration("2024-03-10", "2024-04-05", "days") // "P26D"
+ * @example diffDateAsDuration("2024-01-01", "2023-01-01", "days") // "-P365D"
+ * @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)
+ */
+export function diffDateAsDuration(date1, date2, unit, options) {
+    const validDates = isValidCalendarDate(date1) && isValidCalendarDate(date2);
+    const validUnit = isValidDateDurationUnit(unit);
+    if (!validDates || !validUnit) {
+        return "";
+    }
+    try {
+        const { a: d1, b: d2 } = parseCalendarDatePairForArithmetic(date1, date2);
+        return durationUntilString(d1, d2, unit, options);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,25 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js";
+/**
+ * Return the difference between two PlainDateTime values in the requested unit.
+ *
+ * - Returns `null` for invalid inputs (negative diffs are valid).
+ * - Uses Temporal.PlainDateTime.until and extracts the requested unit.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result,
+ * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
+ * rounds the difference to the nearest hour before extracting the requested unit.
+ * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
+ *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   Temporal and returns null, same as other invalid input.
+ *
+ * @param dateTime1 ISO PlainDateTime string for the start
+ * @param dateTime2 ISO PlainDateTime string for the end
+ * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @returns numeric difference in the requested unit, or null on invalid input
+ *
+ * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "day") // 5
+ * @example diffDateTime("invalid", "2024-03-15T12:00:00", "day") // null
+ */
+export declare function diffDateTime(dateTime1: string, dateTime2: string, units: DateTimeDurationUnit | DateTimeDurationUnit[], options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;

package/dist/plain/calculate/diffDateTime.js

@@ -0,0 +1,57 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
+import { getLargestDateTimeDurationUnit } from "./getLargestDateTimeDurationUnit.js";
+/**
+ * Return the difference between two PlainDateTime values in the requested unit.
+ *
+ * - Returns `null` for invalid inputs (negative diffs are valid).
+ * - Uses Temporal.PlainDateTime.until and extracts the requested unit.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result,
+ * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "hour", roundingMode: "halfExpand" }`
+ * rounds the difference to the nearest hour before extracting the requested unit.
+ * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
+ *   array (e.g. `["day", "hour"]` with `smallestUnit: "week"`) — this combination is rejected by
+ *   Temporal and returns null, same as other invalid input.
+ *
+ * @param dateTime1 ISO PlainDateTime string for the start
+ * @param dateTime2 ISO PlainDateTime string for the end
+ * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @returns numeric difference in the requested unit, or null on invalid input
+ *
+ * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "day") // 5
+ * @example diffDateTime("invalid", "2024-03-15T12:00:00", "day") // null
+ */
+export function diffDateTime(dateTime1, dateTime2, units, options) {
+    const validDateTimes = isValidDateTime(dateTime1) && isValidDateTime(dateTime2);
+    const isSingleUnit = !Array.isArray(units);
+    const validUnits = isSingleUnit
+        ? isValidDateTimeDurationUnit(units)
+        : units.every(isValidDateTimeDurationUnit);
+    //
+    if (!validDateTimes || !validUnits) {
+        return null;
+    }
+    try {
+        const dt1 = Temporal.PlainDateTime.from(dateTime1);
+        const dt2 = Temporal.PlainDateTime.from(dateTime2);
+        const duration = dt1.until(dt2, {
+            largestUnit: isSingleUnit ? units : getLargestDateTimeDurationUnit(units),
+            smallestUnit: options?.smallestUnit,
+            roundingIncrement: options?.roundingIncrement,
+            roundingMode: options?.roundingMode,
+        });
+        if (isSingleUnit) {
+            return duration[units] ?? 0;
+        }
+        // craft record for units passed
+        return units.reduce((result, unit) => {
+            result[unit] = duration[unit] ?? 0;
+            return result;
+        }, {});
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } from "../../types/index.js";
+/**
+ * Return the difference between two PlainDateTime 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.PlainDateTime.until with `largestUnit` set to `unit`, then `.toString()`.
+ * - Unlike `diffDateTime`, `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.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the
+ * underlying difference before it's rendered, per Temporal's DifferenceOptions — same as
+ * `diffDateTime`. `toStringSmallestUnit`, `fractionalSecondDigits`, and `toStringRoundingMode`
+ * control the precision of the rendered string itself, per Temporal's ToStringPrecisionOptions
+ * (mirroring `parseDuration`'s options) — kept separate from the `.until()` rounding options
+ * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
+ * different Temporal types.
+ *
+ * @param dateTime1 ISO PlainDateTime string for the start
+ * @param dateTime2 ISO PlainDateTime string for the end
+ * @param unit DateTimeDurationUnit to use as the duration's largestUnit
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example diffDateTimeAsDuration("2024-03-10T00:00:00", "2024-03-11T02:00:00", "days") // "P1DT2H"
+ * @example diffDateTimeAsDuration("2024-03-11T02:00:00", "2024-03-10T00:00:00", "days") // "-P1DT2H"
+ * @example diffDateTimeAsDuration("2024-01-01T00:00:00", "2024-01-01T00:00:00", "days") // "PT0S"
+ * @example diffDateTimeAsDuration("invalid", "2024-03-15T12:00:00", "days") // ""
+ * @example diffDateTimeAsDuration("2024-02-29T00:00:00", "2024-02-29T01:30:00", "hours", { smallestUnit: "hours", roundingMode: "halfExpand" }) // "PT2H"
+ */
+export declare function diffDateTimeAsDuration(dateTime1: string, dateTime2: string, unit: DateTimeDurationUnit, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

package/dist/plain/calculate/diffDateTimeAsDuration.js

@@ -0,0 +1,48 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { durationUntilString } from "../../internal/index.js";
+import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
+/**
+ * Return the difference between two PlainDateTime 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.PlainDateTime.until with `largestUnit` set to `unit`, then `.toString()`.
+ * - Unlike `diffDateTime`, `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.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the
+ * underlying difference before it's rendered, per Temporal's DifferenceOptions — same as
+ * `diffDateTime`. `toStringSmallestUnit`, `fractionalSecondDigits`, and `toStringRoundingMode`
+ * control the precision of the rendered string itself, per Temporal's ToStringPrecisionOptions
+ * (mirroring `parseDuration`'s options) — kept separate from the `.until()` rounding options
+ * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
+ * different Temporal types.
+ *
+ * @param dateTime1 ISO PlainDateTime string for the start
+ * @param dateTime2 ISO PlainDateTime string for the end
+ * @param unit DateTimeDurationUnit to use as the duration's largestUnit
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @returns ISO 8601 duration string, or "" on invalid input
+ *
+ * @example diffDateTimeAsDuration("2024-03-10T00:00:00", "2024-03-11T02:00:00", "days") // "P1DT2H"
+ * @example diffDateTimeAsDuration("2024-03-11T02:00:00", "2024-03-10T00:00:00", "days") // "-P1DT2H"
+ * @example diffDateTimeAsDuration("2024-01-01T00:00:00", "2024-01-01T00:00:00", "days") // "PT0S"
+ * @example diffDateTimeAsDuration("invalid", "2024-03-15T12:00:00", "days") // ""
+ * @example diffDateTimeAsDuration("2024-02-29T00:00:00", "2024-02-29T01:30:00", "hours", { smallestUnit: "hours", roundingMode: "halfExpand" }) // "PT2H"
+ */
+export function diffDateTimeAsDuration(dateTime1, dateTime2, unit, options) {
+    const validDateTimes = isValidDateTime(dateTime1) && isValidDateTime(dateTime2);
+    const validUnit = isValidDateTimeDurationUnit(unit);
+    if (!validDateTimes || !validUnit) {
+        return "";
+    }
+    try {
+        const dt1 = Temporal.PlainDateTime.from(dateTime1);
+        const dt2 = Temporal.PlainDateTime.from(dateTime2);
+        return durationUntilString(dt1, dt2, unit, options);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,25 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { RoundingOptions, TimeDurationUnit } from "../../types/index.js";
+/**
+ * Return the difference between two PlainTime values in the requested unit.
+ *
+ * - Returns `null` for invalid inputs.
+ * - Uses Temporal.PlainTime.until with `largestUnit` and extracts the requested unit.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result,
+ * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "minute", roundingMode: "halfExpand" }`
+ * rounds the difference to the nearest minute before extracting the requested unit.
+ * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
+ *   array (e.g. `["minute", "second"]` with `smallestUnit: "hour"`) — this combination is
+ *   rejected by Temporal and returns null, same as other invalid input.
+ *
+ * @param time1 ISO PlainTime string for the start
+ * @param time2 ISO PlainTime string for the end
+ * @param units TimeDurationUnit | TimeDurationUnit[] to measure the difference
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @returns numeric difference in the requested unit, or null on invalid input
+ *
+ * @example diffTime("12:00:00", "14:30:00", "hour") // 2
+ * @example diffTime("invalid", "14:30:00", "hour") // null
+ */
+export declare function diffTime(time1: string, time2: string, units: TimeDurationUnit | TimeDurationUnit[], options?: RoundingOptions<Temporal.TimeUnit>): number | Record<TimeDurationUnit, number> | null;

package/dist/plain/calculate/diffTime.js

@@ -0,0 +1,56 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
+import { getLargestTimeDurationUnit } from "./getLargestTimeDurationUnit.js";
+/**
+ * Return the difference between two PlainTime values in the requested unit.
+ *
+ * - Returns `null` for invalid inputs.
+ * - Uses Temporal.PlainTime.until with `largestUnit` and extracts the requested unit.
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the result,
+ * per Temporal's DifferenceOptions — e.g. `{ smallestUnit: "minute", roundingMode: "halfExpand" }`
+ * rounds the difference to the nearest minute before extracting the requested unit.
+ * - When `units` is an array, `smallestUnit` must not be coarser than the largest unit in the
+ *   array (e.g. `["minute", "second"]` with `smallestUnit: "hour"`) — this combination is
+ *   rejected by Temporal and returns null, same as other invalid input.
+ *
+ * @param time1 ISO PlainTime string for the start
+ * @param time2 ISO PlainTime string for the end
+ * @param units TimeDurationUnit | TimeDurationUnit[] to measure the difference
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @returns numeric difference in the requested unit, or null on invalid input
+ *
+ * @example diffTime("12:00:00", "14:30:00", "hour") // 2
+ * @example diffTime("invalid", "14:30:00", "hour") // null
+ */
+export function diffTime(time1, time2, units, options) {
+    const validTimes = isValidTime(time1) && isValidTime(time2);
+    const isSingleUnit = !Array.isArray(units);
+    const validUnits = isSingleUnit
+        ? isValidTimeDurationUnit(units)
+        : units.every(isValidTimeDurationUnit);
+    if (!validTimes || !validUnits) {
+        return null;
+    }
+    try {
+        const t1 = Temporal.PlainTime.from(time1);
+        const t2 = Temporal.PlainTime.from(time2);
+        const duration = t1.until(t2, {
+            largestUnit: isSingleUnit ? units : getLargestTimeDurationUnit(units),
+            smallestUnit: options?.smallestUnit,
+            roundingIncrement: options?.roundingIncrement,
+            roundingMode: options?.roundingMode,
+        });
+        // craft record for units passed
+        if (isSingleUnit) {
+            return duration[units] ?? 0;
+        }
+        return units.reduce((result, unit) => {
+            result[unit] = duration[unit] ?? 0;
+            return result;
+        }, {});
+    }
+    catch {
+        return null;
+    }
+}