@northguild/gmt 1.14.2

package/dist/zoned/calculate/minZoned.js

@@ -0,0 +1,35 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the earliest (minimum) of the given ZonedDateTime values.
+ *
+ * - Returns null if the array is empty or contains no valid dates.
+ * - Validation is performed on each item in the array.
+ *
+ * @param zonedDateTimes Array of ISO ZonedDateTime strings
+ * @returns The earliest zoned datetime string, or null on invalid input
+ *
+ * @example minZoned(["2024-03-10T12:00:00[America/New_York]", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-10T12:00:00-05:00[America/New_York]"
+ * @example minZoned(["invalid", "2024-03-15T12:00:00[America/New_York]"]) // "2024-03-15T12:00:00-04:00[America/New_York]"
+ * @example minZoned(["invalid", "also invalid"]) // null
+ * @example minZoned([]) // null
+ */
+export function minZoned(zonedDateTimes) {
+    if (!zonedDateTimes.length)
+        return null;
+    const valid = zonedDateTimes.filter(isValidZonedDateTime);
+    if (!valid.length)
+        return null;
+    try {
+        const min = valid.reduce((currentMin, candidateStr) => {
+            const candidate = Temporal.ZonedDateTime.from(candidateStr);
+            return Temporal.ZonedDateTime.compare(candidate, currentMin) < 0
+                ? candidate
+                : currentMin;
+        }, Temporal.ZonedDateTime.from(valid[0]));
+        return min.toString();
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,23 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Round an ISO 8601 zoned datetime string to the specified unit.
+ *
+ * - Returns "" for invalid inputs.
+ * - Accepts "day" and time units: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Date units ("year", "month", "week") are not supported by the Temporal polyfill's ZonedDateTime.round() — they return "".
+ * - Wraps Temporal.ZonedDateTime.round() which throws on invalid options.
+ * - Note: The polyfill's `.round()` does not support `disambiguation` or `offset` options.
+ *
+ * @param value ISO 8601 zoned datetime string
+ * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode
+ * @returns Rounded ISO 8601 zoned datetime string, or "" on invalid input
+ *
+ * @example roundZoned("2024-06-15T12:34:56-05:00[America/New_York]", { smallestUnit: "hour" }) // "2024-06-15T13:00:00-05:00[America/New_York]"
+ * @example roundZoned("2024-06-15T12:34:56-05:00[America/New_York]", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:45:00-05:00[America/New_York]"
+ * @example roundZoned("invalid", { smallestUnit: "hour" }) // ""
+ */
+export declare function roundZoned(value: string, options: {
+    smallestUnit: Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">;
+    roundingIncrement?: number;
+    roundingMode?: Temporal.RoundingMode;
+}): string;

package/dist/zoned/calculate/roundZoned.js

@@ -0,0 +1,55 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Round an ISO 8601 zoned datetime string to the specified unit.
+ *
+ * - Returns "" for invalid inputs.
+ * - Accepts "day" and time units: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond".
+ * - Date units ("year", "month", "week") are not supported by the Temporal polyfill's ZonedDateTime.round() — they return "".
+ * - Wraps Temporal.ZonedDateTime.round() which throws on invalid options.
+ * - Note: The polyfill's `.round()` does not support `disambiguation` or `offset` options.
+ *
+ * @param value ISO 8601 zoned datetime string
+ * @param options Rounding options: smallestUnit, optional roundingIncrement, roundingMode
+ * @returns Rounded ISO 8601 zoned datetime string, or "" on invalid input
+ *
+ * @example roundZoned("2024-06-15T12:34:56-05:00[America/New_York]", { smallestUnit: "hour" }) // "2024-06-15T13:00:00-05:00[America/New_York]"
+ * @example roundZoned("2024-06-15T12:34:56-05:00[America/New_York]", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:45:00-05:00[America/New_York]"
+ * @example roundZoned("invalid", { smallestUnit: "hour" }) // ""
+ */
+export function roundZoned(value, options) {
+    const { smallestUnit, roundingIncrement, roundingMode } = options;
+    if (!isValidZonedDateTime(value))
+        return "";
+    // Polyfill limitation: year/month/week not supported for ZonedDateTime.round()
+    const supportedUnits = [
+        "day",
+        "hour",
+        "minute",
+        "second",
+        "millisecond",
+        "microsecond",
+        "nanosecond",
+    ];
+    if (!supportedUnits.includes(smallestUnit))
+        return "";
+    try {
+        const source = Temporal.ZonedDateTime.from(value);
+        const result = source.round({
+            smallestUnit,
+            roundingIncrement,
+            roundingMode,
+        });
+        // 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 = precisionMap[smallestUnit] || 0;
+        return result.toString({ fractionalSecondDigits: fractionalDigits });
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,39 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, Offset, Overflow } from "../../types/index.js";
+/**
+ * Return a zoned ISO 8601 datetime string with the given `fields` set on `value`.
+ *
+ * - Wraps `Temporal.ZonedDateTime.prototype.with()`, which resolves every supplied field in a
+ *   single atomic overflow pass. This is the safe alternative to composing `addZoned()` calls
+ *   field-by-field, and it is the only construction path that can reproduce
+ *   `startOfZoned`'s disambiguation-plus-offset handling — `addZoned()` has no `offset` control
+ *   equivalent to `.with()`'s, because Temporal's `ZonedDateTime.prototype.add()` doesn't accept
+ *   `disambiguation`/`offset` at all.
+ * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
+ *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
+ *   their current value. An empty object is a no-op. `calendar`, `timeZone`, and `offset` are
+ *   deliberately excluded from `fields` — this function only sets date/time components, never
+ *   the zone or calendar identity, and `offset` is controlled separately via `options.offset`.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
+ *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
+ *   (resulting in "").
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
+ * @param options optional: overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns zoned ISO 8601 string with fields set, or "" on invalid input
+ *
+ * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: 9 }) // "2024-03-10T09:00:00-04:00[America/New_York]"
+ * @example setZoned("2024-01-31T12:00:00-05:00[America/New_York]", { month: 2 }) // "2024-02-29T12:00:00-05:00[America/New_York]" (constrain clamps to the last valid day)
+ * @example setZoned("2024-01-31T12:00:00-05:00[America/New_York]", { month: 2 }, { overflow: "reject" }) // ""
+ * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", {}) // "2024-03-10T12:00:00-04:00[America/New_York]" (empty fields object is a no-op)
+ * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "" (offset defaults to "ignore", so disambiguation actually fires and "reject" throws on this fall-back overlap)
+ * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset:"prefer" makes disambiguation inert here — the source's -05:00 offset is still valid, so it's kept and "reject" never fires)
+ * @example setZoned("invalid", { hour: 9 }) // ""
+ */
+export declare function setZoned(value: string, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: {
+    overflow?: Overflow;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): string;

package/dist/zoned/calculate/setZoned.js

@@ -0,0 +1,56 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveOverflow } from "../../internal/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return a zoned ISO 8601 datetime string with the given `fields` set on `value`.
+ *
+ * - Wraps `Temporal.ZonedDateTime.prototype.with()`, which resolves every supplied field in a
+ *   single atomic overflow pass. This is the safe alternative to composing `addZoned()` calls
+ *   field-by-field, and it is the only construction path that can reproduce
+ *   `startOfZoned`'s disambiguation-plus-offset handling — `addZoned()` has no `offset` control
+ *   equivalent to `.with()`'s, because Temporal's `ZonedDateTime.prototype.add()` doesn't accept
+ *   `disambiguation`/`offset` at all.
+ * - `fields` may set any of `year`, `month`, `monthCode`, `day`, `hour`, `minute`, `second`,
+ *   `millisecond`, `microsecond`, `nanosecond`, `era`, and/or `eraYear`; omitted fields keep
+ *   their current value. An empty object is a no-op. `calendar`, `timeZone`, and `offset` are
+ *   deliberately excluded from `fields` — this function only sets date/time components, never
+ *   the zone or calendar identity, and `offset` is controlled separately via `options.offset`.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. setting
+ *   `month: 2` on a value whose `day` is 31: "constrain" clamps to Feb 29/28, "reject" throws
+ *   (resulting in "").
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param fields Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set
+ * @param options optional: overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns zoned ISO 8601 string with fields set, or "" on invalid input
+ *
+ * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: 9 }) // "2024-03-10T09:00:00-04:00[America/New_York]"
+ * @example setZoned("2024-01-31T12:00:00-05:00[America/New_York]", { month: 2 }) // "2024-02-29T12:00:00-05:00[America/New_York]" (constrain clamps to the last valid day)
+ * @example setZoned("2024-01-31T12:00:00-05:00[America/New_York]", { month: 2 }, { overflow: "reject" }) // ""
+ * @example setZoned("2024-03-10T12:00:00-04:00[America/New_York]", {}) // "2024-03-10T12:00:00-04:00[America/New_York]" (empty fields object is a no-op)
+ * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "" (offset defaults to "ignore", so disambiguation actually fires and "reject" throws on this fall-back overlap)
+ * @example setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset:"prefer" makes disambiguation inert here — the source's -05:00 offset is still valid, so it's kept and "reject" never fires)
+ * @example setZoned("invalid", { hour: 9 }) // ""
+ */
+export function setZoned(value, fields, options) {
+    if (!isValidZonedDateTime(value))
+        return "";
+    const overflow = resolveOverflow(options?.overflow);
+    const disambiguation = options?.disambiguation ?? "compatible";
+    // "ignore" (not Temporal's own "prefer" default) so `disambiguation` actually takes effect —
+    // see C3 / docs/dst-disambiguation.md: with "prefer", the source's still-valid offset is kept
+    // and disambiguation is silently never consulted.
+    const offset = options?.offset ?? "ignore";
+    try {
+        const zoned = Temporal.ZonedDateTime.from(value);
+        // Temporal.ZonedDateTime.prototype.with() throws on an empty fields object ("no supported
+        // properties found") rather than treating it as a no-op, so short-circuit here.
+        if (Object.keys(fields).length === 0)
+            return zoned.toString();
+        return zoned.with(fields, { overflow, disambiguation, offset }).toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Sort an array of ZonedDateTime values in ascending or descending order.
+ *
+ * - Invalid dates are filtered out.
+ * - Defaults to ascending order (earliest first).
+ * - Returns empty array if no valid dates.
+ *
+ * @param zonedDateTimes Array of ISO ZonedDateTime strings
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of zoned datetime strings
+ *
+ * @example sortZoned(["2024-03-10T12:00:00[America/New_York]", "2024-01-01T08:00:00[America/New_York]", "2024-02-15T15:30:00[America/New_York]"]) // ["2024-01-01T08:00:00-05:00[America/New_York]", "2024-02-15T15:30:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]"]
+ * @example sortZoned(["2024-03-10T12:00:00[America/New_York]", "2024-01-01T08:00:00[America/New_York]", "2024-02-15T15:30:00[America/New_York]"], "desc") // ["2024-03-10T12:00:00-04:00[America/New_York]", "2024-02-15T15:30:00-05:00[America/New_York]", "2024-01-01T08:00:00-05:00[America/New_York]"]
+ * @example sortZoned(["invalid", "2024-01-01T08:00:00[America/New_York]", "2024-02-15T15:30:00[America/New_York]"]) // ["2024-01-01T08:00:00-05:00[America/New_York]", "2024-02-15T15:30:00-05:00[America/New_York]"]
+ * @example sortZoned([]) // []
+ */
+export declare function sortZoned(zonedDateTimes: string[], order?: "asc" | "desc"): string[];

package/dist/zoned/calculate/sortZoned.js

@@ -0,0 +1,36 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Sort an array of ZonedDateTime values in ascending or descending order.
+ *
+ * - Invalid dates are filtered out.
+ * - Defaults to ascending order (earliest first).
+ * - Returns empty array if no valid dates.
+ *
+ * @param zonedDateTimes Array of ISO ZonedDateTime strings
+ * @param order "asc" for ascending (earliest first) | "desc" for descending (latest first)
+ * @returns Sorted array of zoned datetime strings
+ *
+ * @example sortZoned(["2024-03-10T12:00:00[America/New_York]", "2024-01-01T08:00:00[America/New_York]", "2024-02-15T15:30:00[America/New_York]"]) // ["2024-01-01T08:00:00-05:00[America/New_York]", "2024-02-15T15:30:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]"]
+ * @example sortZoned(["2024-03-10T12:00:00[America/New_York]", "2024-01-01T08:00:00[America/New_York]", "2024-02-15T15:30:00[America/New_York]"], "desc") // ["2024-03-10T12:00:00-04:00[America/New_York]", "2024-02-15T15:30:00-05:00[America/New_York]", "2024-01-01T08:00:00-05:00[America/New_York]"]
+ * @example sortZoned(["invalid", "2024-01-01T08:00:00[America/New_York]", "2024-02-15T15:30:00[America/New_York]"]) // ["2024-01-01T08:00:00-05:00[America/New_York]", "2024-02-15T15:30:00-05:00[America/New_York]"]
+ * @example sortZoned([]) // []
+ */
+export function sortZoned(zonedDateTimes, order = "asc") {
+    if (!zonedDateTimes.length)
+        return [];
+    const valid = zonedDateTimes.filter(isValidZonedDateTime);
+    if (!valid.length)
+        return [];
+    try {
+        const comparables = valid.map((d) => Temporal.ZonedDateTime.from(d));
+        comparables.sort(Temporal.ZonedDateTime.compare);
+        if (order === "desc") {
+            return comparables.reverse().map((d) => d.toString());
+        }
+        return comparables.map((d) => d.toString());
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { Disambiguation, FractionalDigit, Offset } from "../../types/index.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.
+ * - `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)
+ * @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]"
+ * @example startOfQuarterForZoned("2024-05-10T10:00:00+00:00[UTC]") // "2024-04-01T00:00:00+00:00[UTC]"
+ * @example startOfQuarterForZoned("2024-11-20T08:00:00+00:00[UTC]") // "2024-10-01T00:00:00+00:00[UTC]"
+ * @example startOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]", { fractionalSecondDigits: 3 }) // "2024-01-01T00:00:00.000+00:00[UTC]"
+ * @example startOfQuarterForZoned("invalid") // ""
+ */
+export declare function startOfQuarterForZoned(value: string, optionsArg?: {
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+    fractionalSecondDigits?: FractionalDigit;
+}): string;

package/dist/zoned/calculate/startOfQuarterForZoned.js

@@ -0,0 +1,40 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.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.
+ * - `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)
+ * @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]"
+ * @example startOfQuarterForZoned("2024-05-10T10:00:00+00:00[UTC]") // "2024-04-01T00:00:00+00:00[UTC]"
+ * @example startOfQuarterForZoned("2024-11-20T08:00:00+00:00[UTC]") // "2024-10-01T00:00:00+00:00[UTC]"
+ * @example startOfQuarterForZoned("2024-02-15T14:30:00+00:00[UTC]", { fractionalSecondDigits: 3 }) // "2024-01-01T00:00:00.000+00:00[UTC]"
+ * @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 });
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { DateTimeUnit, Disambiguation, FractionalDigit, Offset } 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.
+ * - 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")
+ * @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("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)
+ */
+export declare function startOfZoned(value: string, unit: DateTimeUnit, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+    fractionalSecondDigits?: FractionalDigit;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): string;

package/dist/zoned/calculate/startOfZoned.js

@@ -0,0 +1,122 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTimeUnit } from "../../plain/validate/index.js";
+import { isValidZonedDateTime } from "../validate/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.
+ * - 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")
+ * @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("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)
+ */
+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 "";
+        }
+        // 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 });
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,47 @@
+import type { DateTimeDurationUnit, Disambiguation, Offset, 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.
+ * - `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")
+ * @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-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)
+ */
+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

@@ -0,0 +1,82 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarSystemOfZonedValue, formatZonedInCalendar, isValidAmount, parseCalendarZonedValue, resolveOverflow, } from "../../internal/index.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { isValidCalendarZonedDateTime } from "../validate/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.
+ * - `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")
+ * @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-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)
+ */
+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) {
+            return "";
+        }
+        const zoned = parseCalendarZonedValue(value);
+        const subtracted = zoned.subtract(units, { overflow });
+        if (disambiguation === "compatible") {
+            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 "";
+    }
+}