@northguild/gmt 1.15.0 → 1.17.0

package/dist/zoned/calculate/startOfQuarterForZoned.js

@@ -1,16 +1,16 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { zonedDateTimeFrom, zonedUnitStart } from "../../internal/index.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the start of the quarter for a given zoned ISO datetime.
  *
- * - Calculates which quarter (1-4) the date falls into and returns the first day of that quarter.
- * - `disambiguation` controls DST gap/overlap resolution when the quarter-start 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 the 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.
+ * - Calculates which quarter (1-4) the date falls into and returns the first instant of that quarter, with every field below the day reset — milliseconds, microseconds and nanoseconds included.
+ * - Returns the real start of the local quarter in `value`'s own zone (see `floorToZone`), so the result is never after `value`: a skipped first midnight starts at the quarter's first real instant, and a repeated one (`Africa/Tunis`, 1978-10-01) at its first pass.
  * - `fractionalSecondDigits` controls how many fractional seconds are included in the output: 0 (default — no fractional seconds), 3 (milliseconds), 6 (microseconds), or 9 (nanoseconds).
  * - Validation is performed on the input.
  *
  * @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 0)
  * @returns ISO ZonedDateTime string for the start of the quarter, or "" on invalid input
  *
  * @example startOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]") // "2024-01-01T00:00:00+00:00[UTC]"
