@northguild/gmt 1.15.0 → 1.17.0

package/dist/zoned/parse/parseUnitFromZoned.js

@@ -1,6 +1,9 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 function isValidZonedUnit(unit) {
     return [
         "year",
@@ -12,6 +15,7 @@ function isValidZonedUnit(unit) {
         "minute",
         "second",
         "millisecond",
+        "microsecond",
         "nanosecond",
         "timeZone",
     ].includes(unit);
@@ -19,53 +23,75 @@ function isValidZonedUnit(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".
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", "timeZone".
  * - Uses Temporal.ZonedDateTime.from to parse.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
+ * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
+ *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
  * - 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)
+ * @param optionsArg optional settings (e.g. weekStartsOn for week calculations); a non-object value (such as `null`) is invalid
  * @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("2024-02-29T12:34:56.789+00:00[UTC]", "milliseconds") // "789"
+ * @example parseUnitFromZoned("2024-12-31T12:00:00+00:00[UTC]", "week", { weekStartsOn: "sunday" }) // "1"
  * @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 "";
+        // Temporal GetOptionsObject: options are an object or omitted; null and primitives are invalid.
+        if (!isOptionsArgument(optionsArg)) {
+            return "";
+        }
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        if (!isValidZonedDateTime(value) ||
+            !isValidZonedUnit(resolvedUnit) ||
+            weekStartsOn === null) {
+            return "";
+        }
+        try {
+            const zonedDateTime = zonedDateTimeFrom(value);
+            switch (resolvedUnit) {
+                case "year":
+                    return zonedDateTime.year.toString();
+                case "month":
+                    return zonedDateTime.month.toString().padStart(2, "0");
+                case "week":
+                    return (getWeekNumber(zonedDateTime.toPlainDate().toString(), 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 "microsecond":
+                    return zonedDateTime.microsecond.toString().padStart(3, "0");
+                case "nanosecond":
+                    return zonedDateTime.nanosecond.toString().padStart(3, "0");
+                case "timeZone":
+                    return zonedDateTime.timeZoneId;
+                default:
+                    return "";
+            }
+        }
+        catch {
+            return "";
         }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,15 +1,25 @@
 /**
- * Return the week of the year (1-53) for a given ISO 8601 zoned datetime string.
+ * Return the week of the year for a given ISO 8601 zoned datetime string.
  *
- * - By default uses ISO weeks (Monday-based).
+ * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ *   first Thursday, so late-December days can be week 1 of the next year (a value on 2024-12-31
+ *   → 1). The result is 1–53.
+ * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
+ *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
+ *   next year (2024-12-31 → 1, 2000-12-30 → 53). The result is 1–53.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The week is read from the value's own date on its own wall clock.
  * - 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
+ * @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("2024-12-31T12:00:00+00:00[UTC]") // 1 (ISO week 1 of 2025)
+ * @example parseWeekFromZoned("2024-12-31T12:00:00+00:00[UTC]", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
+ * @example parseWeekFromZoned("2000-12-31T12:00:00+00:00[UTC]", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2001)
  * @example parseWeekFromZoned("invalid") // null
  */
 export declare function parseWeekFromZoned(value: string, optionsArg?: {

package/dist/zoned/parse/parseWeekFromZoned.js

@@ -1,30 +1,54 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../../plain/calculate/getWeekNumber.js";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
- * Return the week of the year (1-53) for a given ISO 8601 zoned datetime string.
+ * Return the week of the year for a given ISO 8601 zoned datetime string.
  *
- * - By default uses ISO weeks (Monday-based).
+ * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ *   first Thursday, so late-December days can be week 1 of the next year (a value on 2024-12-31
+ *   → 1). The result is 1–53.
+ * - `"sunday"` is the UTS #35 week of the week-year with a Sunday first day and minimal days 1:
+ *   week 1 is the Sunday-first week holding 1 January, so late-December days can be week 1 of the
+ *   next year (2024-12-31 → 1, 2000-12-30 → 53). The result is 1–53.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The week is read from the value's own date on its own wall clock.
  * - 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
+ * @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("2024-12-31T12:00:00+00:00[UTC]") // 1 (ISO week 1 of 2025)
+ * @example parseWeekFromZoned("2024-12-31T12:00:00+00:00[UTC]", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
+ * @example parseWeekFromZoned("2000-12-31T12:00:00+00:00[UTC]", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2001)
  * @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);
+        if (!isOptionsArgument(optionsArg)) {
+            return null;
+        }
+        if (!isValidZonedDateTime(value)) {
+            return null;
+        }
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        if (weekStartsOn === null)
+            return null;
+        try {
+            const zonedDateTime = zonedDateTimeFrom(value);
+            return getWeekNumber(zonedDateTime.toPlainDate().toString(), weekStartsOn);
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/zoned/parse/parseYearFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the year for a given ISO 8601 zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function parseYearFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime.year.toString();
     }
     catch {

package/dist/zoned/validate/hasDaylightSaving.js

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Check whether an IANA timeZone identifier observes daylight saving time.
  *
@@ -17,7 +17,7 @@ import { Temporal } from "@js-temporal/polyfill";
  */
 export function hasDaylightSaving(timeZone) {
     try {
-        const zdtJanuary = Temporal.ZonedDateTime.from({
+        const zdtJanuary = zonedDateTimeFrom({
             year: 2024,
             month: 1,
             day: 15,
@@ -26,7 +26,7 @@ export function hasDaylightSaving(timeZone) {
             second: 0,
             timeZone,
         });
-        const zdtJuly = Temporal.ZonedDateTime.from({
+        const zdtJuly = zonedDateTimeFrom({
             year: 2024,
             month: 7,
             day: 15,

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

@@ -1,30 +1,45 @@
 /**
  * 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`.
+ * ("2024-10-03T14:30:45-04:00[America/New_York]") or an RFC 9557 calendar-annotated one
+ * ("2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]"), as
+ * `Temporal.ZonedDateTime#toString()` and `convertZonedToCalendar` write it.
  *
- * - 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).
+ * - Parallel to `isValidZonedDateTime`, which accepts `[u-ca=iso8601]` and rejects every other
+ *   calendar. Only
+ *   the calendar-aware `zoned/` functions gate on this validator, so a string is never certified
+ *   by a validator whose own namespace refuses it.
+ * - The calendar annotation follows the time zone annotation (RFC 9557 §4.1); a calendar before
+ *   the zone, which Temporal also rejects, returns false.
+ * - A `[u-ca=<id>]` annotation, optionally critical. Temporal's `CanonicalizeCalendar` validates
+ *   the id (folding case and aliases), and the calendar must be one GMT supports
+ *   (`CalendarSystem`).
+ * - The annotations follow Temporal's ISO grammar, as `Temporal.ZonedDateTime.from` reads them:
+ *   elective unknown annotations (`[foo=bar]`) are ignored and the first `u-ca` annotation names
+ *   the calendar; an unknown critical annotation or a second `u-ca` annotation when either is
+ *   critical returns false.
+ * - The part before the first annotation must be ISO 8601 extended format, as
+ *   `isValidZonedDateTime` requires: basic format, a space or lower-case `t` separator, a
+ *   lower-case `z`, an hour-only time or offset and a date without a time return false.
  * - 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.
+ * - Delegates the date, time, offset, zone and annotation checks to `Temporal.ZonedDateTime.from`
+ *   (via `parseCalendarZonedValue`).
  * - Returns false for non-strings or empty strings.
  *
+ * Compatibility: since 1.16.0 the string is RFC 9557. Earlier releases accepted calendar-native
+ * digits, `;era=`, the calendar annotation before the zone, and the ids `gregorian`, `taiwan`,
+ * `islamic-tabular` and `ethiopic-amete-alem`.
+ *
  * @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-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]") // true
+ * @example isValidCalendarZonedDateTime("2024-02-24T14:30:00-05:00[America/New_York][foo=bar][u-ca=hebrew]") // true (elective annotation ignored)
+ * @example isValidCalendarZonedDateTime("2024-02-24T14:30:00-05:00[u-ca=hebrew][America/New_York]") // false (calendar before zone)
+ * @example isValidCalendarZonedDateTime("2019-04-30T12:00:00+09:00[Asia/Tokyo][u-ca=japanese;era=heisei]") // false (not RFC 9557)
+ * @example isValidCalendarZonedDateTime("2024-02-24T14:30:00+03:00[America/New_York][u-ca=hebrew]") // false (offset wrong for the zone)
  * @example isValidCalendarZonedDateTime("2024-06-30T23:59:60+00:00[UTC]") // false (leap second)
+ * @example isValidCalendarZonedDateTime("2024-02-24 14:30:00-05:00[America/New_York][u-ca=hebrew]") // false (space separator)
  * @example isValidCalendarZonedDateTime("invalid") // false
  */
 export declare function isValidCalendarZonedDateTime(value: string): boolean;

package/dist/zoned/validate/isValidCalendarZonedDateTime.js

@@ -1,31 +1,46 @@
 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`.
+ * ("2024-10-03T14:30:45-04:00[America/New_York]") or an RFC 9557 calendar-annotated one
+ * ("2024-10-03T14:30:45-04:00[America/New_York][u-ca=hebrew]"), as
+ * `Temporal.ZonedDateTime#toString()` and `convertZonedToCalendar` write it.
  *
- * - 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).
+ * - Parallel to `isValidZonedDateTime`, which accepts `[u-ca=iso8601]` and rejects every other
+ *   calendar. Only
+ *   the calendar-aware `zoned/` functions gate on this validator, so a string is never certified
+ *   by a validator whose own namespace refuses it.
+ * - The calendar annotation follows the time zone annotation (RFC 9557 §4.1); a calendar before
+ *   the zone, which Temporal also rejects, returns false.
+ * - A `[u-ca=<id>]` annotation, optionally critical. Temporal's `CanonicalizeCalendar` validates
+ *   the id (folding case and aliases), and the calendar must be one GMT supports
+ *   (`CalendarSystem`).
+ * - The annotations follow Temporal's ISO grammar, as `Temporal.ZonedDateTime.from` reads them:
+ *   elective unknown annotations (`[foo=bar]`) are ignored and the first `u-ca` annotation names
+ *   the calendar; an unknown critical annotation or a second `u-ca` annotation when either is
+ *   critical returns false.
+ * - The part before the first annotation must be ISO 8601 extended format, as
+ *   `isValidZonedDateTime` requires: basic format, a space or lower-case `t` separator, a
+ *   lower-case `z`, an hour-only time or offset and a date without a time return false.
  * - 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.
+ * - Delegates the date, time, offset, zone and annotation checks to `Temporal.ZonedDateTime.from`
+ *   (via `parseCalendarZonedValue`).
  * - Returns false for non-strings or empty strings.
  *
+ * Compatibility: since 1.16.0 the string is RFC 9557. Earlier releases accepted calendar-native
+ * digits, `;era=`, the calendar annotation before the zone, and the ids `gregorian`, `taiwan`,
+ * `islamic-tabular` and `ethiopic-amete-alem`.
+ *
  * @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-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]") // true
+ * @example isValidCalendarZonedDateTime("2024-02-24T14:30:00-05:00[America/New_York][foo=bar][u-ca=hebrew]") // true (elective annotation ignored)
+ * @example isValidCalendarZonedDateTime("2024-02-24T14:30:00-05:00[u-ca=hebrew][America/New_York]") // false (calendar before zone)
+ * @example isValidCalendarZonedDateTime("2019-04-30T12:00:00+09:00[Asia/Tokyo][u-ca=japanese;era=heisei]") // false (not RFC 9557)
+ * @example isValidCalendarZonedDateTime("2024-02-24T14:30:00+03:00[America/New_York][u-ca=hebrew]") // false (offset wrong for the zone)
  * @example isValidCalendarZonedDateTime("2024-06-30T23:59:60+00:00[UTC]") // false (leap second)
+ * @example isValidCalendarZonedDateTime("2024-02-24 14:30:00-05:00[America/New_York][u-ca=hebrew]") // false (space separator)
  * @example isValidCalendarZonedDateTime("invalid") // false
  */
 export function isValidCalendarZonedDateTime(value) {

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

@@ -1,9 +1,17 @@
 /**
- * Validate whether a string is a valid IANA timeZone identifier.
+ * Validate whether a string is a valid time zone identifier: an IANA name or a UTC offset.
  *
  * - Uses Temporal.ZonedDateTime.from to test timezone validity.
- * - Uses regex to check format.
+ * - Uses the `timeZoneLike` regex to check the identifier's shape: Temporal's
+ *   `TimeZoneIdentifier` grammar (§14.6.2).
+ * - Accepts every IANA Zone and Link name the runtime accepts, including single-component names
+ *   (`UTC`, `Japan`, `Zulu`, `EST5EDT`, `GMT+0`), in any letter case (ECMA-402 matches
+ *   identifiers ASCII-case-insensitively, so `utc` is as valid as `america/new_york`).
+ * - Accepts an offset identifier (`UTCOffset[~SubMinutePrecision]`): `"+05:00"`, `"+0530"`,
+ *   `"-08"`, hour `00`–`23`, no seconds. Temporal and `Intl.DateTimeFormat` accept the same ones.
  * - Returns false for invalid timezone formats.
+ * - Compatibility: earlier releases required a `/` in every name except `UTC` and `GMT`. To keep
+ *   that narrower rule, also require `timeZone.includes("/")` or `"UTC"`/`"GMT"`.
  *
  * @param timeZone timeZone identifier to validate
  * @returns boolean indicating validity
@@ -11,5 +19,10 @@
  * @example isValidTimeZone("America/New_York") // true
  * @example isValidTimeZone("Europe/London") // true
  * @example isValidTimeZone("Invalid/Timezone") // false
+ * @example isValidTimeZone("Japan") // true (IANA link to Asia/Tokyo)
+ * @example isValidTimeZone("utc") // true (case-insensitive)
+ * @example isValidTimeZone("+05:00") // true (an offset identifier)
+ * @example isValidTimeZone("+05:00:00") // false (no seconds in an offset identifier)
+ * @example "Japan".includes("/") // false (the earlier slash-only rule)
  */
 export declare function isValidTimeZone(timeZone: string): boolean;

package/dist/zoned/validate/isValidTimeZone.js

@@ -1,11 +1,19 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { timeZoneLike } from "../../regex/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
- * Validate whether a string is a valid IANA timeZone identifier.
+ * Validate whether a string is a valid time zone identifier: an IANA name or a UTC offset.
  *
  * - Uses Temporal.ZonedDateTime.from to test timezone validity.
- * - Uses regex to check format.
+ * - Uses the `timeZoneLike` regex to check the identifier's shape: Temporal's
+ *   `TimeZoneIdentifier` grammar (§14.6.2).
+ * - Accepts every IANA Zone and Link name the runtime accepts, including single-component names
+ *   (`UTC`, `Japan`, `Zulu`, `EST5EDT`, `GMT+0`), in any letter case (ECMA-402 matches
+ *   identifiers ASCII-case-insensitively, so `utc` is as valid as `america/new_york`).
+ * - Accepts an offset identifier (`UTCOffset[~SubMinutePrecision]`): `"+05:00"`, `"+0530"`,
+ *   `"-08"`, hour `00`–`23`, no seconds. Temporal and `Intl.DateTimeFormat` accept the same ones.
  * - Returns false for invalid timezone formats.
+ * - Compatibility: earlier releases required a `/` in every name except `UTC` and `GMT`. To keep
+ *   that narrower rule, also require `timeZone.includes("/")` or `"UTC"`/`"GMT"`.
  *
  * @param timeZone timeZone identifier to validate
  * @returns boolean indicating validity
@@ -13,10 +21,15 @@ import { timeZoneLike } from "../../regex/index.js";
  * @example isValidTimeZone("America/New_York") // true
  * @example isValidTimeZone("Europe/London") // true
  * @example isValidTimeZone("Invalid/Timezone") // false
+ * @example isValidTimeZone("Japan") // true (IANA link to Asia/Tokyo)
+ * @example isValidTimeZone("utc") // true (case-insensitive)
+ * @example isValidTimeZone("+05:00") // true (an offset identifier)
+ * @example isValidTimeZone("+05:00:00") // false (no seconds in an offset identifier)
+ * @example "Japan".includes("/") // false (the earlier slash-only rule)
  */
 export function isValidTimeZone(timeZone) {
     try {
-        Temporal.ZonedDateTime.from({
+        zonedDateTimeFrom({
             year: 2020,
             month: 2,
             day: 28,

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

@@ -1,14 +1,16 @@
 /**
  * Validate whether a string is a valid ISO 8601 zoned datetime string.
  *
+ * - The part before the first annotation must be ISO 8601 extended format: `<date>T<time>`, then
+ *   nothing, `Z`, or a `±HH:MM[:SS[.fraction]]` offset. Basic format (`20241003T143000-0400`), a
+ *   space or lower-case `t` separator, a lower-case `z`, an hour-only time or offset, and a date
+ *   without a time are rejected, although `Temporal.ZonedDateTime.from` reads them.
  * - 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.
+ * - Reads RFC 9557 annotations as `Temporal.ZonedDateTime.from` does: elective ones
+ *   (`[foo=bar]`) are ignored and an unknown critical one (`[!foo=bar]`) is rejected.
+ * - The calendar must be ISO: `[u-ca=iso8601]` is accepted, and a non-ISO calendar annotation is
+ *   `isValidCalendarZonedDateTime`'s input.
  * - Returns false for non-strings or empty strings.
  *
  * @param value candidate zoned datetime string
@@ -16,7 +18,12 @@
  *
  * @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("2024-02-10T12:00:00-05:00[America/New_York][u-ca=hebrew]") // false (non-ISO calendar: use isValidCalendarZonedDateTime)
+ * @example isValidZonedDateTime("2024-02-10T12:00:00-05:00[America/New_York][u-ca=iso8601]") // true
+ * @example isValidZonedDateTime("2024-02-10T12:00:00-05:00[America/New_York][foo=bar]") // true (elective annotation ignored)
+ * @example isValidZonedDateTime("20241003T143000-0400[America/New_York]") // false (basic format)
+ * @example isValidZonedDateTime("2024-10-03 14:30:00-04:00[America/New_York]") // false (space separator)
+ * @example isValidZonedDateTime("2024-10-03[America/New_York]") // false (no time)
  * @example isValidZonedDateTime("invalid") // false
  */
 export declare function isValidZonedDateTime(value: string): boolean;

package/dist/zoned/validate/isValidZonedDateTime.js

@@ -1,17 +1,19 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { hasCalendarAnnotation } from "../../internal/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
+import { hasZonedDateTimeShape } from "../../internal/isoStringBody.js";
 import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
 /**
  * Validate whether a string is a valid ISO 8601 zoned datetime string.
  *
+ * - The part before the first annotation must be ISO 8601 extended format: `<date>T<time>`, then
+ *   nothing, `Z`, or a `±HH:MM[:SS[.fraction]]` offset. Basic format (`20241003T143000-0400`), a
+ *   space or lower-case `t` separator, a lower-case `z`, an hour-only time or offset, and a date
+ *   without a time are rejected, although `Temporal.ZonedDateTime.from` reads them.
  * - 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.
+ * - Reads RFC 9557 annotations as `Temporal.ZonedDateTime.from` does: elective ones
+ *   (`[foo=bar]`) are ignored and an unknown critical one (`[!foo=bar]`) is rejected.
+ * - The calendar must be ISO: `[u-ca=iso8601]` is accepted, and a non-ISO calendar annotation is
+ *   `isValidCalendarZonedDateTime`'s input.
  * - Returns false for non-strings or empty strings.
  *
  * @param value candidate zoned datetime string
@@ -19,19 +21,25 @@ import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
  *
  * @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("2024-02-10T12:00:00-05:00[America/New_York][u-ca=hebrew]") // false (non-ISO calendar: use isValidCalendarZonedDateTime)
+ * @example isValidZonedDateTime("2024-02-10T12:00:00-05:00[America/New_York][u-ca=iso8601]") // true
+ * @example isValidZonedDateTime("2024-02-10T12:00:00-05:00[America/New_York][foo=bar]") // true (elective annotation ignored)
+ * @example isValidZonedDateTime("20241003T143000-0400[America/New_York]") // false (basic format)
+ * @example isValidZonedDateTime("2024-10-03 14:30:00-04:00[America/New_York]") // false (space separator)
+ * @example isValidZonedDateTime("2024-10-03[America/New_York]") // false (no time)
  * @example isValidZonedDateTime("invalid") // false
  */
 export function isValidZonedDateTime(value) {
     if (typeof value !== "string" || value.length === 0) {
         return false;
     }
-    if (isLeapSecond(value) || hasCalendarAnnotation(value)) {
+    if (isLeapSecond(value) || !hasZonedDateTimeShape(value)) {
         return false;
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
-        return zonedDateTime.timeZoneId.length > 0;
+        const zonedDateTime = zonedDateTimeFrom(value);
+        return (zonedDateTime.timeZoneId.length > 0 &&
+            zonedDateTime.calendarId === "iso8601");
     }
     catch {
         return false;

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

@@ -2,11 +2,15 @@
  * 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.
+ * - Both inputs must be valid ISO 8601 zoned datetime strings in extended format, as
+ *   `isValidZonedDateTime` requires: basic format, a space or lower-case `t` separator, a
+ *   lower-case `z` and a date without a time return `false`.
  * - 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`.
+ * - Annotations are read as `isValidZonedDateTime` reads them: elective ones are ignored,
+ *   `[u-ca=iso8601]` is accepted, and a non-ISO calendar on either endpoint returns `false`.
  *
  * @param value1 first ISO ZonedDateTime string
  * @param value2 second ISO ZonedDateTime string
@@ -16,8 +20,11 @@
  * @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
+ * @example isValidZonedRange({ value1: "2024-01-01T00:00:00+00:00[UTC][u-ca=hebrew]", value2: "2024-02-01T00:00:00+00:00[UTC]" }) // false (non-ISO calendar)
+ * @example isValidZonedRange({ value1: "2024-01-01T00:00:00+00:00[UTC][u-ca=iso8601]", value2: "2024-02-01T00:00:00+00:00[UTC]" }) // true
+ * @example isValidZonedRange({ value1: "2024-01-01 10:00:00+00:00[UTC]", value2: "2024-12-31T23:59:59+00:00[UTC]" }) // false (space separator)
  */
-export declare function isValidZonedRange({ value1, value2, options, }: {
+export declare function isValidZonedRange(props: {
     value1: string;
     value2: string;
     options?: {