@northguild/gmt 1.15.0 → 1.17.0

package/dist/zoned/calculate/addZoned.js

@@ -1,88 +1,103 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { calendarSystemOfZonedValue, formatZonedInCalendar, isValidAmount, parseCalendarZonedValue, resolveOverflow, } from "../../internal/index.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { addToZonedDisambiguated, calendarSystemOfZonedValue, formatZonedInCalendar, isValidAmount, parseCalendarZonedValue, resolveOverflow, } from "../../internal/index.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Add a temporal amount to a zoned ISO 8601 datetime string and return a zoned ISO 8601 string.
  *
  * - Uses Temporal.ZonedDateTime.add to add duration.
  * - Validates duration units and values.
- * - Accepts a GMT calendar-annotated zoned string (as produced by `convertZonedToCalendar`, e.g.
- *   `"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`), not just a bare ISO string —
- *   E7 (issue #152). Calendar-unit arithmetic ("add 1 month") resolves against that calendar (a
- *   Hebrew leap month, an Ethiopic Pagumen, a Japanese era change) **and** the DST rules of the
- *   zone, in one operation. The calendar tag, the era, the wall time and the UTC offset are all
- *   re-derived from the result, never copied from the input — Hebrew Adar I 15 in
- *   `America/New_York` `+1 month` moves both the month (Adar I -> Adar) and the offset
- *   (-05:00 -> -04:00). A bare ISO string is unaffected — always treated as, and always returns,
- *   `"gregorian"`.
- * - `disambiguation` controls DST resolution ONLY when the arithmetic result lands on an ambiguous
- *   local time from a fall-back (DST-end) overlap: "compatible" (default), "earlier", "later", or
- *   "reject" (throws, resulting in ""). Has no effect when the result lands in a spring-forward
- *   (DST-start) gap — Temporal's arithmetic always resolves gap landings unambiguously (by advancing
- *   past the gap) before disambiguation is ever evaluated.
- * - `offset` ("prefer" | "use" | "ignore" (default) | "reject") is accepted for API consistency with
- *   sibling zoned-construction functions (see `startOfZoned`, `endOfZoned`, etc.) but has **no effect
- *   here**: the internal rebuild step reconstructs from a plain datetime string with no UTC offset
- *   embedded, so there is never a stored offset for `offset` to prefer/use/ignore/reject against.
- *   `disambiguation` is the only option that affects this function's output.
+ * - Accepts an RFC 9557 calendar-annotated zoned string (as `Temporal.ZonedDateTime#toString()`
+ *   and `convertZonedToCalendar` write it, e.g.
+ *   `"2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]"`), not just a bare ISO string (E7,
+ *   issue #152). Calendar-unit arithmetic ("add 1 month") resolves against that calendar (a Hebrew
+ *   leap month, an Ethiopic Pagumen) **and** the DST rules of the zone, in one operation: Hebrew
+ *   Adar I 15 in `America/New_York` `+1 month` moves both the month (Adar I -> Adar II) and the
+ *   offset (-05:00 -> -04:00). 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, the `[u-ca=<id>]`
+ *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
+ * - Follows Temporal's AddZonedDateTime: the date portion of the duration (years, months, weeks,
+ *   days) moves the wall-clock date, then the time portion (hours and smaller) is added in exact
+ *   time. `disambiguation` ("compatible" (default), "earlier", "later", or "reject" (returns
+ *   "")) applies ONLY to the intermediate wall-clock date-time after the date portion, exactly as
+ *   Temporal's GetEpochNanosecondsFor resolves it: in a fall-back (DST-end) overlap "compatible"
+ *   and "earlier" take the earlier instant and "later" the later one; in a spring-forward
+ *   (DST-start) gap "compatible" and "later" move the wall clock forward by the gap length and
+ *   "earlier" back by it; "reject" returns "" for both. It never re-resolves the exact-time
+ *   result, so a time-only duration ignores it.
+ * - Compatibility: before 1.16.0 a date portion landing in a spring-forward gap was always moved
+ *   forward, whatever `disambiguation` said, so "earlier" matched "compatible" and "reject" did not
+ *   fail. Pass "compatible" (or omit it) to keep the forward result.
+ * - Compatibility: before 1.16.0 a non-"compatible" `disambiguation` re-resolved the final wall
+ *   clock (so `+ { minutes: 10 }` from `01:30-05:00` with "earlier" returned `01:40-04:00`, 50
+ *   minutes earlier in exact time). To get that value, re-resolve the result's wall clock:
+ *   `setZoned(result, { hour, minute, second }, { disambiguation, offset: "ignore" })`.
+ * - There is no `offset` option (removed in 1.16.0): the intermediate wall clock is resolved from
+ *   a plain date-time, which has no UTC offset for it to act on (Temporal
+ *   `PlainDateTime#toZonedDateTime` reads only `disambiguation`).
  * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
  *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
  * - Returns "" for invalid input.
  *
  * @param value ISO 8601 zoned datetime string, optionally calendar-annotated
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject" — accepted but inert, see above), overflow ("constrain" | "reject")
+ * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), overflow ("constrain" | "reject")
  * @returns zoned ISO 8601 string on success, or "" on invalid input
  *
  * @example addZoned("2024-02-29T14:30:45.123-05:00[America/New_York]", { days: 1 }) // "2024-03-01T14:30:45.123-05:00[America/New_York]"
  * @example addZoned("invalid", { days: 1 }) // ""