@@ -20,21 +20,27 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * @example startOfQuarterForZoned("invalid") // ""
  */
 export function startOfQuarterForZoned(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 quarterStartMonth = Math.floor((month - 1) / 3) * 3 + 1;
-        return zdt
-            .with({ month: quarterStartMonth, day: 1, hour: 0, minute: 0, second: 0 }, { disambiguation, offset })
-            .toString({ fractionalSecondDigits });
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        if (!isValidZonedDateTime(value)) {
+            return "";
+        }
+        const fractionalSecondDigits = optionsArg?.fractionalSecondDigits === undefined
+            ? 0
+            : optionsArg.fractionalSecondDigits;
+        try {
+            const start = zonedUnitStart(zonedDateTimeFrom(value), "quarter");
+            return start ? start.toString({ fractionalSecondDigits }) : "";
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,27 +1,31 @@
-import type { DateTimeUnit, Disambiguation, FractionalDigit, Offset } from "../../types/index.js";
+import type { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeUnit, FractionalDigit } from "../../types/index.js";
 /**
  * Return the start of the specified date-time `unit` for a given zoned ISO 8601 datetime string.
  *
- * - Converts to ZonedDateTime, sets to start 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 real start of the local `unit` containing `value` in its own zone — the same bucket `floorToZone` uses — so the result is never after `value`. A local hour `Pacific/Chatham`'s spring-forward leaves only 15 minutes long starts at 03:45, the second pass of New York's repeated fall-back hour starts at its own 01:00 (−05:00), and a day whose midnight was skipped starts at its first real instant.
+ * - A transition that reopens the previous local date makes that stretch its own bucket. `America/Goose_Bay` fell back at 00:01 on 7 November 2010, re-entering 6 November for 59 minutes, so `2010-11-06T23:30:00-04:00` has a day that starts at 23:01 — consistent with `floorToZone`, `bucketRange` and `intervalCountZoned`.
+ * - A midnight repeated on the same date stays one day: `America/Havana`'s 2024-11-03 starts at its first 00:00 (−04:00) and runs 25 hours, matching Temporal's `startOfDay()`.
+ * - 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.
+ * - `fractionalSecondDigits` defaults to 3, 6 or 9 for "millisecond", "microsecond" or "nanosecond", and 0 otherwise.
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
- * @param unit Temporal.DateUnit|Temporal.TimeUnit to specify the unit for the start
- * @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 start
+ * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
  * @returns zoned ISO 8601 string representing the start of the specified unit, or "" on invalid input
  *
  * @example startOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-01T00:00:00+00:00[UTC]"
+ * @example startOfZoned("2024-02-29T12:34:56.789+01:00[Europe/Berlin]", "milliseconds") // "2024-02-29T12:34:56.789+01:00[Europe/Berlin]"
  * @example startOfZoned("invalid", "month") // ""
- * @example startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour", { disambiguation: "earlier" }) // "2024-11-03T01:00:00-04:00[America/New_York]" (source sits in the second, repeated 1am of the fall-back overlap; "earlier" resolves start-of-hour to the first (EDT) pass)
- * @example startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour", { disambiguation: "reject" }) // "" (same overlap; "reject" throws because start-of-hour is ambiguous between the two 1am instants)
- * @example startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour", { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:00:00-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 startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour") // "2024-11-03T01:00:00-05:00[America/New_York]" (the second, repeated 1am is its own hour)
+ * @example startOfZoned("2024-09-29T03:50:00+13:45[Pacific/Chatham]", "hour") // "2024-09-29T03:45:00+13:45[Pacific/Chatham]" (local 03:00 never happened; the hour began at the jump)
+ * @example startOfZoned("2024-11-03T00:30:00-05:00[America/Havana]", "day") // "2024-11-03T00:00:00-04:00[America/Havana]" (midnight repeated on the same date: one 25-hour day)
  */
-export declare function startOfZoned(value: string, unit: DateTimeUnit, optionsArg?: {
+export declare function startOfZoned(value: string, unit: Temporal.SmallestUnit<DateTimeUnit>, optionsArg?: {
     weekStartsOn?: "monday" | "sunday";
     fractionalSecondDigits?: FractionalDigit;
-    disambiguation?: Disambiguation;
-    offset?: Offset;
 }): string;

package/dist/zoned/calculate/startOfZoned.js

@@ -1,122 +1,40 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidDateTimeUnit } from "../../plain/validate/index.js";
-import { isValidZonedDateTime } from "../validate/index.js";
+import { startOrEndOfZoned } from "../../internal/startOrEndOfZoned.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the start of the specified date-time `unit` for a given zoned ISO 8601 datetime string.
  *
- * - Converts to ZonedDateTime, sets to start 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 real start of the local `unit` containing `value` in its own zone — the same bucket `floorToZone` uses — so the result is never after `value`. A local hour `Pacific/Chatham`'s spring-forward leaves only 15 minutes long starts at 03:45, the second pass of New York's repeated fall-back hour starts at its own 01:00 (−05:00), and a day whose midnight was skipped starts at its first real instant.
+ * - A transition that reopens the previous local date makes that stretch its own bucket. `America/Goose_Bay` fell back at 00:01 on 7 November 2010, re-entering 6 November for 59 minutes, so `2010-11-06T23:30:00-04:00` has a day that starts at 23:01 — consistent with `floorToZone`, `bucketRange` and `intervalCountZoned`.
+ * - A midnight repeated on the same date stays one day: `America/Havana`'s 2024-11-03 starts at its first 00:00 (−04:00) and runs 25 hours, matching Temporal's `startOfDay()`.
+ * - 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.
+ * - `fractionalSecondDigits` defaults to 3, 6 or 9 for "millisecond", "microsecond" or "nanosecond", and 0 otherwise.
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
- * @param unit Temporal.DateUnit|Temporal.TimeUnit to specify the unit for the start
- * @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 start
+ * @param options optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
  * @returns zoned ISO 8601 string representing the start of the specified unit, or "" on invalid input
  *
  * @example startOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-01T00:00:00+00:00[UTC]"
+ * @example startOfZoned("2024-02-29T12:34:56.789+01:00[Europe/Berlin]", "milliseconds") // "2024-02-29T12:34:56.789+01:00[Europe/Berlin]"
  * @example startOfZoned("invalid", "month") // ""
- * @example startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour", { disambiguation: "earlier" }) // "2024-11-03T01:00:00-04:00[America/New_York]" (source sits in the second, repeated 1am of the fall-back overlap; "earlier" resolves start-of-hour to the first (EDT) pass)
- * @example startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour", { disambiguation: "reject" }) // "" (same overlap; "reject" throws because start-of-hour is ambiguous between the two 1am instants)
- * @example startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour", { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:00:00-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 startOfZoned("2024-11-03T01:45:00-05:00[America/New_York]", "hour") // "2024-11-03T01:00:00-05:00[America/New_York]" (the second, repeated 1am is its own hour)
+ * @example startOfZoned("2024-09-29T03:50:00+13:45[Pacific/Chatham]", "hour") // "2024-09-29T03:45:00+13:45[Pacific/Chatham]" (local 03:00 never happened; the hour began at the jump)
+ * @example startOfZoned("2024-11-03T00:30:00-05:00[America/Havana]", "day") // "2024-11-03T00:00:00-04:00[America/Havana]" (midnight repeated on the same date: one 25-hour day)
  */
 export function startOfZoned(value, unit, optionsArg) {
-    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
-    const fractionalSecondDigits = optionsArg?.fractionalSecondDigits;
-    const disambiguation = optionsArg?.disambiguation ?? "compatible";
-    const offset = optionsArg?.offset ?? "ignore";
-    if (!isValidZonedDateTime(value) || !isValidDateTimeUnit(unit))
-        return "";
     try {
-        const source = Temporal.ZonedDateTime.from(value);
-        let result;
-        switch (unit) {
-            case "year":
-                result = source.with({
-                    month: 1,
-                    day: 1,
-                    hour: 0,
-                    minute: 0,
-                    second: 0,
-                    millisecond: 0,
-                    microsecond: 0,
-                    nanosecond: 0,
-                }, { disambiguation, offset });
-                break;
-            case "month":
-                result = source.with({
-                    day: 1,
-                    hour: 0,
-                    minute: 0,
-                    second: 0,
-                    millisecond: 0,
-                    microsecond: 0,
-                    nanosecond: 0,
-                }, { disambiguation, offset });
-                break;
-            case "week": {
-                const daysToSubtract = weekStartsOn === "monday"
-                    ? source.dayOfWeek - 1
-                    : source.dayOfWeek % 7;
-                const startOfWeekDate = source.subtract({ days: daysToSubtract });
-                result = startOfWeekDate.with({
-                    hour: 0,
-                    minute: 0,
-                    second: 0,
-                    millisecond: 0,
-                    microsecond: 0,
-                    nanosecond: 0,
-                }, { disambiguation, offset });
-                break;
-            }
-            case "day":
-                result = source.with({
-                    hour: 0,
-                    minute: 0,
-                    second: 0,
-                    millisecond: 0,
-                    microsecond: 0,
-                    nanosecond: 0,
-                }, { disambiguation, offset });
-                break;
-            case "hour":
-                result = source.with({
-                    minute: 0,
-                    second: 0,
-                    millisecond: 0,
-                    microsecond: 0,
-                    nanosecond: 0,
-                }, { disambiguation, offset });
-                break;
-            case "minute":
-                result = source.with({ second: 0, millisecond: 0, microsecond: 0, nanosecond: 0 }, { disambiguation, offset });
-                break;
-            case "second":
-                result = source.with({ millisecond: 0, microsecond: 0, nanosecond: 0 }, { disambiguation, offset });
-                break;
-            case "millisecond":
-                result = source.with({ microsecond: 0, nanosecond: 0 }, { disambiguation, offset });
-                break;
-            case "microsecond":
-                result = source.with({ nanosecond: 0 }, { disambiguation, offset });
-                break;
-            case "nanosecond":
-                result = source; // Smallest unit, nothing to reset
-                break;
-            default:
-                return "";
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
         }
-        // Handle default precision: 0 for > sec, 3 for ms, 6 for µs, 9 for ns
-        const precisionMap = {
-            millisecond: 3,
-            microsecond: 6,
-            nanosecond: 9,
-        };
-        const fractionalDigits = fractionalSecondDigits ?? (precisionMap[unit] || 0);
-        return result.toString({ fractionalSecondDigits: fractionalDigits });
+        return startOrEndOfZoned(value, unit, optionsArg ?? {}, false);
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,47 +1,59 @@
-import type { DateTimeDurationUnit, Disambiguation, Offset, Overflow } from "../../types/index.js";
+import type { DateTimeDurationUnit, Disambiguation, Overflow } from "../../types/index.js";
 /**
  * Subtract a temporal amount from a zoned ISO 8601 datetime string and return a zoned ISO 8601 string.
  *
  * - Uses Temporal.ZonedDateTime.subtract to subtract duration.
  * - Validates duration units and values.
- * - Accepts a GMT calendar-annotated zoned string (as produced by `convertZonedToCalendar`, e.g.
- *   `"5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]"`), not just a bare ISO string —
- *   E7 (issue #152). Calendar-unit arithmetic ("subtract 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. 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 `convertZonedToCalendar` writes it,
+ *   e.g. `"2024-03-25T14:30:00-04:00[America/New_York][u-ca=hebrew]"`), not just a bare ISO string
+ *   (E7, issue #152). Calendar-unit arithmetic ("subtract 1 month") resolves against that calendar
+ *   **and** the DST rules of the zone, in one operation; 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 subtracted 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 `2024-11-03T01:30:00-05:00[America/New_York]` with
+ *   "earlier" returned `01:20:00-04:00`, 70 minutes before the input in exact time, instead of
+ *   `01:20:00-05:00`). 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. subtracting
  *   1 month from Mar 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 subtract
- * @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 subtractZoned("2024-03-10T12:00:00-04:00[America/New_York]", { days: 5 }) // "2024-03-05T12:00:00-05:00[America/New_York]"
  * @example subtractZoned("invalid", { days: 5 }) // ""
  * @example subtractZoned("2024-11-04T01:30:00-05: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 subtractZoned("2024-11-04T01:30:00-05:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "" (fall-back overlap rejected)
- * @example subtractZoned("2024-03-11T03:30:00-04: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 subtractZoned("2024-03-11T02:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "earlier" }) // "2024-03-10T01:30:00-05:00[America/New_York]" (02:30 on 10 March is in the spring-forward gap; "earlier" moves it back an hour, "compatible" forward to 03:30-04:00)
+ * @example subtractZoned("2024-03-11T02:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "" (spring-forward gap rejected)
+ * @example subtractZoned("2024-11-03T01:50: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(subtractZoned("2024-11-03T01:50: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 subtractZoned("2024-03-31T12:00:00-04:00[America/New_York]", { months: 1 }, { overflow: "reject" }) // ""
- * @example subtractZoned("5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]", { months: 1 }) // "5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]" (Adar -> Adar I, EDT -> EST in one call)
- * @example subtractZoned("0001-05-01T12:00:00+09:00[u-ca=japanese;era=reiwa][Asia/Tokyo]", { days: 1 }) // "0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]" (era re-derived, not copied)
- * @example subtractZoned("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 subtractZoned("2024-03-25T14:30:00-04:00[America/New_York][u-ca=hebrew]", { months: 1 }) // "2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]" (Adar II -> Adar I, EDT -> EST in one call)
+ * @example subtractZoned("2019-05-01T12:00:00+09:00[Asia/Tokyo][u-ca=japanese]", { days: 1 }) // "2019-04-30T12:00:00+09:00[Asia/Tokyo][u-ca=japanese]" (Reiwa 1 -> Heisei 31)
+ * @example subtractZoned("2024-03-10T14:30:00-04:00[u-ca=hebrew][America/New_York]", { days: 1 }) // "" (calendar before zone is not RFC 9557)
  */
 export declare function subtractZoned(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, optionsArg?: {
     disambiguation?: Disambiguation;
-    offset?: Offset;
     overflow?: Overflow;
 }): string;

package/dist/zoned/calculate/subtractZoned.js

@@ -1,82 +1,98 @@
-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";
 /**
  * Subtract a temporal amount from a zoned ISO 8601 datetime string and return a zoned ISO 8601 string.
  *
  * - Uses Temporal.ZonedDateTime.subtract to subtract duration.
  * - Validates duration units and values.
- * - Accepts a GMT calendar-annotated zoned string (as produced by `convertZonedToCalendar`, e.g.
- *   `"5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]"`), not just a bare ISO string —
- *   E7 (issue #152). Calendar-unit arithmetic ("subtract 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. 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 `convertZonedToCalendar` writes it,
+ *   e.g. `"2024-03-25T14:30:00-04:00[America/New_York][u-ca=hebrew]"`), not just a bare ISO string
+ *   (E7, issue #152). Calendar-unit arithmetic ("subtract 1 month") resolves against that calendar
+ *   **and** the DST rules of the zone, in one operation; 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 subtracted 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 `2024-11-03T01:30:00-05:00[America/New_York]` with
+ *   "earlier" returned `01:20:00-04:00`, 70 minutes before the input in exact time, instead of
+ *   `01:20:00-05:00`). 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. subtracting
  *   1 month from Mar 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 subtract
- * @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 subtractZoned("2024-03-10T12:00:00-04:00[America/New_York]", { days: 5 }) // "2024-03-05T12:00:00-05:00[America/New_York]"
  * @example subtractZoned("invalid", { days: 5 }) // ""
  * @example subtractZoned("2024-11-04T01:30:00-05: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 subtractZoned("2024-11-04T01:30:00-05:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "" (fall-back overlap rejected)
- * @example subtractZoned("2024-03-11T03:30:00-04: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 subtractZoned("2024-03-11T02:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "earlier" }) // "2024-03-10T01:30:00-05:00[America/New_York]" (02:30 on 10 March is in the spring-forward gap; "earlier" moves it back an hour, "compatible" forward to 03:30-04:00)
+ * @example subtractZoned("2024-03-11T02:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "" (spring-forward gap rejected)
+ * @example subtractZoned("2024-11-03T01:50: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(subtractZoned("2024-11-03T01:50: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 subtractZoned("2024-03-31T12:00:00-04:00[America/New_York]", { months: 1 }, { overflow: "reject" }) // ""
- * @example subtractZoned("5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]", { months: 1 }) // "5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]" (Adar -> Adar I, EDT -> EST in one call)
- * @example subtractZoned("0001-05-01T12:00:00+09:00[u-ca=japanese;era=reiwa][Asia/Tokyo]", { days: 1 }) // "0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]" (era re-derived, not copied)
- * @example subtractZoned("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 subtractZoned("2024-03-25T14:30:00-04:00[America/New_York][u-ca=hebrew]", { months: 1 }) // "2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]" (Adar II -> Adar I, EDT -> EST in one call)
+ * @example subtractZoned("2019-05-01T12:00:00+09:00[Asia/Tokyo][u-ca=japanese]", { days: 1 }) // "2019-04-30T12:00:00+09:00[Asia/Tokyo][u-ca=japanese]" (Reiwa 1 -> Heisei 31)
+ * @example subtractZoned("2024-03-10T14:30:00-04:00[u-ca=hebrew][America/New_York]", { days: 1 }) // "" (calendar before zone is not RFC 9557)
  */
 export function subtractZoned(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) {
-        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) {
             return "";
         }
-        const zoned = parseCalendarZonedValue(value);
-        const subtracted = zoned.subtract(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 subtracted = addToZonedDisambiguated(zoned, units, -1, {
+                overflow,
+                disambiguation,
+            });
             return formatZonedInCalendar(subtracted, calendar);
         }
-        // The calendar MUST be stripped before this rebuild string is composed (E7 risk R1) — see
-        // `addZoned`'s equivalent comment for the full reasoning. In short: a calendared
-        // `.toPlainDateTime().toString()` already carries Temporal's own `[u-ca=...]` annotation, so
-        // appending `[${timeZoneId}]` produces GMT's forbidden segment ordering and
-        // `Temporal.ZonedDateTime.from` rejects it, silently degrading every non-"compatible"
-        // disambiguation to "".
-        const plainDateTime = subtracted
-            .withCalendar("iso8601")
-            .toPlainDateTime()
-            .toString();
-        const resolved = Temporal.ZonedDateTime.from(`${plainDateTime}[${subtracted.timeZoneId}]`, { disambiguation, offset }).withCalendar(subtracted.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/subtractZonedBusinessDays.d.ts

@@ -2,6 +2,8 @@
  * Return a zoned ISO 8601 datetime string with `amount` business days subtracted from `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 `subtractBusinessDays`, 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/subtractZonedBusinessDays.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 subtracted from `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 `subtractBusinessDays`, 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 subtractZonedBusinessDays(value, amount) {
         return "";
     }
     if (amount === 0) {
-        return value;
+        return adjustZonedBusinessDays(value, 1, 0);
     }
     return adjustZonedBusinessDays(value, -1, Math.abs(amount));
 }

package/dist/zoned/chop/chopZonedDate.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/isValidZonedDateTime.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Extracts the local time portion from an ISO 8601 zoned datetime string.
  *
@@ -16,7 +16,7 @@ export function chopZonedDate(value) {
     if (!isValidZonedDateTime(value))
         return "";
     try {
-        return Temporal.ZonedDateTime.from(value).toPlainTime().toString();
+        return zonedDateTimeFrom(value).toPlainTime().toString();
     }
     catch {
         return "";

package/dist/zoned/chop/chopZonedDateTime.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/isValidZonedDateTime.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Extracts the IANA timeZone identifier from an ISO 8601 zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function chopZonedDateTime(value) {
     if (!validZonedDateTime)
         return "";
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime.timeZoneId;
     }
     catch {