@northguild/gmt 1.17.0 → 1.19.0

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

@@ -1,13 +1,15 @@
 /**
  * Return the year for a given ISO 8601 zoned datetime string.
  *
- * - Returns string for year.
+ * - Returns the year as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  * - Returns "" for invalid input.
  *
  * @param value ISO zoned datetime string
- * @returns Year as string or "" on invalid input
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "2024"
+ * @example parseYearFromZoned("0005-06-01T12:30:00+00:00[UTC]") // "0005"
  * @example parseYearFromZoned("invalid") // ""
  */
 export declare function parseYearFromZoned(value: string): string;

package/dist/zoned/parse/parseYearFromZoned.js

@@ -1,15 +1,18 @@
 import { isValidZonedDateTime } from "../validate/index.js";
 import { zonedDateTimeFrom } from "../../internal/index.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Return the year for a given ISO 8601 zoned datetime string.
  *
- * - Returns string for year.
+ * - Returns the year as Temporal writes it: four digits (`"2024"`, `"0005"`), or a sign and six
+ *   digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  * - Returns "" for invalid input.
  *
  * @param value ISO zoned datetime string
- * @returns Year as string or "" on invalid input
+ * @returns the year as four digits, or a sign and six digits outside 0000–9999, or "" on invalid input
  *
  * @example parseYearFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "2024"
