@northguild/gmt 1.14.2 → 1.16.0

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;

package/dist/zoned/calculate/diffZoned.js

@@ -1,76 +1,121 @@
-import { parseCalendarZonedPairForArithmetic } from "../../internal/index.js";
+import { addToZoned, isCalendarDifferenceAcrossZones, parseCalendarZonedPairForArithmetic, zonedUntil, } from "../../internal/index.js";
+import { differenceRecord } from "../../internal/differenceRecord.js";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 import { getLargestDateTimeDurationUnit } from "../../plain/calculate/getLargestDateTimeDurationUnit.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.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 function diffZoned(value1, value2, units, options) {
-    const validZonedDateTimes = isValidCalendarZonedDateTime(value1) &&
-        isValidCalendarZonedDateTime(value2);
-    const isSingleUnit = !Array.isArray(units);
-    const validUnits = isSingleUnit
-        ? isValidDateTimeDurationUnit(units)
-        : units.every(isValidDateTimeDurationUnit);
-    if (!validZonedDateTimes || !validUnits) {
-        return null;
-    }
     try {
-        // Calendar resolution has to happen BEFORE the UTC normalization, and the normalization has
-        // to preserve the calendar rather than discard it — the two are independent axes.
-        // `withTimeZone` keeps the calendar tag intact (verified), so re-zoning both operands to UTC
-        // still measures in the pair's resolved calendar.
-        const { a, b } = parseCalendarZonedPairForArithmetic(value1, value2);
-        const normalizedZdt1 = a.withTimeZone("UTC");
-        const normalizedZdt2 = b.withTimeZone("UTC");
-        const duration = normalizedZdt1.until(normalizedZdt2, {
-            largestUnit: isSingleUnit ? units : getLargestDateTimeDurationUnit(units),
-            smallestUnit: options?.smallestUnit,
-            roundingIncrement: options?.roundingIncrement,
-            roundingMode: options?.roundingMode,
-        });
-        if (isSingleUnit) {
-            return duration[units] ?? 0;
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const validZonedDateTimes = isValidCalendarZonedDateTime(value1) &&
+            isValidCalendarZonedDateTime(value2);
+        // Singular names resolve to their plural (Temporal §13.17); record keys are the plural names.
+        const resolved = Array.isArray(units)
+            ? units.map((unit) => resolveDurationUnit(unit))
+            : resolveDurationUnit(units);
+        const isSingleUnit = !Array.isArray(resolved);
+        const validUnits = isSingleUnit
+            ? isValidDateTimeDurationUnit(resolved)
+            : resolved.every(isValidDateTimeDurationUnit);
+        if (!validZonedDateTimes || !validUnits) {
+            return null;
+        }
+        try {
+            const { a, b } = parseCalendarZonedPairForArithmetic(value1, value2);
+            const largestUnit = isSingleUnit
+                ? resolved
+                : getLargestDateTimeDurationUnit(resolved);
+            if (largestUnit === "")
+                return null;
+            if (isCalendarDifferenceAcrossZones(a, b, largestUnit)) {
+                return null;
+            }
+            const duration = zonedUntil(a, b, {
+                largestUnit,
+                smallestUnit: options?.smallestUnit,
+                roundingIncrement: options?.roundingIncrement,
+                roundingMode: options?.roundingMode,
+            });
+            if (isSingleUnit) {
+                return duration[resolved] ?? 0;
+            }
+            // An unlisted unit between two listed units is carried into the next smaller listed unit.
+            return differenceRecord(a, duration, resolved, {
+                add: (from, amount) => addToZoned(from, amount),
+                until: (from, to, largest) => zonedUntil(from, to, {
+                    largestUnit: largest,
+                }),
+            });
+        }
+        catch {
+            return null;
         }
-        return units.reduce((result, unit) => {
-            result[unit] = duration[unit] ?? 0;
-            return result;
-        }, {});
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -5,9 +5,14 @@ import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } fro
  * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
  *
  * - Uses Temporal.ZonedDateTime.until with `largestUnit` set to `unit`, then `.toString()`.
- * - Converts both to UTC for consistent calculation, same as `diffZoned`.
- * - Accepts GMT calendar-annotated zoned strings, with the same shared-calendar-or-Gregorian-
- *   fallback policy as `diffZoned` (E7's D5-zoned, issue #152).
+ * - Measures like `diffZoned` (Temporal's DifferenceZonedDateTime): calendar units on the zone's
+ *   own wall clock, time units in exact elapsed time. Values in different time zones with a
+ *   calendar `unit` (days or larger) return "".
+ * - Compatibility: before 1.16.0 both values were converted to UTC first. To get that value:
+ *   `diffUtcAsDuration(convertZonedToUtc(value1), convertZonedToUtc(value2), unit)`.
+ * - Accepts RFC 9557 calendar-annotated zoned strings, with the same calendar rule as `diffZoned`:
+ *   measured in the shared calendar, `""` when the two name different calendars (TC39
+ *   `CalendarEquals`; before 1.16.0 measured in ISO).
  * - Unlike `diffZoned`, `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.
@@ -21,16 +26,21 @@ import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } fro
  * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
  * different Temporal types.
  *
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, 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 unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @param unit date-time unit to use as the duration's largestUnit, singular or plural (`"day"` or `"days"`)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
- * @example diffZonedAsDuration("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", "days") // "P1DT23H"
+ * @example diffZonedAsDuration("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", "days") // "P2D" (wall-clock days; 47 elapsed hours)
  * @example diffZonedAsDuration("2028-01-01T00:00:00+00:00[UTC]", "2028-01-01T00:00:00+00:00[UTC]", "hours") // "PT0S"
+ * @example diffZonedAsDuration("2028-01-01T00:00:00+00:00[UTC]", "2028-01-02T13:00:00+13:00[Pacific/Apia]", "days") // "" (calendar unit across two time zones)
+ * @example diffUtcAsDuration(convertZonedToUtc("2024-03-09T12:00:00-05:00[America/New_York]"), convertZonedToUtc("2024-03-11T12:00:00-04:00[America/New_York]"), "days") // "P1DT23H" (pre-1.16.0 UTC-clock result)
  * @example diffZonedAsDuration("invalid", "2028-01-01T00:00:00+00:00[UTC]", "days") // ""
- * @example diffZonedAsDuration("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") // "P13M" (Hebrew leap year)
- * @example diffZonedAsDuration("2024-03-10T14:30:00-04:00[America/New_York][u-ca=hebrew]", "2024-03-11T14:30:00-04:00[America/New_York]", "days") // "" (Temporal's segment ordering is not GMT's grammar)
+ * @example diffZonedAsDuration("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") // "P13M" (Hebrew leap year 5784)
+ * @example diffZonedAsDuration("2024-03-10T14:30:00-04:00[u-ca=hebrew][America/New_York]", "2024-03-11T14:30:00-04:00[America/New_York]", "days") // "" (calendar before zone is not RFC 9557)
  */
-export declare function diffZonedAsDuration(value1: string, value2: string, unit: DateTimeDurationUnit, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;
+export declare function diffZonedAsDuration(value1: string, value2: string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

package/dist/zoned/calculate/diffZonedAsDuration.js

@@ -1,14 +1,21 @@
-import { durationUntilString, parseCalendarZonedPairForArithmetic, } from "../../internal/index.js";
+import { durationUntilString, isCalendarDifferenceAcrossZones, parseCalendarZonedPairForArithmetic, } from "../../internal/index.js";
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidCalendarZonedDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the difference between two zoned datetimes as an ISO 8601 duration string,
  * bridging to the `duration` namespace (see `parseDuration`, `normalizeDuration`).
  *
  * - Uses Temporal.ZonedDateTime.until with `largestUnit` set to `unit`, then `.toString()`.
- * - Converts both to UTC for consistent calculation, same as `diffZoned`.
- * - Accepts GMT calendar-annotated zoned strings, with the same shared-calendar-or-Gregorian-
- *   fallback policy as `diffZoned` (E7's D5-zoned, issue #152).
+ * - Measures like `diffZoned` (Temporal's DifferenceZonedDateTime): calendar units on the zone's
+ *   own wall clock, time units in exact elapsed time. Values in different time zones with a
+ *   calendar `unit` (days or larger) return "".
+ * - Compatibility: before 1.16.0 both values were converted to UTC first. To get that value:
+ *   `diffUtcAsDuration(convertZonedToUtc(value1), convertZonedToUtc(value2), unit)`.
+ * - Accepts RFC 9557 calendar-annotated zoned strings, with the same calendar rule as `diffZoned`:
+ *   measured in the shared calendar, `""` when the two name different calendars (TC39
+ *   `CalendarEquals`; before 1.16.0 measured in ISO).
  * - Unlike `diffZoned`, `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.
@@ -22,32 +29,42 @@ import { isValidCalendarZonedDateTime } from "../validate/index.js";
  * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
  * different Temporal types.
  *
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, 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 unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)
+ * @param unit date-time unit to use as the duration's largestUnit, singular or plural (`"day"` or `"days"`)
+ * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
- * @example diffZonedAsDuration("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", "days") // "P1DT23H"
+ * @example diffZonedAsDuration("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", "days") // "P2D" (wall-clock days; 47 elapsed hours)
  * @example diffZonedAsDuration("2028-01-01T00:00:00+00:00[UTC]", "2028-01-01T00:00:00+00:00[UTC]", "hours") // "PT0S"
+ * @example diffZonedAsDuration("2028-01-01T00:00:00+00:00[UTC]", "2028-01-02T13:00:00+13:00[Pacific/Apia]", "days") // "" (calendar unit across two time zones)
+ * @example diffUtcAsDuration(convertZonedToUtc("2024-03-09T12:00:00-05:00[America/New_York]"), convertZonedToUtc("2024-03-11T12:00:00-04:00[America/New_York]"), "days") // "P1DT23H" (pre-1.16.0 UTC-clock result)
  * @example diffZonedAsDuration("invalid", "2028-01-01T00:00:00+00:00[UTC]", "days") // ""
- * @example diffZonedAsDuration("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") // "P13M" (Hebrew leap year)
- * @example diffZonedAsDuration("2024-03-10T14:30:00-04:00[America/New_York][u-ca=hebrew]", "2024-03-11T14:30:00-04:00[America/New_York]", "days") // "" (Temporal's segment ordering is not GMT's grammar)
+ * @example diffZonedAsDuration("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") // "P13M" (Hebrew leap year 5784)
+ * @example diffZonedAsDuration("2024-03-10T14:30:00-04:00[u-ca=hebrew][America/New_York]", "2024-03-11T14:30:00-04:00[America/New_York]", "days") // "" (calendar before zone is not RFC 9557)
  */
 export function diffZonedAsDuration(value1, value2, unit, options) {
+    // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     const validZonedDateTimes = isValidCalendarZonedDateTime(value1) &&
         isValidCalendarZonedDateTime(value2);
-    const validUnit = isValidDateTimeDurationUnit(unit);
+    // Singular names resolve to their plural (Temporal §13.17).
+    const resolvedUnit = resolveDurationUnit(unit);
+    const validUnit = isValidDateTimeDurationUnit(resolvedUnit);
     if (!validZonedDateTimes || !validUnit) {
         return "";
     }
     try {
-        // Calendar resolution before UTC normalization, and the normalization preserves the calendar
-        // — see `diffZoned`'s equivalent comment.
         const { a, b } = parseCalendarZonedPairForArithmetic(value1, value2);
-        const normalizedZdt1 = a.withTimeZone("UTC");
-        const normalizedZdt2 = b.withTimeZone("UTC");
-        return durationUntilString(normalizedZdt1, normalizedZdt2, unit, options);
+        if (isCalendarDifferenceAcrossZones(a, b, resolvedUnit)) {
+            return "";
+        }
+        return durationUntilString(a, b, resolvedUnit, options);
     }
     catch {
         return "";

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

@@ -1,25 +1,25 @@
-import type { Disambiguation, FractionalDigit, Offset } from "../../types/index.js";
+import type { FractionalDigit } from "../../types/index.js";
 /**
  * Return the end of the quarter for a given zoned ISO datetime.
  *
  * - Calculates which quarter (1-4) the date falls into and returns the last moment of that quarter.
- * - `disambiguation` controls DST gap/overlap resolution when a quarter boundary lands on an ambiguous local time: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
- * - `offset` controls whether the source's existing UTC offset is kept when computing a new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** in the (rare) common-zone case since quarter boundaries don't fall on DST transitions), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect where a quarter boundary does coincide with a transition), or "reject" (throws if the source offset is invalid for the new fields, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
- * - `fractionalSecondDigits` controls how many fractional seconds are included in the output: 0 (default — no fractional seconds), 3 (milliseconds), 6 (microseconds), or 9 (nanoseconds).
+ * - Returns one nanosecond before the next local quarter starts in `value`'s own zone (see `floorToZone`), so the result is never before `value`: a quarter whose last local hour repeats (`Africa/Cairo`, 2010-09-30) ends with the second pass.
+ * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - Validation is performed on the input.
+ * - **Compatibility:** before 1.16.0 the default printed no fractional digits, which wrote a moment
+ *   earlier than the end. Pass `{ fractionalSecondDigits: 0 }` to keep the previous string.
  *
  * @param value ISO ZonedDateTime string
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore"), fractionalSecondDigits (0 | 3 | 6 | 9, default 0)
+ * @param optionsArg optional: fractionalSecondDigits (0 | 3 | 6 | 9, default 9)
  * @returns ISO ZonedDateTime string for the end of the quarter, or "" on invalid input
  *
- * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // "2024-03-31T23:59:59+00:00[UTC]"
- * @example endOfQuarterForZoned("2024-05-10T10:00:00+00:00[UTC]") // "2024-06-30T23:59:59+00:00[UTC]"
- * @example endOfQuarterForZoned("2024-11-20T08:00:00+00:00[UTC]") // "2024-12-31T23:59:59+00:00[UTC]"
- * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]", { fractionalSecondDigits: 9 }) // "2024-03-31T23:59:59.999999999+00:00[UTC]"
+ * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // "2024-03-31T23:59:59.999999999+00:00[UTC]"
+ * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]", { fractionalSecondDigits: 0 }) // "2024-03-31T23:59:59+00:00[UTC]" — the pre-1.16.0 string
+ * @example endOfQuarterForZoned("2024-05-10T10:00:00+00:00[UTC]") // "2024-06-30T23:59:59.999999999+00:00[UTC]"
+ * @example endOfQuarterForZoned("2024-11-20T08:00:00+00:00[UTC]") // "2024-12-31T23:59:59.999999999+00:00[UTC]"
+ * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]", { fractionalSecondDigits: 3 }) // "2024-03-31T23:59:59.999+00:00[UTC]"
  * @example endOfQuarterForZoned("invalid") // ""
  */
 export declare function endOfQuarterForZoned(value: string, optionsArg?: {
-    disambiguation?: Disambiguation;
-    offset?: Offset;
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/zoned/calculate/endOfQuarterForZoned.js

@@ -1,50 +1,51 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { zonedDateTimeFrom, zonedUnitEnd } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the end of the quarter for a given zoned ISO datetime.
  *
  * - Calculates which quarter (1-4) the date falls into and returns the last moment of that quarter.
- * - `disambiguation` controls DST gap/overlap resolution when a quarter boundary lands on an ambiguous local time: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
- * - `offset` controls whether the source's existing UTC offset is kept when computing a new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** in the (rare) common-zone case since quarter boundaries don't fall on DST transitions), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect where a quarter boundary does coincide with a transition), or "reject" (throws if the source offset is invalid for the new fields, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
- * - `fractionalSecondDigits` controls how many fractional seconds are included in the output: 0 (default — no fractional seconds), 3 (milliseconds), 6 (microseconds), or 9 (nanoseconds).
+ * - Returns one nanosecond before the next local quarter starts in `value`'s own zone (see `floorToZone`), so the result is never before `value`: a quarter whose last local hour repeats (`Africa/Cairo`, 2010-09-30) ends with the second pass.
+ * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - Validation is performed on the input.
+ * - **Compatibility:** before 1.16.0 the default printed no fractional digits, which wrote a moment
+ *   earlier than the end. Pass `{ fractionalSecondDigits: 0 }` to keep the previous string.
  *
  * @param value ISO ZonedDateTime string
- * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore"), fractionalSecondDigits (0 | 3 | 6 | 9, default 0)
+ * @param optionsArg optional: fractionalSecondDigits (0 | 3 | 6 | 9, default 9)
  * @returns ISO ZonedDateTime string for the end of the quarter, or "" on invalid input
  *
- * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // "2024-03-31T23:59:59+00:00[UTC]"
- * @example endOfQuarterForZoned("2024-05-10T10:00:00+00:00[UTC]") // "2024-06-30T23:59:59+00:00[UTC]"
- * @example endOfQuarterForZoned("2024-11-20T08:00:00+00:00[UTC]") // "2024-12-31T23:59:59+00:00[UTC]"
- * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]", { fractionalSecondDigits: 9 }) // "2024-03-31T23:59:59.999999999+00:00[UTC]"
+ * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // "2024-03-31T23:59:59.999999999+00:00[UTC]"
+ * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]", { fractionalSecondDigits: 0 }) // "2024-03-31T23:59:59+00:00[UTC]" — the pre-1.16.0 string
+ * @example endOfQuarterForZoned("2024-05-10T10:00:00+00:00[UTC]") // "2024-06-30T23:59:59.999999999+00:00[UTC]"
+ * @example endOfQuarterForZoned("2024-11-20T08:00:00+00:00[UTC]") // "2024-12-31T23:59:59.999999999+00:00[UTC]"
+ * @example endOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]", { fractionalSecondDigits: 3 }) // "2024-03-31T23:59:59.999+00:00[UTC]"
  * @example endOfQuarterForZoned("invalid") // ""
  */
 export function endOfQuarterForZoned(value, optionsArg) {
-    if (!isValidZonedDateTime(value)) {
-        return "";
-    }
-    const disambiguation = optionsArg?.disambiguation ?? "compatible";
-    const offset = optionsArg?.offset ?? "ignore";
-    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits ?? 0;
     try {
-        const zdt = Temporal.ZonedDateTime.from(value);
-        const month = zdt.month;
-        const quarterEndMonth = Math.floor((month - 1) / 3) * 3 + 3;
-        const quarterStart = zdt.with({ month: quarterEndMonth, day: 1, hour: 0, minute: 0, second: 0 }, { disambiguation, offset });
-        const nextQuarterStart = quarterStart.add({ months: 1 });
-        const lastDayOfQuarter = nextQuarterStart.subtract({ days: 1 });
-        return lastDayOfQuarter
-            .with({
-            hour: 23,
-            minute: 59,
-            second: 59,
-            millisecond: 999,
-            microsecond: 999,
-            nanosecond: 999,
-        }, { disambiguation, offset })
-            .toString({ fractionalSecondDigits });
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        if (!isValidZonedDateTime(value)) {
+            return "";
+        }
+        // An end is next start − 1 ns, so it defaults to nanosecond precision: fewer digits would
+        // print an earlier instant than the end (Calendar & zone semantics §3).
+        const fractionalSecondDigits = optionsArg?.fractionalSecondDigits === undefined
+            ? 9
+            : optionsArg.fractionalSecondDigits;
+        try {
+            const end = zonedUnitEnd(zonedDateTimeFrom(value), "quarter");
+            return end ? end.toString({ fractionalSecondDigits }) : "";
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,28 +1,35 @@
-import { Temporal } from "@js-temporal/polyfill";
-import type { Disambiguation, FractionalDigit, Offset } from "../../types/index.js";
+import type { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeUnit, FractionalDigit } from "../../types/index.js";
 /**
  * Return the end of the specified date-time `unit` for a given zoned ISO 8601 datetime string.
  *
- * - Converts to ZonedDateTime, sets to end of unit, converts back to string.
- * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
- * - `disambiguation` controls DST gap/overlap resolution when the boundary jump lands on an ambiguous local time: "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in "").
- * - `offset` controls whether the source's existing UTC offset is kept when computing the new boundary: "prefer" (Temporal's own default — keeps the source offset whenever still valid, which **makes `disambiguation` inert** for almost every case here since the source offset is nearly always still valid after a same-day field reset), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset; this is what makes `disambiguation` actually take effect), or "reject" (throws if the source offset is invalid for the new fields, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Supports: "year", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", each also in its plural form (`"days"`), as Temporal accepts.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
+ * - Returns the last instant of the real local `unit` containing `value` in its own zone — one nanosecond before the next bucket `floorToZone` would return — so the result is never before `value`. The second pass of New York's repeated fall-back hour ends at 01:59:59.999999999 −05:00, and `Australia/Lord_Howe`'s 90-minute fall-back hour ends in its new offset.
+ * - A transition that reopens the previous local date makes that stretch its own bucket: `America/Goose_Bay`'s 00:01 fall-back on 7 November 2010 re-entered 6 November for 59 minutes, so the day holding `2010-11-06T23:30:00-04:00` ends at 23:59:59.999999999 −04:00.
+ * - A midnight repeated on the same date stays one day: `America/Havana`'s 25-hour 2024-11-03 ends at 23:59:59.999999999 −05:00 from either pass of its repeated first hour.
+ * - Takes no `disambiguation` or `offset`: a boundary is always a real instant, as TC39's `startOfDay()`
+ *   takes neither. Those ignored options were removed in 1.16.0.
+ * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - Returns "" for invalid input.
+ * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
+ *   `second` and coarser, 3 for `millisecond`, 6 for `microsecond` — which wrote a moment earlier
+ *   than the end. Pass that `fractionalSecondDigits` to keep the previous string.
  *
  * @param value zoned ISO 8601 datetime string
- * @param unit Temporal.DateUnit|Temporal.TimeUnit to specify the unit for the end
- * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @param unit date or time unit, singular or plural, to specify the unit for the end
+ * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
  * @returns zoned ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-29T23:59:59.999999999+00:00[UTC]"
+ * @example endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month", { fractionalSecondDigits: 0 }) // "2024-02-29T23:59:59+00:00[UTC]" — the pre-1.16.0 string
+ * @example endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month", { fractionalSecondDigits: 3 }) // "2024-02-29T23:59:59.999+00:00[UTC]"
+ * @example endOfZoned("2024-02-29T12:34:56+01:00[Europe/Berlin]", "hours") // "2024-02-29T12:59:59.999999999+01:00[Europe/Berlin]"
  * @example endOfZoned("invalid", "month") // ""
- * @example endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour", { disambiguation: "earlier" }) // "2024-11-03T01:59:59-04:00[America/New_York]" (source sits in the second, repeated 1am of the fall-back overlap; "earlier" resolves end-of-hour to the first (EDT) pass)
- * @example endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour", { disambiguation: "reject" }) // "" (same overlap; "reject" throws because end-of-hour is ambiguous between the two 1am instants)
- * @example endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour", { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:59:59-05:00[America/New_York]" (setting offset to "prefer" makes disambiguation inert here — the source's -05:00 offset is still valid for 1am, so it's kept and "reject" never fires)
+ * @example endOfZoned("2024-11-03T01:15:00-05:00[America/New_York]", "hour") // "2024-11-03T01:59:59.999999999-05:00[America/New_York]" (the second, repeated 1am is its own hour)
+ * @example endOfZoned("2024-11-03T00:30:00-04:00[America/Havana]", "day") // "2024-11-03T23:59:59.999999999-05:00[America/Havana]" (midnight repeated on the same date: one 25-hour day)
  */
-export declare function endOfZoned(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, optionsArg?: {
+export declare function endOfZoned(value: string, unit: Temporal.SmallestUnit<DateTimeUnit>, optionsArg?: {
     weekStartsOn?: "monday" | "sunday";
     fractionalSecondDigits?: FractionalDigit;
-    disambiguation?: Disambiguation;
-    offset?: Offset;
 }): string;