- * @example addZoned("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", { months: 1 }) // "5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]" (Adar I -> Adar, EST -> EDT in one call)
- * @example addZoned("0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]", { days: 1 }) // "0001-05-01T12:00:00+09:00[u-ca=japanese;era=reiwa][Asia/Tokyo]" (era re-derived, not copied)
- * @example addZoned("7517-12-30T00:30:00-04:00[u-ca=ethiopic-amete-alem][America/Santiago]", { months: 1 }, { overflow: "reject" }) // "" (day 30 does not exist in the 5-day Pagumen)
- * @example addZoned("2024-03-10T14:30:00-04:00[America/New_York][u-ca=hebrew]", { days: 1 }) // "" (Temporal's segment ordering is not GMT's grammar)
+ * @example addZoned("2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]", { months: 1 }) // "2024-03-25T14:30:00-04:00[America/New_York][u-ca=hebrew]" (Adar I -> Adar II, EST -> EDT in one call)
+ * @example addZoned("2019-04-30T12:00:00+09:00[Asia/Tokyo][u-ca=japanese]", { days: 1 }) // "2019-05-01T12:00:00+09:00[Asia/Tokyo][u-ca=japanese]" (Heisei 31 -> Reiwa 1)
+ * @example addZoned("2025-09-05T00:30:00-04:00[America/Santiago][u-ca=ethioaa]", { months: 1 }, { overflow: "reject" }) // "" (day 30 does not exist in the 5-day Pagumen)
+ * @example addZoned("2024-03-10T14:30:00-04:00[u-ca=hebrew][America/New_York]", { days: 1 }) // "" (calendar before zone is not RFC 9557)
  * @example addZoned("2024-11-02T01:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "later" }) // "2024-11-03T01:30:00-05:00[America/New_York]" (fall-back overlap resolved; default "compatible" would return the -04:00 instant instead)
  * @example addZoned("2024-11-02T01:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "" (fall-back overlap rejected)
- * @example addZoned("2024-03-09T02:30:00-05:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "2024-03-10T03:30:00-04:00[America/New_York]" (spring-forward gap — disambiguation has no effect, arithmetic already advanced past it, so "reject" does not throw here)
+ * @example addZoned("2024-03-09T02:30:00-05:00[America/New_York]", { days: 1 }) // "2024-03-10T03:30:00-04:00[America/New_York]" (02:30 on 10 March is in the spring-forward gap; "compatible" moves it forward an hour)
+ * @example addZoned("2024-03-09T02:30:00-05:00[America/New_York]", { days: 1 }, { disambiguation: "earlier" }) // "2024-03-10T01:30:00-05:00[America/New_York]" (spring-forward gap; "earlier" moves it back an hour)
+ * @example addZoned("2024-03-09T02:30:00-05:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "" (spring-forward gap rejected)
+ * @example addZoned("2024-11-03T01:30:00-05:00[America/New_York]", { minutes: 10 }, { disambiguation: "earlier" }) // "2024-11-03T01:40:00-05:00[America/New_York]" (exact time — disambiguation never re-resolves it)
+ * @example setZoned(addZoned("2024-11-03T01:30:00-05:00[America/New_York]", { minutes: 10 }), { hour: 1, minute: 40, second: 0 }, { disambiguation: "earlier", offset: "ignore" }) // "2024-11-03T01:40:00-04:00[America/New_York]" (pre-1.16.0 result)
  * @example addZoned("2024-01-31T12:00:00-05:00[America/New_York]", { months: 1 }, { overflow: "reject" }) // ""
  */
 export function addZoned(value, units, optionsArg) {
-    const validZonedDateTime = isValidCalendarZonedDateTime(value);
-    const validUnits = Object.keys(units).every(isValidDateTimeDurationUnit);
-    const validAmounts = Object.values(units).every(isValidAmount);
-    if (!validZonedDateTime || !validUnits || !validAmounts) {
-        // TODO descriptive messages of what failed - likely could be GMT offset for historical changes and DST
-        return "";
-    }
-    const disambiguation = optionsArg?.disambiguation ?? "compatible";
-    const offset = optionsArg?.offset ?? "ignore";
-    const overflow = resolveOverflow(optionsArg?.overflow);
     try {
-        const calendar = calendarSystemOfZonedValue(value);
-        if (!calendar) {
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const validZonedDateTime = isValidCalendarZonedDateTime(value);
+        const validUnits = typeof units === "object" &&
+            units !== null &&
+            Object.keys(units).every(isValidDateTimeDurationUnit);
+        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
+        if (!validZonedDateTime || !validUnits || !validAmounts) {
+            // TODO descriptive messages of what failed - likely could be GMT offset for historical changes and DST
             return "";
         }
-        const zoned = parseCalendarZonedValue(value);
-        const added = zoned.add(units, { overflow });
-        if (disambiguation === "compatible") {
+        const disambiguation = optionsArg?.disambiguation === undefined
+            ? "compatible"
+            : optionsArg.disambiguation;
+        const overflow = resolveOverflow(optionsArg?.overflow);
+        try {
+            const calendar = calendarSystemOfZonedValue(value);
+            if (!calendar) {
+                return "";
+            }
+            const zoned = parseCalendarZonedValue(value);
+            const added = addToZonedDisambiguated(zoned, units, 1, {
+                overflow,
+                disambiguation,
+            });
             return formatZonedInCalendar(added, calendar);
         }
-        // The calendar MUST be stripped before this rebuild string is composed (E7 risk R1). A
-        // calendared `.toPlainDateTime().toString()` emits Temporal's own annotation — verified:
-        // "2024-03-25T14:30:00[u-ca=hebrew]" — so appending `[${timeZoneId}]` yields
-        // "...[u-ca=hebrew][America/New_York]", which is GMT's forbidden ordering and which
-        // `Temporal.ZonedDateTime.from` rejects. Without this the whole branch would silently degrade
-        // to "" for every non-"compatible" disambiguation the moment a calendar tag reached it.
-        // Round-tripping the rebuild through bare ISO and re-attaching the calendar to the RESULT
-        // (never to the input) keeps both the DST resolution and the calendar tag correct.
-        const plainDateTime = added
-            .withCalendar("iso8601")
-            .toPlainDateTime()
-            .toString();
-        const resolved = Temporal.ZonedDateTime.from(`${plainDateTime}[${added.timeZoneId}]`, { disambiguation, offset }).withCalendar(added.calendarId);
-        return formatZonedInCalendar(resolved, calendar);
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/zoned/calculate/addZonedBusinessDays.d.ts

@@ -2,6 +2,8 @@
  * Return a zoned ISO 8601 datetime string with `amount` business days added to `value`.
  *
  * - Uses fixed ISO Monday–Friday business days (no locale awareness).
+ * - Has no calendar parameter, so no other weekend and no holidays. It is not the
+ *   zoned form of the plain `addBusinessDays`, which takes a `BusinessCalendar`.
  * - Saturday and Sunday are skipped during the count.
  * - Preserves the original time component through the operation.
  * - Returns "" on invalid input.

package/dist/zoned/calculate/addZonedBusinessDays.js

@@ -1,9 +1,12 @@
-import { adjustZonedBusinessDays, isValidAmount } from "../../internal/index.js";
+import { isValidAmount } from "../../internal/index.js";
+import { adjustZonedBusinessDays } from "../../internal/adjustZonedBusinessDays.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 /**
  * Return a zoned ISO 8601 datetime string with `amount` business days added to `value`.
  *
  * - Uses fixed ISO Monday–Friday business days (no locale awareness).
+ * - Has no calendar parameter, so no other weekend and no holidays. It is not the
+ *   zoned form of the plain `addBusinessDays`, which takes a `BusinessCalendar`.
  * - Saturday and Sunday are skipped during the count.
  * - Preserves the original time component through the operation.
  * - Returns "" on invalid input.
@@ -22,7 +25,7 @@ export function addZonedBusinessDays(value, amount) {
         return "";
     }
     if (amount === 0) {
-        return value;
+        return adjustZonedBusinessDays(value, 1, 0);
     }
     const absAmount = Math.abs(amount);
     const direction = amount > 0 ? 1 : -1;

package/dist/zoned/calculate/clampZoned.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Restrict `value` to the range [`min`, `max`] in zoned datetime space.
  *
@@ -26,9 +27,9 @@ export function clampZoned(value, min, max) {
         return "";
     }
     try {
-        const v = Temporal.ZonedDateTime.from(value);
-        const mn = Temporal.ZonedDateTime.from(min);
-        const mx = Temporal.ZonedDateTime.from(max);
+        const v = zonedDateTimeFrom(value);
+        const mn = zonedDateTimeFrom(min);
+        const mx = zonedDateTimeFrom(max);
         if (Temporal.ZonedDateTime.compare(mn, mx) === 1) {
             return "";
         }

package/dist/zoned/calculate/closestZonedTo.d.ts

@@ -2,17 +2,17 @@
  * Return the candidate zoned datetime nearest to `target` by temporal distance.
  *
  * - Distance is measured in total days using `Temporal.Instant` epoch milliseconds.
- * - Returns `null` if the candidates array is empty or contains no valid dates.
- * - Returns `null` if `target` is invalid.
+ * - 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 ZonedDateTime string to measure distance from
  * @param candidates Array of ISO ZonedDateTime strings to choose from
- * @returns The nearest candidate zoned datetime string, or null on invalid input
+ * @returns The nearest candidate zoned datetime string, or "" on invalid input
  *
  * @example closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", ["2024-03-01T00:00:00+00:00[UTC]", "2024-03-20T00:00:00+00:00[UTC]", "2024-03-18T00:00:00+00:00[UTC]"]) // "2024-03-18T00:00:00+00:00[UTC]"
  * @example closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", ["2024-03-01T00:00:00+00:00[UTC]", "2024-03-29T00:00:00+00:00[UTC]"]) // "2024-03-29T00:00:00+00:00[UTC]"
- * @example closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", []) // null
- * @example closestZonedTo("invalid", ["2024-03-01T00:00:00+00:00[UTC]"]) // null
+ * @example closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", []) // ""
+ * @example closestZonedTo("invalid", ["2024-03-01T00:00:00+00:00[UTC]"]) // ""
  */
-export declare function closestZonedTo(target: string, candidates: string[]): string | null;
+export declare function closestZonedTo(target: string, candidates: string[]): string;

package/dist/zoned/calculate/closestZonedTo.js

@@ -1,46 +1,55 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the candidate zoned datetime nearest to `target` by temporal distance.
  *
  * - Distance is measured in total days using `Temporal.Instant` epoch milliseconds.
- * - Returns `null` if the candidates array is empty or contains no valid dates.
- * - Returns `null` if `target` is invalid.
+ * - 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 ZonedDateTime string to measure distance from
  * @param candidates Array of ISO ZonedDateTime strings to choose from
- * @returns The nearest candidate zoned datetime string, or null on invalid input
+ * @returns The nearest candidate zoned datetime string, or "" on invalid input
  *
  * @example closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", ["2024-03-01T00:00:00+00:00[UTC]", "2024-03-20T00:00:00+00:00[UTC]", "2024-03-18T00:00:00+00:00[UTC]"]) // "2024-03-18T00:00:00+00:00[UTC]"
  * @example closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", ["2024-03-01T00:00:00+00:00[UTC]", "2024-03-29T00:00:00+00:00[UTC]"]) // "2024-03-29T00:00:00+00:00[UTC]"
- * @example closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", []) // null
- * @example closestZonedTo("invalid", ["2024-03-01T00:00:00+00:00[UTC]"]) // null
+ * @example closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", []) // ""
+ * @example closestZonedTo("invalid", ["2024-03-01T00:00:00+00:00[UTC]"]) // ""
  */
 export function closestZonedTo(target, candidates) {
-    if (!isValidZonedDateTime(target) || !candidates.length) {
-        return null;
-    }
     try {
-        const t = Temporal.ZonedDateTime.from(target);
-        const validCandidates = candidates.filter(isValidZonedDateTime);
-        if (!validCandidates.length) {
-            return null;
+        if (!isValidZonedDateTime(target) ||
+            !Array.isArray(candidates) ||
+            !candidates.length) {
+            return "";
+        }
+        try {
+            const t = zonedDateTimeFrom(target);
+            const validCandidates = candidates.filter(isValidZonedDateTime);
+            if (!validCandidates.length) {
+                return "";
+            }
+            const parsed = validCandidates.map((c) => ({
+                str: c,
+                date: zonedDateTimeFrom(c),
+            }));
+            const closest = parsed.reduce((best, candidate) => {
+                const bestDist = Math.abs(best.date.toInstant().epochMilliseconds -
+                    t.toInstant().epochMilliseconds) / 86400000;
+                const candDist = Math.abs(candidate.date.toInstant().epochMilliseconds -
+                    t.toInstant().epochMilliseconds) / 86400000;
+                return candDist < bestDist ? candidate : best;
+            }, parsed[0]);
+            return closest.date.toString();
+        }
+        catch {
+            return "";
         }
-        const parsed = validCandidates.map((c) => ({
-            str: c,
-            date: Temporal.ZonedDateTime.from(c),
-        }));
-        const closest = parsed.reduce((best, candidate) => {
-            const bestDist = Math.abs(best.date.toInstant().epochMilliseconds -
-                t.toInstant().epochMilliseconds) / 86400000;
-            const candDist = Math.abs(candidate.date.toInstant().epochMilliseconds -
-                t.toInstant().epochMilliseconds) / 86400000;
-            return candDist < bestDist ? candidate : best;
-        }, parsed[0]);
-        return closest.date.toString();
     }
     catch {
-        return null;
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
     }
 }

package/dist/zoned/calculate/cycleZoned.d.ts

@@ -13,26 +13,29 @@ import type { DateTimeCycleField, Disambiguation, Offset, Overflow } from "../..
  *   whatever DST edge case results (the wrapped local time landing in a gap or an overlap) exactly
  *   the way it resolves any other field-set call. This is deliberately simpler than deriving
  *   DST-aware wrap boundaries directly.
- * - `disambiguation` defaults to `"compatible"` and `offset` defaults to `"ignore"` (not
- *   Temporal's own `"prefer"` default) — the same C3 precedent as `setZoned`/`startOfZoned`: with
- *   `"prefer"`, the source's still-valid offset is kept and `disambiguation` is silently never
- *   consulted. Leave `offset` at its default unless you specifically need Temporal's raw `.with()`
- *   semantics.
+ * - `disambiguation` defaults to `"compatible"` and `offset` defaults to `"prefer"`, as Temporal's
+ *   `ZonedDateTime#with` does: when the source's offset is still valid for the cycled wall time
+ *   (a repeated fall-back hour), it is kept and `disambiguation` is not consulted. Pass
+ *   `offset: "ignore"` to resolve the cycled wall time through `disambiguation` instead.
+ * - **Compatibility:** before 1.16.0 `offset` defaulted to `"ignore"`. Pass `{ offset: "ignore" }`
+ *   to keep that resolution.
  * - `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 zoned ISO 8601 datetime 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"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param options optional: round (boolean, default false), overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "prefer")
  * @returns zoned ISO 8601 string with `field` cycled, or "" on invalid input
  *
  * @example cycleZoned("2024-06-15T09:30:00-05:00[America/Chicago]", "hour", 1) // "2024-06-15T10:30:00-05:00[America/Chicago]"
  * @example cycleZoned("2024-12-15T09:30:00-06:00[America/Chicago]", "month", 1) // "2024-01-15T09:30:00-06:00[America/Chicago]" (wraps, stays in the same year)
  * @example cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1) // "2024-03-10T03:30:00-05:00[America/Chicago]" (cycled hour lands in a spring-forward gap; "compatible" skips forward)
  * @example cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1, { disambiguation: "reject" }) // "" (same gap; "reject" throws)
+ * @example cycleZoned("2024-11-03T00:30:00-05:00[America/Chicago]", "hour", 1, { disambiguation: "reject" }) // "2024-11-03T01:30:00-05:00[America/Chicago]" (repeated hour; offset "prefer" keeps -05:00)
+ * @example cycleZoned("2024-11-03T00:30:00-05:00[America/Chicago]", "hour", 1, { disambiguation: "reject", offset: "ignore" }) // ""
  * @example cycleZoned("2024-06-15T09:30:00-05:00[America/Chicago]", "week", 1) // "" ("week" is not a cyclable field)
  * @example cycleZoned("invalid", "hour", 1) // ""
  */

package/dist/zoned/calculate/cycleZoned.js

@@ -1,8 +1,8 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { cycleFieldValue, dateCycleFieldBounds, timeCycleFieldBounds, } from "../../internal/index.js";
+import { cycleFieldValue, dateCycleFieldBounds, isValidAmount, timeCycleFieldBounds, zonedDateTimeFrom, } from "../../internal/index.js";
 import { isValidDateCycleField, isValidDateTimeCycleField, } from "../../plain/validate/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
 import { setZoned } from "./setZoned.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a ZonedDateTime ISO string with `field` cycled by `amount`, wrapping at that field's own
  * min/max instead of carrying into the next larger field.
@@ -17,35 +17,43 @@ import { setZoned } from "./setZoned.js";
  *   whatever DST edge case results (the wrapped local time landing in a gap or an overlap) exactly
  *   the way it resolves any other field-set call. This is deliberately simpler than deriving
  *   DST-aware wrap boundaries directly.
- * - `disambiguation` defaults to `"compatible"` and `offset` defaults to `"ignore"` (not
- *   Temporal's own `"prefer"` default) — the same C3 precedent as `setZoned`/`startOfZoned`: with
- *   `"prefer"`, the source's still-valid offset is kept and `disambiguation` is silently never
- *   consulted. Leave `offset` at its default unless you specifically need Temporal's raw `.with()`
- *   semantics.
+ * - `disambiguation` defaults to `"compatible"` and `offset` defaults to `"prefer"`, as Temporal's
+ *   `ZonedDateTime#with` does: when the source's offset is still valid for the cycled wall time
+ *   (a repeated fall-back hour), it is kept and `disambiguation` is not consulted. Pass
+ *   `offset: "ignore"` to resolve the cycled wall time through `disambiguation` instead.
+ * - **Compatibility:** before 1.16.0 `offset` defaulted to `"ignore"`. Pass `{ offset: "ignore" }`
+ *   to keep that resolution.
  * - `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 zoned ISO 8601 datetime 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"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param options optional: round (boolean, default false), overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "prefer")
  * @returns zoned ISO 8601 string with `field` cycled, or "" on invalid input
  *
  * @example cycleZoned("2024-06-15T09:30:00-05:00[America/Chicago]", "hour", 1) // "2024-06-15T10:30:00-05:00[America/Chicago]"
  * @example cycleZoned("2024-12-15T09:30:00-06:00[America/Chicago]", "month", 1) // "2024-01-15T09:30:00-06:00[America/Chicago]" (wraps, stays in the same year)
  * @example cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1) // "2024-03-10T03:30:00-05:00[America/Chicago]" (cycled hour lands in a spring-forward gap; "compatible" skips forward)
  * @example cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1, { disambiguation: "reject" }) // "" (same gap; "reject" throws)
+ * @example cycleZoned("2024-11-03T00:30:00-05:00[America/Chicago]", "hour", 1, { disambiguation: "reject" }) // "2024-11-03T01:30:00-05:00[America/Chicago]" (repeated hour; offset "prefer" keeps -05:00)
+ * @example cycleZoned("2024-11-03T00:30:00-05:00[America/Chicago]", "hour", 1, { disambiguation: "reject", offset: "ignore" }) // ""
  * @example cycleZoned("2024-06-15T09:30:00-05:00[America/Chicago]", "week", 1) // "" ("week" is not a cyclable field)
  * @example cycleZoned("invalid", "hour", 1) // ""
  */
 export function cycleZoned(value, field, amount, options) {
-    if (!isValidZonedDateTime(value) || !isValidDateTimeCycleField(field)) {
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
+    if (!isValidZonedDateTime(value) ||
+        !isValidDateTimeCycleField(field) ||
+        !isValidAmount(amount)) {
         return "";
     }
     try {
-        const zoned = Temporal.ZonedDateTime.from(value);
+        const zoned = zonedDateTimeFrom(value);
         const bounds = isValidDateCycleField(field)
             ? dateCycleFieldBounds(field, zoned)
             : timeCycleFieldBounds(field);

package/dist/zoned/calculate/diffZoned.d.ts

@@ -4,36 +4,58 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
  * Return the difference between two zoned datetimes measured in the given date-time unit.
  *
  * - Uses Temporal.ZonedDateTime.until to calculate difference.
- * - Converts both to UTC for consistent calculation.
+ * - Follows Temporal's DifferenceZonedDateTime: calendar units (days, weeks, months, years) are
+ *   measured on the zone's own wall clock, so a 23-hour DST day is 1 day and a month from Jan 31
+ *   follows the local date; time units (hours and smaller) are exact elapsed time.
+ * - Two values in different time zones (by TC39 TimeZoneEquals, so `UTC` equals `Etc/UTC`) can
+ *   only be differenced in time units: a calendar largest unit returns null, because day lengths
+ *   differ between zones.
+ * - Compatibility: before 1.16.0 both values were converted to UTC first, so calendar units were
+ *   measured on the UTC clock and mixed zones were accepted. To get that value, difference the UTC
+ *   instants: `diffUtc(convertZonedToUtc(value1), convertZonedToUtc(value2), units)`.
  * - Supports single unit or array of units.
- * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) —
- *   E7 (issue #152). When BOTH endpoints carry the same calendar tag, calendar units are measured
- *   in that calendar (a Hebrew leap year spans 13 month boundaries, not 14). When the tags
- *   mismatch, or either endpoint is a bare ISO string, the measurement falls back to
- *   Gregorian/ISO rather than returning the sentinel (E7's D5-zoned). That fallback is mandatory
- *   here, not a convenience: `Temporal.ZonedDateTime.prototype.until` throws across mismatched
- *   calendars for EVERY `largestUnit` — verified, including `"hour"` and `"nanosecond"` — so
- *   without it a purely time-unit question like "how many hours between these two moments" would
- *   return null just because the two strings named different calendars.
+ * - Accepts RFC 9557 calendar-annotated zoned strings (as `convertZonedToCalendar` writes them;
+ *   E7, issue #152). When BOTH endpoints name the same calendar, calendar units are measured in
+ *   that calendar (a Hebrew leap year spans 13 months, not 12). When they name different calendars
+ *   (a bare ISO string names `iso8601`), the result is `null` for every unit, hours included, as
+ *   TC39 `DifferenceTemporalZonedDateTime` 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: `convertZonedToCalendar(value, "iso8601")`.
  * - Returns null for invalid input.
  *
  * `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
+ *   array (e.g. `["days", "hours"]` with `smallestUnit: "week"`) — 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 }`.
+ *   Days carried into a time unit follow the zone's wall clock (a 23-hour DST day is 23 hours).
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, the `[u-ca=<id>]`
+ *   annotation after the zone, canonical calendar ids); see `isValidCalendarZonedDateTime`.
  *
  * @param value1 zoned ISO 8601 datetime string (start), optionally calendar-annotated
  * @param value2 zoned ISO 8601 datetime string (end), optionally calendar-annotated
- * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)
+ * @param units date-time 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 diffZoned("2024-02-28T14:30:00+00:00[UTC]", "2024-03-01T15:30:00+00:00[UTC]", "days") // 2
+ * @example diffZoned("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]", "days") // 1 (a 23-hour local day)
+ * @example diffZoned("2024-01-01T00:00:00-05:00[America/New_York]", "2024-01-03T00:00:00+01:00[Europe/Paris]", "days") // null (calendar unit across two time zones)
+ * @example diffUtc(convertZonedToUtc("2024-03-09T12:00:00-05:00[America/New_York]"), convertZonedToUtc("2024-03-10T12:00:00-04:00[America/New_York]"), "days") // 0 (pre-1.16.0 UTC-clock result)
+ * @example diffZoned("2024-02-28T14:30:00+00:00[UTC]", "2024-03-01T15:30:00+00:00[UTC]", ["day", "hour"]) // { days: 2, hours: 1 } (singular names, plural keys)
  * @example diffZoned("invalid", "2024-03-01T15:30:00+00:00[UTC]", "days") // null
- * @example diffZoned("5784-01-01T00:00:00-04:00[u-ca=hebrew][America/New_York]", "5785-01-01T00:00:00-04:00[u-ca=hebrew][America/New_York]", "months") // 13 (Hebrew leap year; the ISO equivalent is 12)
- * @example diffZoned("5784-01-01T00:00:00-04:00[u-ca=hebrew][America/New_York]", "1446-03-30T00:00:00-04:00[u-ca=islamic-tabular][America/New_York]", "hours") // measured in Gregorian/ISO (mismatched tags fall back rather than returning null)
- * @example diffZoned("2024-03-10T14:30:00-04:00[America/New_York][u-ca=hebrew]", "2024-03-11T14:30:00-04:00[America/New_York]", "days") // null (Temporal's segment ordering is not GMT's grammar)
+ * @example diffZoned("2023-09-16T00:00:00-04:00[America/New_York][u-ca=hebrew]", "2024-10-03T00:00:00-04:00[America/New_York][u-ca=hebrew]", "months") // 13 (Hebrew leap year 5784; the ISO equivalent is 12)
+ * @example diffZoned("2023-09-16T00:00:00-04:00[America/New_York][u-ca=hebrew]", "2024-10-03T00:00:00-04:00[America/New_York][u-ca=islamic-tbla]", "hours") // null (different calendars)
+ * @example diffZoned("2024-03-10T14:30:00-04:00[u-ca=hebrew][America/New_York]", "2024-03-11T14:30:00-04:00[America/New_York]", "days") // null (calendar before zone is not RFC 9557)
+ * @example diffZoned("2024-01-01T00:00:00+00:00[UTC]", "2025-03-01T00:00:00+00:00[UTC]", ["years", "days"]) // { years: 1, days: 59 } (P1Y2M; the 2 months are carried into days)
+ * @example diffZoned("2024-02-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", ["months", "hours"]) // { months: 1, hours: 47 } (P1M2D; the 2 days include the 23-hour 2024-03-10)
  */
-export declare function diffZoned(value1: string, value2: string, units: DateTimeDurationUnit | DateTimeDurationUnit[], options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;
+export declare function diffZoned(value1: string, value2: string, units: DateTimeDurationUnit | Temporal.DateTimeUnit | Array<DateTimeDurationUnit | Temporal.DateTimeUnit>, options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;