@northguild/gmt 1.15.0 → 1.17.0

package/dist/utc/parse/parseUnitFromUtc.js

@@ -1,55 +1,82 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveReadingTimeZone } from "../../internal/resolveReadingTimeZone.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract a unit from a UTC datetime string.
  *
- * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond".
- * - Uses Temporal.Instant.from to parse, converts to UTC.
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns "".
+ * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
+ *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
  * @param unit unit to extract from the datetime
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations, timeZone (IANA, default "UTC"); a non-object value (such as `null`) is invalid
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromUtc("2024-03-17T14:30:45Z", "month") // "03"
+ * @example parseUnitFromUtc("2024-03-17T14:30:45Z", "hours") // "14"
+ * @example parseUnitFromUtc("2024-03-17T02:30:45Z", "day", { timeZone: "America/New_York" }) // "16"
  * @example parseUnitFromUtc("2024-01-01T00:00:00Z", "week") // "1"
- * @example parseUnitFromUtc("2024-01-01T00:00:00Z", "week", { weekStartsOn: "sunday" }) // "1"
+ * @example parseUnitFromUtc("2024-12-31T12:00:00Z", "week", { weekStartsOn: "sunday" }) // "1"
  * @example parseUnitFromUtc("invalid", "month") // ""
  */
 export function parseUnitFromUtc(value, unit, optionsArg) {
-    if (!isValidUtc(value)) {
-        return "";
-    }
-    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        switch (unit) {
-            case "year":
-                return dateTime.year.toString();
-            case "month":
-                return dateTime.month.toString().padStart(2, "0");
-            case "week":
-                return (getWeekNumber(`${dateTime.year}-${dateTime.month.toString().padStart(2, "0")}-${dateTime.day.toString().padStart(2, "0")}`, weekStartsOn) ?? 0).toString();
-            case "day":
-                return dateTime.day.toString().padStart(2, "0");
-            case "dayOfWeek":
-                return dateTime.dayOfWeek.toString();
-            case "hour":
-                return dateTime.hour.toString().padStart(2, "0");
-            case "minute":
-                return dateTime.minute.toString().padStart(2, "0");
-            case "second":
-                return dateTime.second.toString().padStart(2, "0");
-            case "millisecond":
-                return dateTime.millisecond.toString().padStart(3, "0");
-            default:
-                return "";
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        const timeZone = resolveReadingTimeZone(optionsArg?.timeZone);
+        if (!isValidUtc(value) || weekStartsOn === null || timeZone === null) {
+            return "";
+        }
+        try {
+            const dateTime = Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
+            switch (resolveDateTimeUnit(unit)) {
+                case "year":
+                    return dateTime.year.toString();
+                case "month":
+                    return dateTime.month.toString().padStart(2, "0");
+                case "week":
+                    return (getWeekNumber(dateTime.toPlainDate().toString(), weekStartsOn) ?? 0).toString();
+                case "day":
+                    return dateTime.day.toString().padStart(2, "0");
+                case "dayOfWeek":
+                    return dateTime.dayOfWeek.toString();
+                case "hour":
+                    return dateTime.hour.toString().padStart(2, "0");
+                case "minute":
+                    return dateTime.minute.toString().padStart(2, "0");
+                case "second":
+                    return dateTime.second.toString().padStart(2, "0");
+                case "millisecond":
+                    return dateTime.millisecond.toString().padStart(3, "0");
+                case "microsecond":
+                    return dateTime.microsecond.toString().padStart(3, "0");
+                case "nanosecond":
+                    return dateTime.nanosecond.toString().padStart(3, "0");
+                default:
+                    return "";
+            }
+        }
+        catch {
+            return "";
         }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/parse/parseWeekFromUtc.d.ts

@@ -1,16 +1,29 @@
 /**
  * Return the week number from a UTC datetime string.
  *
- * - By default uses ISO weeks (Monday-based).
+ * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ *   first Thursday, so late-December days can be week 1 of the next year (a value on 2024-12-31
+ *   → 1). The result is 1–53.
+ * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
+ *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
+ *   next year (2024-12-31 → 1, 2000-12-30 → 53). The result is 1–53.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The week is read from the value's date on the wall clock of `options.timeZone` (an IANA zone,
+ *   default UTC), as `parseTimeFromUtc` does; an invalid zone returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
- * @returns Week number (1-53) or null on invalid input
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations, timeZone (IANA, default "UTC")
+ * @returns Week number (1-53), or null on invalid input
  *
  * @example parseWeekFromUtc("2024-03-17T14:30:45Z") // 11
+ * @example parseWeekFromUtc("2024-12-31T12:00:00Z") // 1 (ISO week 1 of 2025)
+ * @example parseWeekFromUtc("2024-12-31T12:00:00Z", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
+ * @example parseWeekFromUtc("2000-12-31T12:00:00Z", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2001)
+ * @example parseWeekFromUtc("2024-03-17T02:30:45Z", { weekStartsOn: "sunday", timeZone: "America/New_York" }) // 11 (Saturday 16 March in New York)
  * @example parseWeekFromUtc("invalid") // null
  */
 export declare function parseWeekFromUtc(value: string, optionsArg?: {
     weekStartsOn?: "monday" | "sunday";
+    timeZone?: string;
 }): number | null;

package/dist/utc/parse/parseWeekFromUtc.js

@@ -1,30 +1,58 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveReadingTimeZone } from "../../internal/resolveReadingTimeZone.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the week number from a UTC datetime string.
  *
- * - By default uses ISO weeks (Monday-based).
+ * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ *   first Thursday, so late-December days can be week 1 of the next year (a value on 2024-12-31
+ *   → 1). The result is 1–53.
+ * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
+ *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
+ *   next year (2024-12-31 → 1, 2000-12-30 → 53). The result is 1–53.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The week is read from the value's date on the wall clock of `options.timeZone` (an IANA zone,
+ *   default UTC), as `parseTimeFromUtc` does; an invalid zone returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
- * @returns Week number (1-53) or null on invalid input
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations, timeZone (IANA, default "UTC")
+ * @returns Week number (1-53), or null on invalid input
  *
  * @example parseWeekFromUtc("2024-03-17T14:30:45Z") // 11
