@northguild/gmt 1.14.2

package/dist/zoned/calculate/addZonedBusinessDays.js

@@ -0,0 +1,30 @@
+import { adjustZonedBusinessDays, isValidAmount } from "../../internal/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return a zoned ISO 8601 datetime string with `amount` business days added to `value`.
+ *
+ * - Uses fixed ISO Monday–Friday business days (no locale awareness).
+ * - Saturday and Sunday are skipped during the count.
+ * - Preserves the original time component through the operation.
+ * - Returns "" on invalid input.
+ *
+ * @param value ISO 8601 zoned datetime string
+ * @param amount number of business days to add
+ * @returns Zoned ISO 8601 datetime string after adding business days, or "" on invalid input
+ *
+ * @example addZonedBusinessDays("2024-03-15T14:30:00-04:00[America/New_York]", 1) // "2024-03-18T14:30:00-04:00[America/New_York]"
+ * @example addZonedBusinessDays("2024-03-16T14:30:00-04:00[America/New_York]", 1) // "2024-03-18T14:30:00-04:00[America/New_York]"
+ * @example addZonedBusinessDays("2024-03-15T14:30:00-04:00[America/New_York]", 0) // "2024-03-15T14:30:00-04:00[America/New_York]"
+ * @example addZonedBusinessDays("invalid", 1) // ""
+ */
+export function addZonedBusinessDays(value, amount) {
+    if (!isValidZonedDateTime(value) || !isValidAmount(amount)) {
+        return "";
+    }
+    if (amount === 0) {
+        return value;
+    }
+    const absAmount = Math.abs(amount);
+    const direction = amount > 0 ? 1 : -1;
+    return adjustZonedBusinessDays(value, direction, absAmount);
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Restrict `value` to the range [`min`, `max`] in zoned datetime space.
+ *
+ * - Returns `value` if it falls within the bounds (inclusive on both ends).
+ * - Returns `min` if `value` is before `min`.
+ * - Returns `max` if `value` is after `max`.
+ * - Returns `""` if any input is invalid or `min > max`.
+ *
+ * @param value ISO ZonedDateTime string to clamp
+ * @param min ISO ZonedDateTime string for the lower bound (inclusive)
+ * @param max ISO ZonedDateTime string for the upper bound (inclusive)
+ * @returns The clamped zoned datetime string, or "" on invalid input
+ *
+ * @example clampZoned("2024-03-15T12:00:00+00:00[UTC]", "2024-03-01T00:00:00+00:00[UTC]", "2024-03-31T23:59:59+00:00[UTC]") // "2024-03-15T12:00:00+00:00[UTC]"
+ * @example clampZoned("2024-02-01T12:00:00+00:00[UTC]", "2024-03-01T00:00:00+00:00[UTC]", "2024-03-31T23:59:59+00:00[UTC]") // "2024-03-01T00:00:00+00:00[UTC]"
+ * @example clampZoned("2024-05-01T12:00:00+00:00[UTC]", "2024-03-01T00:00:00+00:00[UTC]", "2024-03-31T23:59:59+00:00[UTC]") // "2024-03-31T23:59:59+00:00[UTC]"
+ * @example clampZoned("2024-03-15T12:00:00+00:00[UTC]", "2024-03-31T00:00:00+00:00[UTC]", "2024-03-01T00:00:00+00:00[UTC]") // ""
+ * @example clampZoned("invalid", "2024-03-01T00:00:00+00:00[UTC]", "2024-03-31T23:59:59+00:00[UTC]") // ""
+ */
+export declare function clampZoned(value: string, min: string, max: string): string;

package/dist/zoned/calculate/clampZoned.js

@@ -0,0 +1,48 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Restrict `value` to the range [`min`, `max`] in zoned datetime space.
+ *
+ * - Returns `value` if it falls within the bounds (inclusive on both ends).
+ * - Returns `min` if `value` is before `min`.
+ * - Returns `max` if `value` is after `max`.
+ * - Returns `""` if any input is invalid or `min > max`.
+ *
+ * @param value ISO ZonedDateTime string to clamp
+ * @param min ISO ZonedDateTime string for the lower bound (inclusive)
+ * @param max ISO ZonedDateTime string for the upper bound (inclusive)
+ * @returns The clamped zoned datetime string, or "" on invalid input
+ *
+ * @example clampZoned("2024-03-15T12:00:00+00:00[UTC]", "2024-03-01T00:00:00+00:00[UTC]", "2024-03-31T23:59:59+00:00[UTC]") // "2024-03-15T12:00:00+00:00[UTC]"
+ * @example clampZoned("2024-02-01T12:00:00+00:00[UTC]", "2024-03-01T00:00:00+00:00[UTC]", "2024-03-31T23:59:59+00:00[UTC]") // "2024-03-01T00:00:00+00:00[UTC]"
+ * @example clampZoned("2024-05-01T12:00:00+00:00[UTC]", "2024-03-01T00:00:00+00:00[UTC]", "2024-03-31T23:59:59+00:00[UTC]") // "2024-03-31T23:59:59+00:00[UTC]"
+ * @example clampZoned("2024-03-15T12:00:00+00:00[UTC]", "2024-03-31T00:00:00+00:00[UTC]", "2024-03-01T00:00:00+00:00[UTC]") // ""
+ * @example clampZoned("invalid", "2024-03-01T00:00:00+00:00[UTC]", "2024-03-31T23:59:59+00:00[UTC]") // ""
+ */
+export function clampZoned(value, min, max) {
+    if (!isValidZonedDateTime(value) ||
+        !isValidZonedDateTime(min) ||
+        !isValidZonedDateTime(max)) {
+        return "";
+    }
+    try {
+        const v = Temporal.ZonedDateTime.from(value);
+        const mn = Temporal.ZonedDateTime.from(min);
+        const mx = Temporal.ZonedDateTime.from(max);
+        if (Temporal.ZonedDateTime.compare(mn, mx) === 1) {
+            return "";
+        }
+        const cmpMin = Temporal.ZonedDateTime.compare(v, mn);
+        const cmpMax = Temporal.ZonedDateTime.compare(v, mx);
+        if (cmpMin < 0) {
+            return mn.toString();
+        }
+        if (cmpMax > 0) {
+            return mx.toString();
+        }
+        return v.toString();
+    }
+    catch {
+        return "";
+    }
+}

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

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

package/dist/zoned/calculate/closestZonedTo.js

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

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

@@ -0,0 +1,44 @@
+import type { DateTimeCycleField, Disambiguation, Offset, Overflow } from "../../types/index.js";
+/**
+ * Return a ZonedDateTime ISO string with `field` cycled by `amount`, wrapping at that field's own
+ * min/max instead of carrying into the next larger field.
+ *
+ * - `cycleZoned` is not `addZoned`: cycling December's `month` by `+1` stays in the same year, and
+ *   cycling `hour` `23` by `+1` stays on the same day. Reach for `addZoned` for calendar/clock
+ *   arithmetic; reach for `cycleZoned` when a single field (e.g. a datepicker segment) must stay
+ *   isolated from the others.
+ * - Wrap bounds are computed the same way as `cycleDateTime` — plain local-field bounds (`hour`
+ *   always `0–23`, etc.), **not** DST-aware absolute-time bounds. The wrapped local time is then
+ *   handed to `setZoned`, whose `.with()` call — via `disambiguation` and `offset` — resolves
+ *   whatever DST edge case results (the wrapped local time landing in a gap or an overlap) exactly
+ *   the way it resolves any other field-set call. This is deliberately simpler than deriving
+ *   DST-aware wrap boundaries directly.
+ * - `disambiguation` defaults to `"compatible"` and `offset` defaults to `"ignore"` (not
+ *   Temporal's own `"prefer"` default) — the same C3 precedent as `setZoned`/`startOfZoned`: with
+ *   `"prefer"`, the source's still-valid offset is kept and `disambiguation` is silently never
+ *   consulted. Leave `offset` at its default unless you specifically need Temporal's raw `.with()`
+ *   semantics.
+ * - `options.round` steps to the *next* multiple of `amount` in the direction of its sign
+ *   (ceiling for positive, floor for negative) — not the nearest one. See `cycleDate`/`cycleTime`'s
+ *   docs for worked examples.
+ * - Returns "" for an invalid `value` or an invalid `field`.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param field the field to cycle: "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
+ * @param amount signed amount to cycle by
+ * @param options optional: round (boolean, default false), overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns zoned ISO 8601 string with `field` cycled, or "" on invalid input
+ *
+ * @example cycleZoned("2024-06-15T09:30:00-05:00[America/Chicago]", "hour", 1) // "2024-06-15T10:30:00-05:00[America/Chicago]"
+ * @example cycleZoned("2024-12-15T09:30:00-06:00[America/Chicago]", "month", 1) // "2024-01-15T09:30:00-06:00[America/Chicago]" (wraps, stays in the same year)
+ * @example cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1) // "2024-03-10T03:30:00-05:00[America/Chicago]" (cycled hour lands in a spring-forward gap; "compatible" skips forward)
+ * @example cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1, { disambiguation: "reject" }) // "" (same gap; "reject" throws)
+ * @example cycleZoned("2024-06-15T09:30:00-05:00[America/Chicago]", "week", 1) // "" ("week" is not a cyclable field)
+ * @example cycleZoned("invalid", "hour", 1) // ""
+ */
+export declare function cycleZoned(value: string, field: DateTimeCycleField, amount: number, options?: {
+    round?: boolean;
+    overflow?: Overflow;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): string;

package/dist/zoned/calculate/cycleZoned.js

@@ -0,0 +1,58 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { cycleFieldValue, dateCycleFieldBounds, timeCycleFieldBounds, } from "../../internal/index.js";
+import { isValidDateCycleField, isValidDateTimeCycleField, } from "../../plain/validate/index.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+import { setZoned } from "./setZoned.js";
+/**
+ * Return a ZonedDateTime ISO string with `field` cycled by `amount`, wrapping at that field's own
+ * min/max instead of carrying into the next larger field.
+ *
+ * - `cycleZoned` is not `addZoned`: cycling December's `month` by `+1` stays in the same year, and
+ *   cycling `hour` `23` by `+1` stays on the same day. Reach for `addZoned` for calendar/clock
+ *   arithmetic; reach for `cycleZoned` when a single field (e.g. a datepicker segment) must stay
+ *   isolated from the others.
+ * - Wrap bounds are computed the same way as `cycleDateTime` — plain local-field bounds (`hour`
+ *   always `0–23`, etc.), **not** DST-aware absolute-time bounds. The wrapped local time is then
+ *   handed to `setZoned`, whose `.with()` call — via `disambiguation` and `offset` — resolves
+ *   whatever DST edge case results (the wrapped local time landing in a gap or an overlap) exactly
+ *   the way it resolves any other field-set call. This is deliberately simpler than deriving
+ *   DST-aware wrap boundaries directly.
+ * - `disambiguation` defaults to `"compatible"` and `offset` defaults to `"ignore"` (not
+ *   Temporal's own `"prefer"` default) — the same C3 precedent as `setZoned`/`startOfZoned`: with
+ *   `"prefer"`, the source's still-valid offset is kept and `disambiguation` is silently never
+ *   consulted. Leave `offset` at its default unless you specifically need Temporal's raw `.with()`
+ *   semantics.
+ * - `options.round` steps to the *next* multiple of `amount` in the direction of its sign
+ *   (ceiling for positive, floor for negative) — not the nearest one. See `cycleDate`/`cycleTime`'s
+ *   docs for worked examples.
+ * - Returns "" for an invalid `value` or an invalid `field`.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param field the field to cycle: "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
+ * @param amount signed amount to cycle by
+ * @param options optional: round (boolean, default false), overflow ("constrain" | "reject"), disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns zoned ISO 8601 string with `field` cycled, or "" on invalid input
+ *
+ * @example cycleZoned("2024-06-15T09:30:00-05:00[America/Chicago]", "hour", 1) // "2024-06-15T10:30:00-05:00[America/Chicago]"
+ * @example cycleZoned("2024-12-15T09:30:00-06:00[America/Chicago]", "month", 1) // "2024-01-15T09:30:00-06:00[America/Chicago]" (wraps, stays in the same year)
+ * @example cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1) // "2024-03-10T03:30:00-05:00[America/Chicago]" (cycled hour lands in a spring-forward gap; "compatible" skips forward)
+ * @example cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1, { disambiguation: "reject" }) // "" (same gap; "reject" throws)
+ * @example cycleZoned("2024-06-15T09:30:00-05:00[America/Chicago]", "week", 1) // "" ("week" is not a cyclable field)
+ * @example cycleZoned("invalid", "hour", 1) // ""
+ */
+export function cycleZoned(value, field, amount, options) {
+    if (!isValidZonedDateTime(value) || !isValidDateTimeCycleField(field)) {
+        return "";
+    }
+    try {
+        const zoned = Temporal.ZonedDateTime.from(value);
+        const bounds = isValidDateCycleField(field)
+            ? dateCycleFieldBounds(field, zoned)
+            : timeCycleFieldBounds(field);
+        const newValue = cycleFieldValue(zoned[field], amount, bounds, options?.round ?? false);
+        return setZoned(value, { [field]: newValue }, options);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { Temporal } from "@js-temporal/polyfill";
+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.
+ * - 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.
+ * - 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
+ *   Temporal and returns null, same as other invalid input.
+ *
+ * @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)
+ * @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("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)
+ */
+export declare function diffZoned(value1: string, value2: string, units: DateTimeDurationUnit | DateTimeDurationUnit[], options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number> | null;

package/dist/zoned/calculate/diffZoned.js

@@ -0,0 +1,76 @@
+import { parseCalendarZonedPairForArithmetic } from "../../internal/index.js";
+import { getLargestDateTimeDurationUnit } from "../../plain/calculate/getLargestDateTimeDurationUnit.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { isValidCalendarZonedDateTime } from "../validate/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.
+ * - 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.
+ * - 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
+ *   Temporal and returns null, same as other invalid input.
+ *
+ * @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)
+ * @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("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)
+ */
+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;
+        }
+        return units.reduce((result, unit) => {
+            result[unit] = duration[unit] ?? 0;
+            return result;
+        }, {});
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,36 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } from "../../types/index.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).
+ * - 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.
+ * - Returns `""` for invalid input (negative diffs are valid and render with a leading `-`).
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the
+ * underlying difference before it's rendered, per Temporal's DifferenceOptions — same as
+ * `diffZoned`. `toStringSmallestUnit`, `fractionalSecondDigits`, and `toStringRoundingMode`
+ * control the precision of the rendered string itself, per Temporal's ToStringPrecisionOptions
+ * (mirroring `parseDuration`'s options) — kept separate from the `.until()` rounding options
+ * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
+ * different Temporal types.
+ *
+ * @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)
+ * @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("2028-01-01T00:00:00+00:00[UTC]", "2028-01-01T00:00:00+00:00[UTC]", "hours") // "PT0S"
+ * @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)
+ */
+export declare function diffZonedAsDuration(value1: string, value2: string, unit: DateTimeDurationUnit, options?: RoundingOptions<Temporal.DateTimeUnit> & DurationStringOptions): string;

package/dist/zoned/calculate/diffZonedAsDuration.js

@@ -0,0 +1,55 @@
+import { durationUntilString, parseCalendarZonedPairForArithmetic, } from "../../internal/index.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
+import { isValidCalendarZonedDateTime } from "../validate/index.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).
+ * - 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.
+ * - Returns `""` for invalid input (negative diffs are valid and render with a leading `-`).
+ *
+ * `smallestUnit`, `roundingIncrement`, and `roundingMode` control optional rounding of the
+ * underlying difference before it's rendered, per Temporal's DifferenceOptions — same as
+ * `diffZoned`. `toStringSmallestUnit`, `fractionalSecondDigits`, and `toStringRoundingMode`
+ * control the precision of the rendered string itself, per Temporal's ToStringPrecisionOptions
+ * (mirroring `parseDuration`'s options) — kept separate from the `.until()` rounding options
+ * above because both option sets have colliding `smallestUnit`/`roundingMode` keys with
+ * different Temporal types.
+ *
+ * @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)
+ * @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("2028-01-01T00:00:00+00:00[UTC]", "2028-01-01T00:00:00+00:00[UTC]", "hours") // "PT0S"
+ * @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)
+ */
+export function diffZonedAsDuration(value1, value2, unit, options) {
+    const validZonedDateTimes = isValidCalendarZonedDateTime(value1) &&
+        isValidCalendarZonedDateTime(value2);
+    const validUnit = isValidDateTimeDurationUnit(unit);
+    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);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { Disambiguation, FractionalDigit, Offset } 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).
+ * - 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 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("invalid") // ""
+ */
+export declare function endOfQuarterForZoned(value: string, optionsArg?: {
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+    fractionalSecondDigits?: FractionalDigit;
+}): string;

package/dist/zoned/calculate/endOfQuarterForZoned.js

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

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

@@ -0,0 +1,28 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { Disambiguation, FractionalDigit, Offset } 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.
+ * - Returns "" for invalid input.
+ *
+ * @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")
+ * @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("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)
+ */
+export declare function endOfZoned(value: string, unit: Temporal.DateUnit | Temporal.TimeUnit, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+    fractionalSecondDigits?: FractionalDigit;
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): string;