@northguild/gmt 1.14.2

package/dist/utc/parse/parseMonthFromUtc.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../validate/index.js";
+/**
+ * Return the month (1-12) from a UTC datetime string.
+ *
+ * - Returns zero-padded string for month.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @returns Month (01-12) or "" on invalid input
+ *
+ * @example parseMonthFromUtc("2024-03-17T14:30:45Z") // "03"
+ * @example parseMonthFromUtc("invalid") // ""
+ */
+export function parseMonthFromUtc(value) {
+    if (!isValidUtc(value))
+        return "";
+    try {
+        const instant = Temporal.Instant.from(value);
+        const dateTime = instant.toZonedDateTimeISO("UTC");
+        return dateTime.month.toString().padStart(2, "0");
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the nanosecond (0-999) from a UTC datetime string.
+ *
+ * - Returns zero-padded string for nanosecond.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45.123Z")
+ * @returns Nanosecond (000-999) or "" on invalid input
+ *
+ * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123Z") // "123000000"
+ * @example parseNanosecondFromUtc("invalid") // ""
+ */
+export declare function parseNanosecondFromUtc(value: string): string;

package/dist/utc/parse/parseNanosecondFromUtc.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../validate/index.js";
+/**
+ * Return the nanosecond (0-999) from a UTC datetime string.
+ *
+ * - Returns zero-padded string for nanosecond.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45.123Z")
+ * @returns Nanosecond (000-999) or "" on invalid input
+ *
+ * @example parseNanosecondFromUtc("2024-03-17T14:30:45.123Z") // "123000000"
+ * @example parseNanosecondFromUtc("invalid") // ""
+ */
+export function parseNanosecondFromUtc(value) {
+    if (!isValidUtc(value))
+        return "";
+    try {
+        const instant = Temporal.Instant.from(value);
+        const dateTime = instant.toZonedDateTimeISO("UTC");
+        return (dateTime.nanosecond ?? 0).toString().padStart(3, "0");
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the second (0-59) from a UTC datetime string.
+ *
+ * - Returns zero-padded string for second.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @returns Second (00-59) or "" on invalid input
+ *
+ * @example parseSecondFromUtc("2024-03-17T14:30:45Z") // "45"
+ * @example parseSecondFromUtc("invalid") // ""
+ */
+export declare function parseSecondFromUtc(value: string): string;

package/dist/utc/parse/parseSecondFromUtc.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../validate/index.js";
+/**
+ * Return the second (0-59) from a UTC datetime string.
+ *
+ * - Returns zero-padded string for second.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @returns Second (00-59) or "" on invalid input
+ *
+ * @example parseSecondFromUtc("2024-03-17T14:30:45Z") // "45"
+ * @example parseSecondFromUtc("invalid") // ""
+ */
+export function parseSecondFromUtc(value) {
+    if (!isValidUtc(value))
+        return "";
+    try {
+        const instant = Temporal.Instant.from(value);
+        const dateTime = instant.toZonedDateTimeISO("UTC");
+        return dateTime.second.toString().padStart(2, "0");
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Extract the time portion from a UTC datetime string.
+ *
+ * - Uses Temporal.Instant.from to parse, converts to specified timezone.
+ * - Defaults to UTC if no timezone specified.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA)
+ * @returns ISO time string (e.g., "14:30:45") or "" on invalid input
+ *
+ * @example parseTimeFromUtc("2024-03-17T14:30:45Z") // "14:30:45"
+ * @example parseTimeFromUtc("2024-03-17T14:30:45Z", { timeZone: "America/New_York" }) // "10:30:45"
+ * @example parseTimeFromUtc("invalid") // ""
+ */
+export declare function parseTimeFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseTimeFromUtc.js

@@ -0,0 +1,35 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidTimeZone } from "../../zoned/index.js";
+import { isValidUtc } from "../validate/index.js";
+/**
+ * Extract the time portion from a UTC datetime string.
+ *
+ * - Uses Temporal.Instant.from to parse, converts to specified timezone.
+ * - Defaults to UTC if no timezone specified.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA)
+ * @returns ISO time string (e.g., "14:30:45") or "" on invalid input
+ *
+ * @example parseTimeFromUtc("2024-03-17T14:30:45Z") // "14:30:45"
+ * @example parseTimeFromUtc("2024-03-17T14:30:45Z", { timeZone: "America/New_York" }) // "10:30:45"
+ * @example parseTimeFromUtc("invalid") // ""
+ */
+export function parseTimeFromUtc(value, options) {
+    if (!isValidUtc(value)) {
+        return "";
+    }
+    const { timeZone = "UTC" } = options ?? {};
+    if (timeZone !== "UTC" && !isValidTimeZone(timeZone)) {
+        return "";
+    }
+    try {
+        const instant = Temporal.Instant.from(value);
+        const dateTime = instant.toZonedDateTimeISO(timeZone);
+        return dateTime.toPlainTime().toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,21 @@
+export type UtcUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond";
+/**
+ * Extract a unit from a UTC datetime string.
+ *
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond".
+ * - Uses Temporal.Instant.from to parse, converts to UTC.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param unit unit to extract from the datetime
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns string representation of the requested unit or "" on invalid input
+ *
+ * @example parseUnitFromUtc("2024-03-17T14:30:45Z", "month") // "03"
+ * @example parseUnitFromUtc("2024-01-01T00:00:00Z", "week") // "1"
+ * @example parseUnitFromUtc("2024-01-01T00:00:00Z", "week", { weekStartsOn: "sunday" }) // "1"
+ * @example parseUnitFromUtc("invalid", "month") // ""
+ */
+export declare function parseUnitFromUtc(value: string, unit: UtcUnit, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+}): string;

package/dist/utc/parse/parseUnitFromUtc.js

@@ -0,0 +1,55 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
+import { isValidUtc } from "../validate/index.js";
+/**
+ * Extract a unit from a UTC datetime string.
+ *
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond".
+ * - Uses Temporal.Instant.from to parse, converts to UTC.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param unit unit to extract from the datetime
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns string representation of the requested unit or "" on invalid input
+ *
+ * @example parseUnitFromUtc("2024-03-17T14:30:45Z", "month") // "03"
+ * @example parseUnitFromUtc("2024-01-01T00:00:00Z", "week") // "1"
+ * @example parseUnitFromUtc("2024-01-01T00:00:00Z", "week", { weekStartsOn: "sunday" }) // "1"
+ * @example parseUnitFromUtc("invalid", "month") // ""
+ */
+export function parseUnitFromUtc(value, unit, optionsArg) {
+    if (!isValidUtc(value)) {
+        return "";
+    }
+    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
+    try {
+        const instant = Temporal.Instant.from(value);
+        const dateTime = instant.toZonedDateTimeISO("UTC");
+        switch (unit) {
+            case "year":
+                return dateTime.year.toString();
+            case "month":
+                return dateTime.month.toString().padStart(2, "0");
+            case "week":
+                return (getWeekNumber(`${dateTime.year}-${dateTime.month.toString().padStart(2, "0")}-${dateTime.day.toString().padStart(2, "0")}`, weekStartsOn) ?? 0).toString();
+            case "day":
+                return dateTime.day.toString().padStart(2, "0");
+            case "dayOfWeek":
+                return dateTime.dayOfWeek.toString();
+            case "hour":
+                return dateTime.hour.toString().padStart(2, "0");
+            case "minute":
+                return dateTime.minute.toString().padStart(2, "0");
+            case "second":
+                return dateTime.second.toString().padStart(2, "0");
+            case "millisecond":
+                return dateTime.millisecond.toString().padStart(3, "0");
+            default:
+                return "";
+        }
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Return the week number from a UTC datetime string.
+ *
+ * - By default uses ISO weeks (Monday-based).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example parseWeekFromUtc("2024-03-17T14:30:45Z") // 11
+ * @example parseWeekFromUtc("invalid") // null
+ */
+export declare function parseWeekFromUtc(value: string, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+}): number | null;

package/dist/utc/parse/parseWeekFromUtc.js

@@ -0,0 +1,30 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
+import { isValidUtc } from "../validate/index.js";
+/**
+ * Return the week number from a UTC datetime string.
+ *
+ * - By default uses ISO weeks (Monday-based).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example parseWeekFromUtc("2024-03-17T14:30:45Z") // 11
+ * @example parseWeekFromUtc("invalid") // null
+ */
+export function parseWeekFromUtc(value, optionsArg) {
+    if (!isValidUtc(value))
+        return null;
+    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
+    try {
+        const instant = Temporal.Instant.from(value);
+        const dt = instant.toZonedDateTimeISO("UTC");
+        const dateStr = `${dt.year}-${dt.month.toString().padStart(2, "0")}-${dt.day.toString().padStart(2, "0")}`;
+        return getWeekNumber(dateStr, weekStartsOn);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Return the year from a UTC datetime string.
+ *
+ * - Returns the year as a string (e.g., "2024").
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @returns Year (YYYY) or "" on invalid input
+ *
+ * @example parseYearFromUtc("2024-03-17T14:30:45Z") // "2024"
+ * @example parseYearFromUtc("invalid") // ""
+ */
+export declare function parseYearFromUtc(value: string): string;

package/dist/utc/parse/parseYearFromUtc.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidUtc } from "../validate/index.js";
+/**
+ * Return the year from a UTC datetime string.
+ *
+ * - Returns the year as a string (e.g., "2024").
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @returns Year (YYYY) or "" on invalid input
+ *
+ * @example parseYearFromUtc("2024-03-17T14:30:45Z") // "2024"
+ * @example parseYearFromUtc("invalid") // ""
+ */
+export function parseYearFromUtc(value) {
+    if (!isValidUtc(value))
+        return "";
+    try {
+        const instant = Temporal.Instant.from(value);
+        const dateTime = instant.toZonedDateTimeISO("UTC");
+        return dateTime.year.toString();
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,2 @@
+export * from "./isValidUtc.js";
+export * from "./isValidUtcRange.js";

package/dist/utc/validate/index.js

@@ -0,0 +1,2 @@
+export * from "./isValidUtc.js";
+export * from "./isValidUtcRange.js";

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

@@ -0,0 +1,17 @@
+/**
+ * Return true when the provided string is a valid ISO 8601 UTC datetime.
+ *
+ * - Uses regex to check format before parsing.
+ * - Rejects leap seconds (e.g., "2024-12-31T23:59:60Z").
+ * - Uses Temporal.Instant.from for validation.
+ * - Requires a time component — date-only strings ("2024-01-01Z") are rejected.
+ *
+ * @param value input UTC datetime string (ISO 8601)
+ * @returns boolean indicating whether the input is a valid UTC datetime
+ *
+ * @example isValidUtc("2024-03-17T14:30:45Z") // true
+ * @example isValidUtc("2024-01-01Z") // false — date-only not supported
+ * @example isValidUtc("2024-12-31T23:59:60Z") // false
+ * @example isValidUtc("invalid") // false
+ */
+export declare function isValidUtc(value: string): boolean;

package/dist/utc/validate/isValidUtc.js

@@ -0,0 +1,34 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/index.js";
+import { utcDateTime } from "../../regex/utc-date-time.js";
+/**
+ * Return true when the provided string is a valid ISO 8601 UTC datetime.
+ *
+ * - Uses regex to check format before parsing.
+ * - Rejects leap seconds (e.g., "2024-12-31T23:59:60Z").
+ * - Uses Temporal.Instant.from for validation.
+ * - Requires a time component — date-only strings ("2024-01-01Z") are rejected.
+ *
+ * @param value input UTC datetime string (ISO 8601)
+ * @returns boolean indicating whether the input is a valid UTC datetime
+ *
+ * @example isValidUtc("2024-03-17T14:30:45Z") // true
+ * @example isValidUtc("2024-01-01Z") // false — date-only not supported
+ * @example isValidUtc("2024-12-31T23:59:60Z") // false
+ * @example isValidUtc("invalid") // false
+ */
+export function isValidUtc(value) {
+    if (isLeapSecond(value)) {
+        return false;
+    }
+    if (!utcDateTime.test(value)) {
+        return false;
+    }
+    try {
+        Temporal.Instant.from(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Return true if `value1` and `value2` form a valid UTC range — both parseable as
+ * ISO UTC datetime strings and the instant at `value1` is <= the instant at `value2`.
+ *
+ * - Both inputs must be ISO 8601 UTC datetime strings (e.g. `"2024-01-01T10:00:00Z"`).
+ * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
+ * - Leap-second strings return `false`.
+ * - Invalid input or malformed strings return `false`.
+ *
+ * @param value1 first ISO UTC datetime string
+ * @param value2 second ISO UTC datetime string
+ * @param options optional allowEqual flag
+ * @returns boolean indicating whether the UTC range is valid
+ *
+ * @example isValidUtcRange({ value1: "2024-01-01T10:00:00Z", value2: "2024-12-31T23:59:59Z" }) // true
+ * @example isValidUtcRange({ value1: "2024-12-31T23:59:59Z", value2: "2024-01-01T10:00:00Z" }) // false
+ * @example isValidUtcRange({ value1: "2024-01-01T10:00:00Z", value2: "2024-01-01T10:00:00Z", options: { allowEqual: true } }) // true
+ */
+export declare function isValidUtcRange({ value1, value2, options, }: {
+    value1: string;
+    value2: string;
+    options?: {
+        allowEqual?: boolean;
+    };
+}): boolean;

package/dist/utc/validate/isValidUtcRange.js

@@ -0,0 +1,44 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+import { utcDateTime } from "../../regex/utc-date-time.js";
+/**
+ * Return true if `value1` and `value2` form a valid UTC range — both parseable as
+ * ISO UTC datetime strings and the instant at `value1` is <= the instant at `value2`.
+ *
+ * - Both inputs must be ISO 8601 UTC datetime strings (e.g. `"2024-01-01T10:00:00Z"`).
+ * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
+ * - Leap-second strings return `false`.
+ * - Invalid input or malformed strings return `false`.
+ *
+ * @param value1 first ISO UTC datetime string
+ * @param value2 second ISO UTC datetime string
+ * @param options optional allowEqual flag
+ * @returns boolean indicating whether the UTC range is valid
+ *
+ * @example isValidUtcRange({ value1: "2024-01-01T10:00:00Z", value2: "2024-12-31T23:59:59Z" }) // true
+ * @example isValidUtcRange({ value1: "2024-12-31T23:59:59Z", value2: "2024-01-01T10:00:00Z" }) // false
+ * @example isValidUtcRange({ value1: "2024-01-01T10:00:00Z", value2: "2024-01-01T10:00:00Z", options: { allowEqual: true } }) // true
+ */
+export function isValidUtcRange({ value1, value2, options, }) {
+    if (typeof value1 !== "string" || typeof value2 !== "string") {
+        return false;
+    }
+    if (!utcDateTime.test(value1) || !utcDateTime.test(value2)) {
+        return false;
+    }
+    if (isLeapSecond(value1) || isLeapSecond(value2)) {
+        return false;
+    }
+    try {
+        const startInstant = Temporal.Instant.from(value1);
+        const endInstant = Temporal.Instant.from(value2);
+        const cmp = Temporal.Instant.compare(startInstant, endInstant);
+        if (options?.allowEqual) {
+            return cmp <= 0;
+        }
+        return cmp < 0;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,50 @@
+import type { DateTimeDurationUnit, Disambiguation, Offset, Overflow } from "../../types/index.js";
+/**
+ * Add a temporal amount to a zoned ISO 8601 datetime string and return a zoned ISO 8601 string.
+ *
+ * - Uses Temporal.ZonedDateTime.add to add duration.
+ * - Validates duration units and values.
+ * - Accepts a GMT calendar-annotated zoned string (as produced by `convertZonedToCalendar`, e.g.
+ *   `"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`), not just a bare ISO string —
+ *   E7 (issue #152). Calendar-unit arithmetic ("add 1 month") resolves against that calendar (a
+ *   Hebrew leap month, an Ethiopic Pagumen, a Japanese era change) **and** the DST rules of the
+ *   zone, in one operation. The calendar tag, the era, the wall time and the UTC offset are all
+ *   re-derived from the result, never copied from the input — Hebrew Adar I 15 in
+ *   `America/New_York` `+1 month` moves both the month (Adar I -> Adar) and the offset
+ *   (-05:00 -> -04:00). A bare ISO string is unaffected — always treated as, and always returns,
+ *   `"gregorian"`.
+ * - `disambiguation` controls DST resolution ONLY when the arithmetic result lands on an ambiguous
+ *   local time from a fall-back (DST-end) overlap: "compatible" (default), "earlier", "later", or
+ *   "reject" (throws, resulting in ""). Has no effect when the result lands in a spring-forward
+ *   (DST-start) gap — Temporal's arithmetic always resolves gap landings unambiguously (by advancing
+ *   past the gap) before disambiguation is ever evaluated.
+ * - `offset` ("prefer" | "use" | "ignore" (default) | "reject") is accepted for API consistency with
+ *   sibling zoned-construction functions (see `startOfZoned`, `endOfZoned`, etc.) but has **no effect
+ *   here**: the internal rebuild step reconstructs from a plain datetime string with no UTC offset
+ *   embedded, so there is never a stored offset for `offset` to prefer/use/ignore/reject against.
+ *   `disambiguation` is the only option that affects this function's output.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO 8601 zoned datetime string, optionally calendar-annotated
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
+ * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject" — accepted but inert, see above), overflow ("constrain" | "reject")
+ * @returns zoned ISO 8601 string on success, or "" on invalid input
+ *
+ * @example addZoned("2024-02-29T14:30:45.123-05:00[America/New_York]", { days: 1 }) // "2024-03-01T14:30:45.123-05:00[America/New_York]"
+ * @example addZoned("invalid", { days: 1 }) // ""
+ * @example addZoned("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", { months: 1 }) // "5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]" (Adar I -> Adar, EST -> EDT in one call)
+ * @example addZoned("0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]", { days: 1 }) // "0001-05-01T12:00:00+09:00[u-ca=japanese;era=reiwa][Asia/Tokyo]" (era re-derived, not copied)
+ * @example addZoned("7517-12-30T00:30:00-04:00[u-ca=ethiopic-amete-alem][America/Santiago]", { months: 1 }, { overflow: "reject" }) // "" (day 30 does not exist in the 5-day Pagumen)
+ * @example addZoned("2024-03-10T14:30:00-04:00[America/New_York][u-ca=hebrew]", { days: 1 }) // "" (Temporal's segment ordering is not GMT's grammar)
+ * @example addZoned("2024-11-02T01:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "later" }) // "2024-11-03T01:30:00-05:00[America/New_York]" (fall-back overlap resolved; default "compatible" would return the -04:00 instant instead)
+ * @example addZoned("2024-11-02T01:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "" (fall-back overlap rejected)
+ * @example addZoned("2024-03-09T02:30:00-05:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "2024-03-10T03:30:00-04:00[America/New_York]" (spring-forward gap — disambiguation has no effect, arithmetic already advanced past it, so "reject" does not throw here)
+ * @example addZoned("2024-01-31T12:00:00-05:00[America/New_York]", { months: 1 }, { overflow: "reject" }) // ""
+ */
+export declare function addZoned(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, optionsArg?: {
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+    overflow?: Overflow;
+}): string;

package/dist/zoned/calculate/addZoned.js

@@ -0,0 +1,88 @@
+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";
+/**
+ * Add a temporal amount to a zoned ISO 8601 datetime string and return a zoned ISO 8601 string.
+ *
+ * - Uses Temporal.ZonedDateTime.add to add duration.
+ * - Validates duration units and values.
+ * - Accepts a GMT calendar-annotated zoned string (as produced by `convertZonedToCalendar`, e.g.
+ *   `"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`), not just a bare ISO string —
+ *   E7 (issue #152). Calendar-unit arithmetic ("add 1 month") resolves against that calendar (a
+ *   Hebrew leap month, an Ethiopic Pagumen, a Japanese era change) **and** the DST rules of the
+ *   zone, in one operation. The calendar tag, the era, the wall time and the UTC offset are all
+ *   re-derived from the result, never copied from the input — Hebrew Adar I 15 in
+ *   `America/New_York` `+1 month` moves both the month (Adar I -> Adar) and the offset
+ *   (-05:00 -> -04:00). A bare ISO string is unaffected — always treated as, and always returns,
+ *   `"gregorian"`.
+ * - `disambiguation` controls DST resolution ONLY when the arithmetic result lands on an ambiguous
+ *   local time from a fall-back (DST-end) overlap: "compatible" (default), "earlier", "later", or
+ *   "reject" (throws, resulting in ""). Has no effect when the result lands in a spring-forward
+ *   (DST-start) gap — Temporal's arithmetic always resolves gap landings unambiguously (by advancing
+ *   past the gap) before disambiguation is ever evaluated.
+ * - `offset` ("prefer" | "use" | "ignore" (default) | "reject") is accepted for API consistency with
+ *   sibling zoned-construction functions (see `startOfZoned`, `endOfZoned`, etc.) but has **no effect
+ *   here**: the internal rebuild step reconstructs from a plain datetime string with no UTC offset
+ *   embedded, so there is never a stored offset for `offset` to prefer/use/ignore/reject against.
+ *   `disambiguation` is the only option that affects this function's output.
+ * - `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. adding 1 month
+ *   to Jan 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO 8601 zoned datetime string, optionally calendar-annotated
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
+ * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject" — accepted but inert, see above), overflow ("constrain" | "reject")
+ * @returns zoned ISO 8601 string on success, or "" on invalid input
+ *
+ * @example addZoned("2024-02-29T14:30:45.123-05:00[America/New_York]", { days: 1 }) // "2024-03-01T14:30:45.123-05:00[America/New_York]"
+ * @example addZoned("invalid", { days: 1 }) // ""
+ * @example addZoned("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", { months: 1 }) // "5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]" (Adar I -> Adar, EST -> EDT in one call)
+ * @example addZoned("0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]", { days: 1 }) // "0001-05-01T12:00:00+09:00[u-ca=japanese;era=reiwa][Asia/Tokyo]" (era re-derived, not copied)
+ * @example addZoned("7517-12-30T00:30:00-04:00[u-ca=ethiopic-amete-alem][America/Santiago]", { months: 1 }, { overflow: "reject" }) // "" (day 30 does not exist in the 5-day Pagumen)
+ * @example addZoned("2024-03-10T14:30:00-04:00[America/New_York][u-ca=hebrew]", { days: 1 }) // "" (Temporal's segment ordering is not GMT's grammar)
+ * @example addZoned("2024-11-02T01:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "later" }) // "2024-11-03T01:30:00-05:00[America/New_York]" (fall-back overlap resolved; default "compatible" would return the -04:00 instant instead)
+ * @example addZoned("2024-11-02T01:30:00-04:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "" (fall-back overlap rejected)
+ * @example addZoned("2024-03-09T02:30:00-05:00[America/New_York]", { days: 1 }, { disambiguation: "reject" }) // "2024-03-10T03:30:00-04:00[America/New_York]" (spring-forward gap — disambiguation has no effect, arithmetic already advanced past it, so "reject" does not throw here)
+ * @example addZoned("2024-01-31T12:00:00-05:00[America/New_York]", { months: 1 }, { overflow: "reject" }) // ""
+ */
+export function addZoned(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) {
+        // TODO descriptive messages of what failed - likely could be GMT offset for historical changes and DST
+        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 added = zoned.add(units, { overflow });
+        if (disambiguation === "compatible") {
+            return formatZonedInCalendar(added, calendar);
+        }
+        // The calendar MUST be stripped before this rebuild string is composed (E7 risk R1). A
+        // calendared `.toPlainDateTime().toString()` emits Temporal's own annotation — verified:
+        // "2024-03-25T14:30:00[u-ca=hebrew]" — so appending `[${timeZoneId}]` yields
+        // "...[u-ca=hebrew][America/New_York]", which is GMT's forbidden ordering and which
+        // `Temporal.ZonedDateTime.from` rejects. Without this the whole branch would silently degrade
+        // to "" for every non-"compatible" disambiguation the moment a calendar tag reached it.
+        // Round-tripping the rebuild through bare ISO and re-attaching the calendar to the RESULT
+        // (never to the input) keeps both the DST resolution and the calendar tag correct.
+        const plainDateTime = added
+            .withCalendar("iso8601")
+            .toPlainDateTime()
+            .toString();
+        const resolved = Temporal.ZonedDateTime.from(`${plainDateTime}[${added.timeZoneId}]`, { disambiguation, offset }).withCalendar(added.calendarId);
+        return formatZonedInCalendar(resolved, calendar);
+    }
+    catch {
+        return "";
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * 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 declare function addZonedBusinessDays(value: string, amount: number): string;