+ * @example parseWeekFromUtc("2024-12-31T12:00:00Z") // 1 (ISO week 1 of 2025)
+ * @example parseWeekFromUtc("2024-12-31T12:00:00Z", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
+ * @example parseWeekFromUtc("2000-12-31T12:00:00Z", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2001)
+ * @example parseWeekFromUtc("2024-03-17T02:30:45Z", { weekStartsOn: "sunday", timeZone: "America/New_York" }) // 11 (Saturday 16 March in New York)
  * @example parseWeekFromUtc("invalid") // null
  */
 export function parseWeekFromUtc(value, optionsArg) {
-    if (!isValidUtc(value))
-        return null;
-    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
     try {
-        const instant = Temporal.Instant.from(value);
-        const dt = instant.toZonedDateTimeISO("UTC");
-        const dateStr = `${dt.year}-${dt.month.toString().padStart(2, "0")}-${dt.day.toString().padStart(2, "0")}`;
-        return getWeekNumber(dateStr, weekStartsOn);
+        if (!isOptionsArgument(optionsArg)) {
+            return null;
+        }
+        if (!isValidUtc(value))
+            return null;
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        const timeZone = resolveReadingTimeZone(optionsArg?.timeZone);
+        if (weekStartsOn === null || timeZone === null)
+            return null;
+        try {
+            const instant = Temporal.Instant.from(value);
+            const dt = instant.toZonedDateTimeISO(timeZone);
+            const dateStr = dt.toPlainDate().toString();
+            return getWeekNumber(dateStr, weekStartsOn);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/utc/parse/parseYearFromUtc.d.ts

@@ -2,12 +2,18 @@
  * Return the year from a UTC datetime string.
  *
  * - Returns the year as a string (e.g., "2024").
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns Year (YYYY) or "" on invalid input
  *
  * @example parseYearFromUtc("2024-03-17T14:30:45Z") // "2024"
+ * @example parseYearFromUtc("2025-01-01T02:00:00Z", { timeZone: "America/New_York" }) // "2024"
  * @example parseYearFromUtc("invalid") // ""
  */
-export declare function parseYearFromUtc(value: string): string;
+export declare function parseYearFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseYearFromUtc.js

@@ -1,26 +1,32 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../validate/index.js";
+import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the year from a UTC datetime string.
  *
  * - Returns the year as a string (e.g., "2024").
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns Year (YYYY) or "" on invalid input
  *
  * @example parseYearFromUtc("2024-03-17T14:30:45Z") // "2024"
+ * @example parseYearFromUtc("2025-01-01T02:00:00Z", { timeZone: "America/New_York" }) // "2024"
  * @example parseYearFromUtc("invalid") // ""
  */
-export function parseYearFromUtc(value) {
-    if (!isValidUtc(value))
-        return "";
+export function parseYearFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return dateTime.year.toString();
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const dateTime = utcZonedDateTime(value, options);
+        return dateTime === null ? "" : dateTime.year.toString();
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/validate/isValidUtc.d.ts

@@ -1,7 +1,11 @@
 /**
  * Return true when the provided string is a valid ISO 8601 UTC datetime.
  *
- * - Uses regex to check format before parsing.
+ * - The part before the first annotation must match `utcDateTime` (`<date>T<time>Z`): ISO 8601
+ *   extended format with an upper-case `Z`, so `z`, a `t` or space separator and basic format fail.
+ * - Reads RFC 9557 annotations as `Temporal.Instant.from` does: elective ones (`[foo=bar]`), a
+ *   time zone annotation and a calendar annotation are ignored (an instant has neither), and an
+ *   unknown critical one (`[!foo=bar]`) is rejected.
  * - Rejects leap seconds (e.g., "2024-12-31T23:59:60Z").
  * - Uses Temporal.Instant.from for validation.
  * - Requires a time component — date-only strings ("2024-01-01Z") are rejected.
@@ -11,6 +15,9 @@
  *
  * @example isValidUtc("2024-03-17T14:30:45Z") // true
  * @example isValidUtc("2024-01-01Z") // false — date-only not supported
+ * @example isValidUtc("2024-03-17T14:30:45z") // false — lower-case z (ISO 8601 extended format only)
+ * @example isValidUtc("2024-03-17T14:30:45Z[Europe/Paris]") // true — the annotation is ignored
+ * @example isValidUtc("2024-03-17T14:30:45Z[!foo=bar]") // false — unknown critical annotation
  * @example isValidUtc("2024-12-31T23:59:60Z") // false
  * @example isValidUtc("invalid") // false
  */

package/dist/utc/validate/isValidUtc.js

@@ -1,10 +1,15 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isoStringBody } from "../../internal/isoStringBody.js";
 import { isLeapSecond } from "../../plain/validate/index.js";
 import { utcDateTime } from "../../regex/utc-date-time.js";
 /**
  * Return true when the provided string is a valid ISO 8601 UTC datetime.
  *
- * - Uses regex to check format before parsing.
+ * - The part before the first annotation must match `utcDateTime` (`<date>T<time>Z`): ISO 8601
+ *   extended format with an upper-case `Z`, so `z`, a `t` or space separator and basic format fail.
+ * - Reads RFC 9557 annotations as `Temporal.Instant.from` does: elective ones (`[foo=bar]`), a
+ *   time zone annotation and a calendar annotation are ignored (an instant has neither), and an
+ *   unknown critical one (`[!foo=bar]`) is rejected.
  * - Rejects leap seconds (e.g., "2024-12-31T23:59:60Z").
  * - Uses Temporal.Instant.from for validation.
  * - Requires a time component — date-only strings ("2024-01-01Z") are rejected.
@@ -14,14 +19,18 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  *
  * @example isValidUtc("2024-03-17T14:30:45Z") // true
  * @example isValidUtc("2024-01-01Z") // false — date-only not supported
+ * @example isValidUtc("2024-03-17T14:30:45z") // false — lower-case z (ISO 8601 extended format only)
+ * @example isValidUtc("2024-03-17T14:30:45Z[Europe/Paris]") // true — the annotation is ignored
+ * @example isValidUtc("2024-03-17T14:30:45Z[!foo=bar]") // false — unknown critical annotation
  * @example isValidUtc("2024-12-31T23:59:60Z") // false
  * @example isValidUtc("invalid") // false
  */
 export function isValidUtc(value) {
-    if (isLeapSecond(value)) {
+    const body = isoStringBody(value);
+    if (isLeapSecond(body)) {
         return false;
     }
-    if (!utcDateTime.test(value)) {
+    if (!utcDateTime.test(body)) {
         return false;
     }
     try {

package/dist/utc/validate/isValidUtcRange.d.ts

@@ -2,7 +2,8 @@
  * Return true if `value1` and `value2` form a valid UTC range — both parseable as
  * ISO UTC datetime strings and the instant at `value1` is <= the instant at `value2`.
  *
- * - Both inputs must be ISO 8601 UTC datetime strings (e.g. `"2024-01-01T10:00:00Z"`).
+ * - Both inputs must be ISO 8601 UTC datetime strings (e.g. `"2024-01-01T10:00:00Z"`), as
+ *   `isValidUtc` accepts, annotations included.
  * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Leap-second strings return `false`.
  * - Invalid input or malformed strings return `false`.
@@ -16,7 +17,7 @@
  * @example isValidUtcRange({ value1: "2024-12-31T23:59:59Z", value2: "2024-01-01T10:00:00Z" }) // false
  * @example isValidUtcRange({ value1: "2024-01-01T10:00:00Z", value2: "2024-01-01T10:00:00Z", options: { allowEqual: true } }) // true
  */
-export declare function isValidUtcRange({ value1, value2, options, }: {
+export declare function isValidUtcRange(props: {
     value1: string;
     value2: string;
     options?: {

package/dist/utc/validate/isValidUtcRange.js

@@ -1,11 +1,13 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+import { isValidUtc } from "./isValidUtc.js";
+import { isObject, isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true if `value1` and `value2` form a valid UTC range — both parseable as
  * ISO UTC datetime strings and the instant at `value1` is <= the instant at `value2`.
  *
- * - Both inputs must be ISO 8601 UTC datetime strings (e.g. `"2024-01-01T10:00:00Z"`).
+ * - Both inputs must be ISO 8601 UTC datetime strings (e.g. `"2024-01-01T10:00:00Z"`), as
+ *   `isValidUtc` accepts, annotations included.
  * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Leap-second strings return `false`.
  * - Invalid input or malformed strings return `false`.
@@ -19,26 +21,35 @@ import { utcDateTime } from "../../regex/utc-date-time.js";
  * @example isValidUtcRange({ value1: "2024-12-31T23:59:59Z", value2: "2024-01-01T10:00:00Z" }) // false
  * @example isValidUtcRange({ value1: "2024-01-01T10:00:00Z", value2: "2024-01-01T10:00:00Z", options: { allowEqual: true } }) // true
  */
-export function isValidUtcRange({ value1, value2, options, }) {
-    if (typeof value1 !== "string" || typeof value2 !== "string") {
-        return false;
-    }
-    if (!utcDateTime.test(value1) || !utcDateTime.test(value2)) {
-        return false;
-    }
-    if (isLeapSecond(value1) || isLeapSecond(value2)) {
-        return false;
-    }
+export function isValidUtcRange(props) {
     try {
-        const startInstant = Temporal.Instant.from(value1);
-        const endInstant = Temporal.Instant.from(value2);
-        const cmp = Temporal.Instant.compare(startInstant, endInstant);
-        if (options?.allowEqual) {
-            return cmp <= 0;
+        if (!isObject(props))
+            return false;
+        const { value1, value2, options } = props;
+        if (!isOptionsArgument(options))
+            return false;
+        if (typeof value1 !== "string" || typeof value2 !== "string") {
+            return false;
+        }
+        if (!isValidUtc(value1) || !isValidUtc(value2)) {
+            return false;
+        }
+        try {
+            const startInstant = Temporal.Instant.from(value1);
+            const endInstant = Temporal.Instant.from(value2);
+            const cmp = Temporal.Instant.compare(startInstant, endInstant);
+            if (options?.allowEqual) {
+                return cmp <= 0;
+            }
+            return cmp < 0;
+        }
+        catch {
+            return false;
         }
-        return cmp < 0;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

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

@@ -1,50 +1,63 @@
-import type { DateTimeDurationUnit, Disambiguation, Offset, Overflow } from "../../types/index.js";
+import type { DateTimeDurationUnit, Disambiguation, Overflow } from "../../types/index.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 declare function addZoned(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, optionsArg?: {
     disambiguation?: Disambiguation;
-    offset?: Offset;
     overflow?: Overflow;
 }): string;