+ * @example parseYearFromZoned("0005-06-01T12:30:00+00:00[UTC]") // "0005"
  * @example parseYearFromZoned("invalid") // ""
  */
 export function parseYearFromZoned(value) {
@@ -18,7 +21,7 @@ export function parseYearFromZoned(value) {
     }
     try {
         const zonedDateTime = zonedDateTimeFrom(value);
-        return zonedDateTime.year.toString();
+        return isoYearString(zonedDateTime.year);
     }
     catch {
         return "";

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

@@ -1,17 +1,50 @@
 /**
- * Check whether an IANA timeZone identifier observes daylight saving time.
+ * Check whether a timeZone observes daylight saving time at a reference instant.
  *
- * - 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.
+ * - True when the zone is in daylight time at the reference instant, or a daylight period begins
+ *   less than 365 days after it. So a zone in its winter is true, and a zone that has stopped
+ *   changing its clocks is false.
+ * - With `options.at` the answer does not depend on the day the code runs.
+ * - The rule is GMT's own definition, not the tz database's daylight flag, which no JavaScript
+ *   API exposes: daylight time runs from a forward change of the zone's clocks to the backward
+ *   change of the same size that undoes it, less than 365 days later.
+ * - Read as standard time, because the offsets do not show otherwise: the last summer before a
+ *   zone kept its daylight offset for good; a daylight period held 365 days or longer; one that
+ *   began, ended or was interrupted by a move of standard time, so the offset changes part-way
+ *   through and the rest, or all, of it is not paired (`Asia/Tomsk` 2002); and one whose end is
+ *   past the last instant Temporal can represent.
+ * - A forward change never undone is a change of standard time: `Europe/Istanbul` is false from
+ *   2016 on, although its clocks went forward in March 2016.
+ * - Read from the runtime's time zone data, so the answer can change when that data does.
+ * - Returns false for an invalid timeZone, an invalid `at`, an options argument that is not an
+ *   object, and a fixed UTC offset, with or without seconds (`"+05:30"`, `"-00:44:30"`).
  *
- * @param timeZone timeZone identifier to check
- * @returns boolean indicating whether the timeZone observes DST
+ * @param timeZone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or a
+ *   stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
+ * @param options optional setting for the reference instant
+ * @returns boolean indicating whether the timeZone observes DST, or false on invalid input
  *
- * @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
+ * @example hasDaylightSaving("America/New_York", { at: "2024-01-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("Australia/Sydney", { at: "2024-06-15T12:00:00Z" }) // true (winter; the next period begins in October)
+ * @example hasDaylightSaving("Asia/Tokyo", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("Europe/Istanbul", { at: "2015-06-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("Europe/Istanbul", { at: "2016-06-15T12:00:00Z" }) // false (the March 2016 advance was never undone)
+ * @example hasDaylightSaving("America/Sao_Paulo", { at: "2018-06-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("America/Sao_Paulo", { at: "2019-06-15T12:00:00Z" }) // false (last daylight period ended 2019-02-17)
+ * @example hasDaylightSaving("UTC", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("+05:00", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("Invalid/Zone", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("America/New_York", { at: "2024-01-15" }) // false (not an instant)
+ * @example hasDaylightSaving("-00:44:30", { at: "1970-01-01T12:00:00Z" }) // false (a fixed offset)
  */
-export declare function hasDaylightSaving(timeZone: string): boolean;
+export declare function hasDaylightSaving(timeZone: string, options?: {
+    /**
+     * The reference instant the zone is judged at, as an ISO 8601 instant string ending in `Z`, an
+     * offset or a bracketed zone. It only names an instant, as `isValidInstant` reads it: a
+     * bracketed zone is not validated and does not replace `timeZone`. An invalid value returns
+     * false.
+     *
+     * @defaultValue The current instant.
+     */
+    at?: string;
+}): boolean;

package/dist/zoned/validate/hasDaylightSaving.js

@@ -1,41 +1,63 @@
-import { zonedDateTimeFrom } from "../../internal/index.js";
+import { Temporal } from "@js-temporal/polyfill";
+import { isOptionsArgument, observesDaylightTime, parseInstantNanoseconds, zoneFrame, } from "../../internal/index.js";
 /**
- * Check whether an IANA timeZone identifier observes daylight saving time.
+ * Check whether a timeZone observes daylight saving time at a reference instant.
  *
- * - 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.
+ * - True when the zone is in daylight time at the reference instant, or a daylight period begins
+ *   less than 365 days after it. So a zone in its winter is true, and a zone that has stopped
+ *   changing its clocks is false.
+ * - With `options.at` the answer does not depend on the day the code runs.
+ * - The rule is GMT's own definition, not the tz database's daylight flag, which no JavaScript
+ *   API exposes: daylight time runs from a forward change of the zone's clocks to the backward
+ *   change of the same size that undoes it, less than 365 days later.
+ * - Read as standard time, because the offsets do not show otherwise: the last summer before a
+ *   zone kept its daylight offset for good; a daylight period held 365 days or longer; one that
+ *   began, ended or was interrupted by a move of standard time, so the offset changes part-way
+ *   through and the rest, or all, of it is not paired (`Asia/Tomsk` 2002); and one whose end is
+ *   past the last instant Temporal can represent.
+ * - A forward change never undone is a change of standard time: `Europe/Istanbul` is false from
+ *   2016 on, although its clocks went forward in March 2016.
+ * - Read from the runtime's time zone data, so the answer can change when that data does.
+ * - Returns false for an invalid timeZone, an invalid `at`, an options argument that is not an
+ *   object, and a fixed UTC offset, with or without seconds (`"+05:30"`, `"-00:44:30"`).
  *
- * @param timeZone timeZone identifier to check
- * @returns boolean indicating whether the timeZone observes DST
+ * @param timeZone IANA name or UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or a
+ *   stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
+ * @param options optional setting for the reference instant
+ * @returns boolean indicating whether the timeZone observes DST, or false on invalid input
  *
- * @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
+ * @example hasDaylightSaving("America/New_York", { at: "2024-01-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("Australia/Sydney", { at: "2024-06-15T12:00:00Z" }) // true (winter; the next period begins in October)
+ * @example hasDaylightSaving("Asia/Tokyo", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("Europe/Istanbul", { at: "2015-06-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("Europe/Istanbul", { at: "2016-06-15T12:00:00Z" }) // false (the March 2016 advance was never undone)
+ * @example hasDaylightSaving("America/Sao_Paulo", { at: "2018-06-15T12:00:00Z" }) // true
+ * @example hasDaylightSaving("America/Sao_Paulo", { at: "2019-06-15T12:00:00Z" }) // false (last daylight period ended 2019-02-17)
+ * @example hasDaylightSaving("UTC", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("+05:00", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("Invalid/Zone", { at: "2024-01-15T12:00:00Z" }) // false
+ * @example hasDaylightSaving("America/New_York", { at: "2024-01-15" }) // false (not an instant)
+ * @example hasDaylightSaving("-00:44:30", { at: "1970-01-01T12:00:00Z" }) // false (a fixed offset)
  */
-export function hasDaylightSaving(timeZone) {
+export function hasDaylightSaving(timeZone, options) {
+    const frame = zoneFrame(timeZone);
+    // A stored offset with seconds is a fixed offset: it observes no daylight time, as "-00:45"
+    // observes none.
+    if (frame === null ||
+        frame.shiftNanoseconds !== 0n ||
+        !isOptionsArgument(options)) {
+        return false;
+    }
     try {
-        const zdtJanuary = zonedDateTimeFrom({
-            year: 2024,
-            month: 1,
-            day: 15,
-            hour: 12,
-            minute: 0,
-            second: 0,
-            timeZone,
-        });
-        const zdtJuly = zonedDateTimeFrom({
-            year: 2024,
-            month: 7,
-            day: 15,
-            hour: 12,
-            minute: 0,
-            second: 0,
-            timeZone,
-        });
-        return zdtJanuary.offsetNanoseconds !== zdtJuly.offsetNanoseconds;
+        const at = options?.at;
+        if (at === undefined) {
+            return observesDaylightTime(Temporal.Now.zonedDateTimeISO(frame.timeZone));
+        }
+        const epochNanoseconds = parseInstantNanoseconds(at);
+        if (epochNanoseconds === null) {
+            return false;
+        }
+        return observesDaylightTime(Temporal.Instant.fromEpochNanoseconds(epochNanoseconds).toZonedDateTimeISO(frame.timeZone));
     }
     catch {
         return false;

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

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

package/dist/zoned/validate/index.js

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

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

@@ -0,0 +1,32 @@
+/**
+ * Return true when `value` is a real RFC 5322 (RFC 2822) date-time: the date an email `Date:`
+ * header carries, such as `Fri, 15 Mar 2024 14:30:00 -0400`.
+ *
+ * - True exactly when `parseRfc2822` returns a zoned string for the same value: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - **Reads what a conformant receiver must**, which is more than the strict `rfc2822DateTime`
+ *   pattern matches: RFC 5322 §3.3 folding white space, comments, names in any case and a year of
+ *   more than four digits, and the §4 obsolete syntax (2- and 3-digit years, military and other
+ *   alphabetic zones). `parseRfc2822` lists each form.
+ * - Checks the calendar as well as the shape. The pattern matches a day that does not exist:
+ *   `31 Feb`, `29 Feb 2023` and `31 Jun` are false here.
+ * - **The day-of-week must match the date.** RFC 5322 §3.3: "the day-of-week (if included) MUST be
+ *   the day implied by the date". The pattern does not check it.
+ * - False for an hour above 23, a minute above 59, zone minutes above 59 and an offset of 24
+ *   hours or more, all of which the pattern matches. False for a second of 60: GMT rejects leap
+ *   seconds.
+ * - False for a non-string. Read the value with `parseRfc2822`; write one with `formatRfc2822`.
+ *
+ * @param value candidate RFC 5322 date-time string
+ * @returns boolean indicating validity
+ *
+ * @example isValidRfc2822DateTime("Fri, 15 Mar 2024 14:30:00 -0400") // true
+ * @example isValidRfc2822DateTime("5 Jan 2024 09:00:00 GMT") // true (no day-of-week, 1-digit day)
+ * @example isValidRfc2822DateTime("fri,15 Mar 24 14:30 -0400 (EDT)") // true (obsolete 2-digit year, comment; the rfc2822DateTime pattern does not match it)
+ * @example isValidRfc2822DateTime("Sat, 15 Mar 2024 14:30:00 -0400") // false (15 Mar 2024 was a Friday; the rfc2822DateTime pattern matches it)
+ * @example isValidRfc2822DateTime("Wed, 29 Feb 2023 14:30:00 -0400") // false (2023 has no 29 February; the rfc2822DateTime pattern matches it)
+ * @example isValidRfc2822DateTime("Fri, 15 Mar 2024 14:30:00 -0460") // false (zone minutes above 59; the rfc2822DateTime pattern matches it)
+ * @example isValidRfc2822DateTime("Fri, 15 Mar 2024 14:30:00") // false (no zone)
+ * @example isValidRfc2822DateTime("not a date") // false
+ */
+export declare function isValidRfc2822DateTime(value: string): boolean;

package/dist/zoned/validate/isValidRfc2822DateTime.js

@@ -0,0 +1,35 @@
+import { parseRfc2822 } from "../parse/parseRfc2822.js";
+/**
+ * Return true when `value` is a real RFC 5322 (RFC 2822) date-time: the date an email `Date:`
+ * header carries, such as `Fri, 15 Mar 2024 14:30:00 -0400`.
+ *
+ * - True exactly when `parseRfc2822` returns a zoned string for the same value: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - **Reads what a conformant receiver must**, which is more than the strict `rfc2822DateTime`
+ *   pattern matches: RFC 5322 §3.3 folding white space, comments, names in any case and a year of
+ *   more than four digits, and the §4 obsolete syntax (2- and 3-digit years, military and other
+ *   alphabetic zones). `parseRfc2822` lists each form.
+ * - Checks the calendar as well as the shape. The pattern matches a day that does not exist:
+ *   `31 Feb`, `29 Feb 2023` and `31 Jun` are false here.
+ * - **The day-of-week must match the date.** RFC 5322 §3.3: "the day-of-week (if included) MUST be
+ *   the day implied by the date". The pattern does not check it.
+ * - False for an hour above 23, a minute above 59, zone minutes above 59 and an offset of 24
+ *   hours or more, all of which the pattern matches. False for a second of 60: GMT rejects leap
+ *   seconds.
+ * - False for a non-string. Read the value with `parseRfc2822`; write one with `formatRfc2822`.
+ *
+ * @param value candidate RFC 5322 date-time string
+ * @returns boolean indicating validity
+ *
+ * @example isValidRfc2822DateTime("Fri, 15 Mar 2024 14:30:00 -0400") // true
+ * @example isValidRfc2822DateTime("5 Jan 2024 09:00:00 GMT") // true (no day-of-week, 1-digit day)
+ * @example isValidRfc2822DateTime("fri,15 Mar 24 14:30 -0400 (EDT)") // true (obsolete 2-digit year, comment; the rfc2822DateTime pattern does not match it)
+ * @example isValidRfc2822DateTime("Sat, 15 Mar 2024 14:30:00 -0400") // false (15 Mar 2024 was a Friday; the rfc2822DateTime pattern matches it)
+ * @example isValidRfc2822DateTime("Wed, 29 Feb 2023 14:30:00 -0400") // false (2023 has no 29 February; the rfc2822DateTime pattern matches it)
+ * @example isValidRfc2822DateTime("Fri, 15 Mar 2024 14:30:00 -0460") // false (zone minutes above 59; the rfc2822DateTime pattern matches it)
+ * @example isValidRfc2822DateTime("Fri, 15 Mar 2024 14:30:00") // false (no zone)
+ * @example isValidRfc2822DateTime("not a date") // false
+ */
+export function isValidRfc2822DateTime(value) {
+    return parseRfc2822(value) !== "";
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Return true when `value` is a real RFC 3339 date-time: an ISO 8601 date and time that always
+ * states its UTC offset, as `Z` or `±HH:MM` (RFC 3339 §5.6).
+ *
+ * - True exactly when `parseRfc3339` returns a zoned string for the same value: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - Checks the calendar as well as the shape. The `rfc3339DateTime` pattern proves the shape
+ *   alone, so it matches a day that does not exist: 29 February in a common year and 31 June are
+ *   false here.
+ * - Accepts `T`, `t` or a single space between the date and the time, `Z` or `z`, a numeric
+ *   offset from `-23:59` to `+23:59`, and up to nine fraction digits.
+ * - False for a leap second (`:60`), although §5.6 `time-second` admits it: GMT rejects leap
+ *   seconds because Temporal would read one as `:59`.
+ * - False for GMT's own zoned strings, which carry a bracketed zone (`...+00:00[UTC]`): that
+ *   annotation is not RFC 3339. Check those with `isValidZonedDateTime`.
+ * - False for a non-string. Read the value with `parseRfc3339`; write one with `formatRfc3339`.
+ *
+ * @param value candidate RFC 3339 date-time string
+ * @returns boolean indicating validity
+ *
+ * @example isValidRfc3339DateTime("2024-03-15T14:30:00-04:00") // true
+ * @example isValidRfc3339DateTime("2024-03-15t14:30:00z") // true (lower-case t and z)
+ * @example isValidRfc3339DateTime("2024-03-15 14:30:00.5Z") // true (space separator, fraction)
+ * @example isValidRfc3339DateTime("2023-02-29T10:00:00Z") // false (2023 has no 29 February; the rfc3339DateTime pattern matches it)
+ * @example isValidRfc3339DateTime("2024-06-31T10:00:00Z") // false (June has 30 days; the rfc3339DateTime pattern matches it)
+ * @example isValidRfc3339DateTime("2016-12-31T23:59:60Z") // false (leap second)
+ * @example isValidRfc3339DateTime("2024-03-15T14:30:00") // false (no offset)
+ * @example isValidRfc3339DateTime("2024-03-15T14:30:00+00:00[UTC]") // false (bracketed zone: use isValidZonedDateTime)
+ * @example isValidRfc3339DateTime("not a date") // false
+ */
+export declare function isValidRfc3339DateTime(value: string): boolean;

package/dist/zoned/validate/isValidRfc3339DateTime.js

@@ -0,0 +1,34 @@
+import { parseRfc3339 } from "../parse/parseRfc3339.js";
+/**
+ * Return true when `value` is a real RFC 3339 date-time: an ISO 8601 date and time that always
+ * states its UTC offset, as `Z` or `±HH:MM` (RFC 3339 §5.6).
+ *
+ * - True exactly when `parseRfc3339` returns a zoned string for the same value: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - Checks the calendar as well as the shape. The `rfc3339DateTime` pattern proves the shape
+ *   alone, so it matches a day that does not exist: 29 February in a common year and 31 June are
+ *   false here.
+ * - Accepts `T`, `t` or a single space between the date and the time, `Z` or `z`, a numeric
+ *   offset from `-23:59` to `+23:59`, and up to nine fraction digits.
+ * - False for a leap second (`:60`), although §5.6 `time-second` admits it: GMT rejects leap
+ *   seconds because Temporal would read one as `:59`.
+ * - False for GMT's own zoned strings, which carry a bracketed zone (`...+00:00[UTC]`): that
+ *   annotation is not RFC 3339. Check those with `isValidZonedDateTime`.
+ * - False for a non-string. Read the value with `parseRfc3339`; write one with `formatRfc3339`.
+ *
+ * @param value candidate RFC 3339 date-time string
+ * @returns boolean indicating validity
+ *
+ * @example isValidRfc3339DateTime("2024-03-15T14:30:00-04:00") // true
+ * @example isValidRfc3339DateTime("2024-03-15t14:30:00z") // true (lower-case t and z)
+ * @example isValidRfc3339DateTime("2024-03-15 14:30:00.5Z") // true (space separator, fraction)
+ * @example isValidRfc3339DateTime("2023-02-29T10:00:00Z") // false (2023 has no 29 February; the rfc3339DateTime pattern matches it)
+ * @example isValidRfc3339DateTime("2024-06-31T10:00:00Z") // false (June has 30 days; the rfc3339DateTime pattern matches it)
+ * @example isValidRfc3339DateTime("2016-12-31T23:59:60Z") // false (leap second)
+ * @example isValidRfc3339DateTime("2024-03-15T14:30:00") // false (no offset)
+ * @example isValidRfc3339DateTime("2024-03-15T14:30:00+00:00[UTC]") // false (bracketed zone: use isValidZonedDateTime)
+ * @example isValidRfc3339DateTime("not a date") // false
+ */
+export function isValidRfc3339DateTime(value) {
+    return parseRfc3339(value) !== "";
+}

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

@@ -3,7 +3,7 @@
  *
  * - Uses Temporal.ZonedDateTime.from to test timezone validity.
  * - Uses the `timeZoneLike` regex to check the identifier's shape: Temporal's
- *   `TimeZoneIdentifier` grammar (§14.6.2).
+ *   `TimeZoneIdentifier` grammar (§13.31).
  * - 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`).
@@ -12,6 +12,9 @@
  * - 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"`.
+ * - A stored offset with seconds (`-00:44:30`) is false here and true for `isValidUtcOffset`. To
+ *   check what a function with a zoneless result accepts, use
+ *   `isValidTimeZone(x) || isValidUtcOffset(x)`.
  *
  * @param timeZone timeZone identifier to validate
  * @returns boolean indicating validity
@@ -23,6 +26,7 @@
  * @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 isValidTimeZone("-00:44:30") // false (a stored offset with seconds; `isValidUtcOffset` accepts it)
  * @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,11 @@
 import { timeZoneLike } from "../../regex/index.js";
-import { zonedDateTimeFrom } from "../../internal/index.js";
+import { zonedDateTimeFrom } from "../../internal/zonedWallClock.js";
 /**
  * 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 the `timeZoneLike` regex to check the identifier's shape: Temporal's
- *   `TimeZoneIdentifier` grammar (§14.6.2).
+ *   `TimeZoneIdentifier` grammar (§13.31).
  * - 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`).
@@ -14,6 +14,9 @@ import { zonedDateTimeFrom } from "../../internal/index.js";
  * - 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"`.
+ * - A stored offset with seconds (`-00:44:30`) is false here and true for `isValidUtcOffset`. To
+ *   check what a function with a zoneless result accepts, use
+ *   `isValidTimeZone(x) || isValidUtcOffset(x)`.
  *
  * @param timeZone timeZone identifier to validate
  * @returns boolean indicating validity
@@ -25,6 +28,7 @@ import { zonedDateTimeFrom } from "../../internal/index.js";
  * @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 isValidTimeZone("-00:44:30") // false (a stored offset with seconds; `isValidUtcOffset` accepts it)
  * @example "Japan".includes("/") // false (the earlier slash-only rule)
  */
 export function isValidTimeZone(timeZone) {

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

@@ -6,7 +6,15 @@
  *   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.
+ * - A written offset must agree with the bracketed zone, as TC39 `ToTemporalZonedDateTime`
+ *   matches it: an offset written to the minute may be the zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]` for −00:44:30, which is how Temporal writes it), and an offset
+ *   written with seconds must be the zone's offset exactly.
  * - Rejects leap seconds.
+ * - With an offset, the local date must be inside Temporal's date range, as
+ *   `Temporal.ZonedDateTime.from` requires (`CheckISODaysRange`): a zoned string on
+ *   −271821-04-19, which a zone west of Greenwich shows for the first hours of the instant
+ *   range, is rejected although `isValidInstant` accepts it.
  * - 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
@@ -24,6 +32,11 @@
  * @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("2024-10-03T14:30:00-05:00[America/New_York]") // false (New York is -04:00 in October)
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // true (-00:45 is Monrovia's -00:44:30, rounded)
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:44:30[Africa/Monrovia]") // true
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:45:00[Africa/Monrovia]") // false (an offset with seconds must be exact)
+ * @example isValidZonedDateTime("-271821-04-19T23:59:00-00:01[Europe/London]") // false (the local date is before Temporal's date range)
  * @example isValidZonedDateTime("invalid") // false
  */
 export declare function isValidZonedDateTime(value: string): boolean;

package/dist/zoned/validate/isValidZonedDateTime.js

@@ -1,5 +1,5 @@
-import { zonedDateTimeFrom } from "../../internal/index.js";
 import { hasZonedDateTimeShape } from "../../internal/isoStringBody.js";
+import { zonedDateTimeFrom } from "../../internal/zonedWallClock.js";
 import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
 /**
  * Validate whether a string is a valid ISO 8601 zoned datetime string.
@@ -9,7 +9,15 @@ import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
  *   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.
+ * - A written offset must agree with the bracketed zone, as TC39 `ToTemporalZonedDateTime`
+ *   matches it: an offset written to the minute may be the zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]` for −00:44:30, which is how Temporal writes it), and an offset
+ *   written with seconds must be the zone's offset exactly.
  * - Rejects leap seconds.
+ * - With an offset, the local date must be inside Temporal's date range, as
+ *   `Temporal.ZonedDateTime.from` requires (`CheckISODaysRange`): a zoned string on
+ *   −271821-04-19, which a zone west of Greenwich shows for the first hours of the instant
+ *   range, is rejected although `isValidInstant` accepts it.
  * - 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
@@ -27,6 +35,11 @@ import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
  * @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("2024-10-03T14:30:00-05:00[America/New_York]") // false (New York is -04:00 in October)
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // true (-00:45 is Monrovia's -00:44:30, rounded)
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:44:30[Africa/Monrovia]") // true
+ * @example isValidZonedDateTime("1960-01-01T00:20:00-00:45:00[Africa/Monrovia]") // false (an offset with seconds must be exact)
+ * @example isValidZonedDateTime("-271821-04-19T23:59:00-00:01[Europe/London]") // false (the local date is before Temporal's date range)
  * @example isValidZonedDateTime("invalid") // false
  */
 export function isValidZonedDateTime(value) {

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

@@ -5,16 +5,13 @@
  * - 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
- * @param options optional allowEqual flag
+ * @param props the two endpoints of the range and its optional settings
  * @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
@@ -25,9 +22,23 @@
  * @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(props: {
+    /** The start of the range, as an ISO 8601 zoned datetime string. */
     value1: string;
+    /** The end of the range, as an ISO 8601 zoned datetime string. */
     value2: string;
+    /**
+     * The settings for the comparison. It must be an object or omitted; any other value, `null`
+     * included, returns `false`.
+     *
+     * @defaultValue None. Two values at the same instant are not a valid range.
+     */
     options?: {
+        /**
+         * Whether `value1` at the same instant as `value2` is a valid range. `false` requires `value1`
+         * to be before `value2`.
+         *
+         * @defaultValue `false`
+         */
         allowEqual?: boolean;
     };
 }): boolean;

package/dist/zoned/validate/isValidZonedRange.js

@@ -10,16 +10,13 @@ import { hasZonedDateTimeShape } from "../../internal/isoStringBody.js";
  * - 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
- * @param options optional allowEqual flag
+ * @param props the two endpoints of the range and its optional settings
  * @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