@northguild/gmt 1.14.2

package/dist/zoned/parse/parseSecondFromZoned.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the second (0-59) from a zoned datetime string.
+ *
+ * - Returns zero-padded string for second.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO zoned datetime string (e.g., "2024-03-15T14:30:45.123+00:00[UTC]")
+ * @returns Second (00-59) or "" on invalid input
+ *
+ * @example parseSecondFromZoned("2024-03-15T14:30:45+00:00[UTC]") // "45"
+ * @example parseSecondFromZoned("invalid") // ""
+ */
+export function parseSecondFromZoned(value) {
+    if (!isValidZonedDateTime(value)) {
+        return "";
+    }
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        return zonedDateTime.second.toString().padStart(2, "0");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/parse/parseTimeFromZoned.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Extract the plain time portion from an ISO 8601 zoned datetime string.
+ *
+ * - Extracts time components from a ZonedDateTime.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns plain time string (HH:mm:ss[.sss]) or "" when invalid
+ *
+ * @example parseTimeFromZoned("2024-02-29T12:34:56.789+00:00[UTC]") // "12:34:56.789"
+ * @example parseTimeFromZoned("invalid") // ""
+ */
+export declare function parseTimeFromZoned(value: string): string;

package/dist/zoned/parse/parseTimeFromZoned.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Extract the plain time portion from an ISO 8601 zoned datetime string.
+ *
+ * - Extracts time components from a ZonedDateTime.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns plain time string (HH:mm:ss[.sss]) or "" when invalid
+ *
+ * @example parseTimeFromZoned("2024-02-29T12:34:56.789+00:00[UTC]") // "12:34:56.789"
+ * @example parseTimeFromZoned("invalid") // ""
+ */
+export function parseTimeFromZoned(value) {
+    if (!isValidZonedDateTime(value)) {
+        return "";
+    }
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        return zonedDateTime?.toPlainTime().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/parse/parseTimeZoneFromZoned.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Extract the IANA timeZone identifier from an ISO 8601 zoned datetime string.
+ *
+ * - Extracts timeZone id from a ZonedDateTime.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns IANA timeZone id or "" when invalid
+ *
+ * @example parseTimeZoneFromZoned("2024-02-29T12:34:56.789+00:00[UTC]") // "UTC"
+ * @example parseTimeZoneFromZoned("invalid") // ""
+ */
+export declare function parseTimeZoneFromZoned(value: string): string;

package/dist/zoned/parse/parseTimeZoneFromZoned.js

@@ -0,0 +1,25 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Extract the IANA timeZone identifier from an ISO 8601 zoned datetime string.
+ *
+ * - Extracts timeZone id from a ZonedDateTime.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns IANA timeZone id or "" when invalid
+ *
+ * @example parseTimeZoneFromZoned("2024-02-29T12:34:56.789+00:00[UTC]") // "UTC"
+ * @example parseTimeZoneFromZoned("invalid") // ""
+ */
+export function parseTimeZoneFromZoned(value) {
+    if (!isValidZonedDateTime(value)) {
+        return "";
+    }
+    try {
+        return Temporal.ZonedDateTime.from(value).timeZoneId ?? "";
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/parse/parseUnitFromZoned.d.ts

@@ -0,0 +1,19 @@
+export type ZonedParseUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond" | "nanosecond" | "timeZone";
+/**
+ * Return the requested unit value from an ISO 8601 zoned datetime string.
+ *
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "nanosecond", "timeZone".
+ * - Uses Temporal.ZonedDateTime.from to parse.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param unit unit to extract
+ * @param options optional settings (e.g. weekStartsOn for week calculations)
+ * @returns string representation of the requested unit or "" when invalid
+ *
+ * @example parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "year") // "2024"
+ * @example parseUnitFromZoned("invalid", "year") // ""
+ */
+export declare function parseUnitFromZoned(value: string, unit: ZonedParseUnit, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+}): string;

package/dist/zoned/parse/parseUnitFromZoned.js

@@ -0,0 +1,71 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+function isValidZonedUnit(unit) {
+    return [
+        "year",
+        "month",
+        "week",
+        "day",
+        "dayOfWeek",
+        "hour",
+        "minute",
+        "second",
+        "millisecond",
+        "nanosecond",
+        "timeZone",
+    ].includes(unit);
+}
+/**
+ * Return the requested unit value from an ISO 8601 zoned datetime string.
+ *
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "nanosecond", "timeZone".
+ * - Uses Temporal.ZonedDateTime.from to parse.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param unit unit to extract
+ * @param options optional settings (e.g. weekStartsOn for week calculations)
+ * @returns string representation of the requested unit or "" when invalid
+ *
+ * @example parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "year") // "2024"
+ * @example parseUnitFromZoned("invalid", "year") // ""
+ */
+export function parseUnitFromZoned(value, unit, optionsArg) {
+    if (!isValidZonedDateTime(value) || !isValidZonedUnit(unit)) {
+        return "";
+    }
+    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        switch (unit) {
+            case "year":
+                return zonedDateTime.year.toString();
+            case "month":
+                return zonedDateTime.month.toString().padStart(2, "0");
+            case "week":
+                return (getWeekNumber(`${zonedDateTime.year}-${zonedDateTime.month.toString().padStart(2, "0")}-${zonedDateTime.day.toString().padStart(2, "0")}`, weekStartsOn) ?? 0).toString();
+            case "day":
+                return zonedDateTime.day.toString().padStart(2, "0");
+            case "dayOfWeek":
+                return zonedDateTime.dayOfWeek.toString();
+            case "hour":
+                return zonedDateTime.hour.toString().padStart(2, "0");
+            case "minute":
+                return zonedDateTime.minute.toString().padStart(2, "0");
+            case "second":
+                return zonedDateTime.second.toString().padStart(2, "0");
+            case "millisecond":
+                return zonedDateTime.millisecond.toString().padStart(3, "0");
+            case "nanosecond":
+                return zonedDateTime.nanosecond.toString().padStart(3, "0");
+            case "timeZone":
+                return zonedDateTime.timeZoneId;
+            default:
+                return "";
+        }
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/parse/parseWeekFromZoned.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Return the week of the year (1-53) for a given ISO 8601 zoned datetime string.
+ *
+ * - By default uses ISO weeks (Monday-based).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO zoned datetime string
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example parseWeekFromZoned("2024-01-01T14:30:45.123+00:00[UTC]") // 1
+ * @example parseWeekFromZoned("2024-01-08T14:30:45.123+00:00[UTC]") // 2
+ * @example parseWeekFromZoned("invalid") // null
+ */
+export declare function parseWeekFromZoned(value: string, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+}): number | null;

package/dist/zoned/parse/parseWeekFromZoned.js

@@ -0,0 +1,30 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the week of the year (1-53) for a given ISO 8601 zoned datetime string.
+ *
+ * - By default uses ISO weeks (Monday-based).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO zoned datetime string
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example parseWeekFromZoned("2024-01-01T14:30:45.123+00:00[UTC]") // 1
+ * @example parseWeekFromZoned("2024-01-08T14:30:45.123+00:00[UTC]") // 2
+ * @example parseWeekFromZoned("invalid") // null
+ */
+export function parseWeekFromZoned(value, optionsArg) {
+    if (!isValidZonedDateTime(value)) {
+        return null;
+    }
+    const weekStartsOn = optionsArg?.weekStartsOn ?? "monday";
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        return getWeekNumber(`${zonedDateTime.year}-${zonedDateTime.month.toString().padStart(2, "0")}-${zonedDateTime.day.toString().padStart(2, "0")}`, weekStartsOn);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/zoned/parse/parseYearFromZoned.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Return the year for a given ISO 8601 zoned datetime string.
+ *
+ * - Returns string for year.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO zoned datetime string
+ * @returns Year as string or "" on invalid input
+ *
+ * @example parseYearFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "2024"
+ * @example parseYearFromZoned("invalid") // ""
+ */
+export declare function parseYearFromZoned(value: string): string;

package/dist/zoned/parse/parseYearFromZoned.js

@@ -0,0 +1,26 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return the year for a given ISO 8601 zoned datetime string.
+ *
+ * - Returns string for year.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO zoned datetime string
+ * @returns Year as string or "" on invalid input
+ *
+ * @example parseYearFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "2024"
+ * @example parseYearFromZoned("invalid") // ""
+ */
+export function parseYearFromZoned(value) {
+    if (!isValidZonedDateTime(value)) {
+        return "";
+    }
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        return zonedDateTime.year.toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/validate/hasDaylightSaving.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Check whether an IANA timeZone identifier observes daylight saving time.
+ *
+ * - Compares UTC offsets at two dates six months apart (January and July).
+ * - A zone is considered to have DST if its offset differs between the two dates.
+ * - Returns false for invalid or unresolvable timeZone identifiers.
+ *
+ * @param timeZone timeZone identifier to check
+ * @returns boolean indicating whether the timeZone observes DST
+ *
+ * @example hasDaylightSaving("America/New_York") // true
+ * @example hasDaylightSaving("Europe/Berlin")     // true
+ * @example hasDaylightSaving("Asia/Tokyo")        // false
+ * @example hasDaylightSaving("UTC")               // false
+ * @example hasDaylightSaving("Invalid/Zone")      // false
+ */
+export declare function hasDaylightSaving(timeZone: string): boolean;

package/dist/zoned/validate/hasDaylightSaving.js

@@ -0,0 +1,43 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Check whether an IANA timeZone identifier observes daylight saving time.
+ *
+ * - Compares UTC offsets at two dates six months apart (January and July).
+ * - A zone is considered to have DST if its offset differs between the two dates.
+ * - Returns false for invalid or unresolvable timeZone identifiers.
+ *
+ * @param timeZone timeZone identifier to check
+ * @returns boolean indicating whether the timeZone observes DST
+ *
+ * @example hasDaylightSaving("America/New_York") // true
+ * @example hasDaylightSaving("Europe/Berlin")     // true
+ * @example hasDaylightSaving("Asia/Tokyo")        // false
+ * @example hasDaylightSaving("UTC")               // false
+ * @example hasDaylightSaving("Invalid/Zone")      // false
+ */
+export function hasDaylightSaving(timeZone) {
+    try {
+        const zdtJanuary = Temporal.ZonedDateTime.from({
+            year: 2024,
+            month: 1,
+            day: 15,
+            hour: 12,
+            minute: 0,
+            second: 0,
+            timeZone,
+        });
+        const zdtJuly = Temporal.ZonedDateTime.from({
+            year: 2024,
+            month: 7,
+            day: 15,
+            hour: 12,
+            minute: 0,
+            second: 0,
+            timeZone,
+        });
+        return zdtJanuary.offsetNanoseconds !== zdtJuly.offsetNanoseconds;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,5 @@
+export * from "./hasDaylightSaving.js";
+export * from "./isValidCalendarZonedDateTime.js";
+export * from "./isValidTimeZone.js";
+export * from "./isValidZonedDateTime.js";
+export * from "./isValidZonedRange.js";

package/dist/zoned/validate/index.js

@@ -0,0 +1,5 @@
+export * from "./hasDaylightSaving.js";
+export * from "./isValidCalendarZonedDateTime.js";
+export * from "./isValidTimeZone.js";
+export * from "./isValidZonedDateTime.js";
+export * from "./isValidZonedRange.js";

package/dist/zoned/validate/isValidCalendarZonedDateTime.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Return true if `value` is a valid GMT ZonedDateTime string: a bare ISO zoned datetime
+ * ("2024-10-03T14:30:45-04:00[America/New_York]") or a calendar-annotated zoned datetime with
+ * calendar-native fields ("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"), as
+ * produced by `convertZonedToCalendar`.
+ *
+ * - Parallel to `isValidZonedDateTime`, which is deliberately left unchanged and still rejects
+ *   every `[u-ca=...]` annotation (E7, issue #152). Only the ~18 calendar-aware `zoned/`
+ *   functions gate on this validator; the ~72 that stay out of E7's scope keep the old one, so a
+ *   string can never be certified valid by a validator whose own namespace still refuses it.
+ * - Rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering, and a GMT-shaped string in
+ *   that ordering, for the reason spelled out in `regex/calendar-zoned-date-time.ts`: the latter
+ *   parses silently and wrongly (Hebrew year 5784 read as ISO year 5784).
+ * - Rejects leap seconds, which `Temporal.ZonedDateTime.from` otherwise clamps to `:59`.
+ * - Delegates all field-range, era, calendar-identifier and time-zone checking to Temporal (via
+ *   `parseCalendarZonedValue`) — the regex proves shape only.
+ * - Returns false for non-strings or empty strings.
+ *
+ * @param value candidate zoned datetime string, optionally calendar-annotated
+ * @returns boolean indicating validity
+ *
+ * @example isValidCalendarZonedDateTime("2024-10-03T14:30:45-04:00[America/New_York]") // true
+ * @example isValidCalendarZonedDateTime("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]") // true
+ * @example isValidCalendarZonedDateTime("0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]") // true
+ * @example isValidCalendarZonedDateTime("5784-06-15T14:30:00-05:00[America/New_York][u-ca=hebrew]") // false (Temporal's segment ordering)
+ * @example isValidCalendarZonedDateTime("5785-13-15T14:30:00-05:00[u-ca=hebrew][America/New_York]") // false (5785 is not a Hebrew leap year, so month 13 does not exist)
+ * @example isValidCalendarZonedDateTime("2024-06-30T23:59:60+00:00[UTC]") // false (leap second)
+ * @example isValidCalendarZonedDateTime("invalid") // false
+ */
+export declare function isValidCalendarZonedDateTime(value: string): boolean;

package/dist/zoned/validate/isValidCalendarZonedDateTime.js

@@ -0,0 +1,41 @@
+import { parseCalendarZonedValue } from "../../internal/index.js";
+/**
+ * Return true if `value` is a valid GMT ZonedDateTime string: a bare ISO zoned datetime
+ * ("2024-10-03T14:30:45-04:00[America/New_York]") or a calendar-annotated zoned datetime with
+ * calendar-native fields ("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"), as
+ * produced by `convertZonedToCalendar`.
+ *
+ * - Parallel to `isValidZonedDateTime`, which is deliberately left unchanged and still rejects
+ *   every `[u-ca=...]` annotation (E7, issue #152). Only the ~18 calendar-aware `zoned/`
+ *   functions gate on this validator; the ~72 that stay out of E7's scope keep the old one, so a
+ *   string can never be certified valid by a validator whose own namespace still refuses it.
+ * - Rejects Temporal's own `[timeZone][u-ca=...]` RFC 9557 ordering, and a GMT-shaped string in
+ *   that ordering, for the reason spelled out in `regex/calendar-zoned-date-time.ts`: the latter
+ *   parses silently and wrongly (Hebrew year 5784 read as ISO year 5784).
+ * - Rejects leap seconds, which `Temporal.ZonedDateTime.from` otherwise clamps to `:59`.
+ * - Delegates all field-range, era, calendar-identifier and time-zone checking to Temporal (via
+ *   `parseCalendarZonedValue`) — the regex proves shape only.
+ * - Returns false for non-strings or empty strings.
+ *
+ * @param value candidate zoned datetime string, optionally calendar-annotated
+ * @returns boolean indicating validity
+ *
+ * @example isValidCalendarZonedDateTime("2024-10-03T14:30:45-04:00[America/New_York]") // true
+ * @example isValidCalendarZonedDateTime("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]") // true
+ * @example isValidCalendarZonedDateTime("0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]") // true
+ * @example isValidCalendarZonedDateTime("5784-06-15T14:30:00-05:00[America/New_York][u-ca=hebrew]") // false (Temporal's segment ordering)
+ * @example isValidCalendarZonedDateTime("5785-13-15T14:30:00-05:00[u-ca=hebrew][America/New_York]") // false (5785 is not a Hebrew leap year, so month 13 does not exist)
+ * @example isValidCalendarZonedDateTime("2024-06-30T23:59:60+00:00[UTC]") // false (leap second)
+ * @example isValidCalendarZonedDateTime("invalid") // false
+ */
+export function isValidCalendarZonedDateTime(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        return false;
+    }
+    try {
+        return parseCalendarZonedValue(value).timeZoneId.length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/zoned/validate/isValidTimeZone.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Validate whether a string is a valid IANA timeZone identifier.
+ *
+ * - Uses Temporal.ZonedDateTime.from to test timezone validity.
+ * - Uses regex to check format.
+ * - Returns false for invalid timezone formats.
+ *
+ * @param timeZone timeZone identifier to validate
+ * @returns boolean indicating validity
+ *
+ * @example isValidTimeZone("America/New_York") // true
+ * @example isValidTimeZone("Europe/London") // true
+ * @example isValidTimeZone("Invalid/Timezone") // false
+ */
+export declare function isValidTimeZone(timeZone: string): boolean;

package/dist/zoned/validate/isValidTimeZone.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { timeZoneLike } from "../../regex/index.js";
+/**
+ * Validate whether a string is a valid IANA timeZone identifier.
+ *
+ * - Uses Temporal.ZonedDateTime.from to test timezone validity.
+ * - Uses regex to check format.
+ * - Returns false for invalid timezone formats.
+ *
+ * @param timeZone timeZone identifier to validate
+ * @returns boolean indicating validity
+ *
+ * @example isValidTimeZone("America/New_York") // true
+ * @example isValidTimeZone("Europe/London") // true
+ * @example isValidTimeZone("Invalid/Timezone") // false
+ */
+export function isValidTimeZone(timeZone) {
+    try {
+        Temporal.ZonedDateTime.from({
+            year: 2020,
+            month: 2,
+            day: 28,
+            hour: 0,
+            minute: 0,
+            second: 0,
+            timeZone,
+        });
+        return timeZoneLike.test(timeZone) && true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/zoned/validate/isValidZonedDateTime.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validate whether a string is a valid ISO 8601 zoned datetime string.
+ *
+ * - Uses Temporal.ZonedDateTime.from for validation.
+ * - Rejects leap seconds.
+ * - Rejects any `[u-ca=...]` calendar annotation (E5 issue #78, decision of record D2):
+ *   calendar-system awareness is confined to `plain/` `PlainDate` values (D1) — `zoned/`
+ *   previously accepted the annotation by accident (nothing gated it) and did genuinely
+ *   calendar-aware but undocumented, untested arithmetic; this closes that rather than
+ *   blessing it. See `context/roadmap/issues/E.md`'s E5 section for the follow-up story
+ *   proposal to extend `zoned/` with a GMT-shape annotated string deliberately.
+ * - Returns false for non-strings or empty strings.
+ *
+ * @param value candidate zoned datetime string
+ * @returns boolean indicating validity
+ *
+ * @example isValidZonedDateTime("2024-02-29T12:34:56.789+00:00[UTC]") // true
+ * @example isValidZonedDateTime("2024-06-30T23:59:60+00:00[UTC]") // false (leap second)
+ * @example isValidZonedDateTime("2024-02-10T12:00:00-05:00[America/New_York][u-ca=hebrew]") // false (calendar annotation rejected)
+ * @example isValidZonedDateTime("invalid") // false
+ */
+export declare function isValidZonedDateTime(value: string): boolean;

package/dist/zoned/validate/isValidZonedDateTime.js

@@ -0,0 +1,39 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { hasCalendarAnnotation } from "../../internal/index.js";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+/**
+ * Validate whether a string is a valid ISO 8601 zoned datetime string.
+ *
+ * - Uses Temporal.ZonedDateTime.from for validation.
+ * - Rejects leap seconds.
+ * - Rejects any `[u-ca=...]` calendar annotation (E5 issue #78, decision of record D2):
+ *   calendar-system awareness is confined to `plain/` `PlainDate` values (D1) — `zoned/`
+ *   previously accepted the annotation by accident (nothing gated it) and did genuinely
+ *   calendar-aware but undocumented, untested arithmetic; this closes that rather than
+ *   blessing it. See `context/roadmap/issues/E.md`'s E5 section for the follow-up story
+ *   proposal to extend `zoned/` with a GMT-shape annotated string deliberately.
+ * - Returns false for non-strings or empty strings.
+ *
+ * @param value candidate zoned datetime string
+ * @returns boolean indicating validity
+ *
+ * @example isValidZonedDateTime("2024-02-29T12:34:56.789+00:00[UTC]") // true
+ * @example isValidZonedDateTime("2024-06-30T23:59:60+00:00[UTC]") // false (leap second)
+ * @example isValidZonedDateTime("2024-02-10T12:00:00-05:00[America/New_York][u-ca=hebrew]") // false (calendar annotation rejected)
+ * @example isValidZonedDateTime("invalid") // false
+ */
+export function isValidZonedDateTime(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        return false;
+    }
+    if (isLeapSecond(value) || hasCalendarAnnotation(value)) {
+        return false;
+    }
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        return zonedDateTime.timeZoneId.length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/zoned/validate/isValidZonedRange.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Return true if `value1` and `value2` form a valid zoned range — both parseable as
+ * ISO ZonedDateTime strings and the instant at `value1` is <= the instant at `value2`.
+ *
+ * - Both inputs must be valid ISO 8601 zoned datetime strings.
+ * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
+ * - Comparison is done by instant, so intervals spanning DST transitions are compared
+ *   by absolute time.
+ * - Invalid input, malformed strings, or leap-second strings return `false`.
+ *
+ * @param value1 first ISO ZonedDateTime string
+ * @param value2 second ISO ZonedDateTime string
+ * @param options optional allowEqual flag
+ * @returns boolean indicating whether the zoned range is valid
+ *
+ * @example isValidZonedRange({ value1: "2024-01-01T10:00:00+00:00[UTC]", value2: "2024-12-31T23:59:59+00:00[UTC]" }) // true
+ * @example isValidZonedRange({ value1: "2024-12-31T23:59:59+00:00[UTC]", value2: "2024-01-01T10:00:00+00:00[UTC]" }) // false
+ * @example isValidZonedRange({ value1: "2024-06-15T12:00:00-04:00[America/New_York]", value2: "2024-06-15T12:00:00-04:00[America/New_York]", options: { allowEqual: true } }) // true
+ */
+export declare function isValidZonedRange({ value1, value2, options, }: {
+    value1: string;
+    value2: string;
+    options?: {
+        allowEqual?: boolean;
+    };
+}): boolean;

package/dist/zoned/validate/isValidZonedRange.js

@@ -0,0 +1,43 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
+/**
+ * Return true if `value1` and `value2` form a valid zoned range — both parseable as
+ * ISO ZonedDateTime strings and the instant at `value1` is <= the instant at `value2`.
+ *
+ * - Both inputs must be valid ISO 8601 zoned datetime strings.
+ * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
+ * - Comparison is done by instant, so intervals spanning DST transitions are compared
+ *   by absolute time.
+ * - Invalid input, malformed strings, or leap-second strings return `false`.
+ *
+ * @param value1 first ISO ZonedDateTime string
+ * @param value2 second ISO ZonedDateTime string
+ * @param options optional allowEqual flag
+ * @returns boolean indicating whether the zoned range is valid
+ *
+ * @example isValidZonedRange({ value1: "2024-01-01T10:00:00+00:00[UTC]", value2: "2024-12-31T23:59:59+00:00[UTC]" }) // true
+ * @example isValidZonedRange({ value1: "2024-12-31T23:59:59+00:00[UTC]", value2: "2024-01-01T10:00:00+00:00[UTC]" }) // false
+ * @example isValidZonedRange({ value1: "2024-06-15T12:00:00-04:00[America/New_York]", value2: "2024-06-15T12:00:00-04:00[America/New_York]", options: { allowEqual: true } }) // true
+ */
+export function isValidZonedRange({ value1, value2, options, }) {
+    if (typeof value1 !== "string" || typeof value2 !== "string") {
+        return false;
+    }
+    if (isLeapSecond(value1) || isLeapSecond(value2)) {
+        return false;
+    }
+    try {
+        const zdt1 = Temporal.ZonedDateTime.from(value1);
+        const zdt2 = Temporal.ZonedDateTime.from(value2);
+        const instant1 = zdt1.toInstant();
+        const instant2 = zdt2.toInstant();
+        const cmp = Temporal.Instant.compare(instant1, instant2);
+        if (options?.allowEqual) {
+            return cmp <= 0;
+        }
+        return cmp < 0;
+    }
+    catch {
+        return false;
+    }
+}