@northguild/gmt 1.15.0 → 1.17.0

package/dist/regex/sql-date-time.js

@@ -1,15 +1,34 @@
 /**
- * RegExp matching an ANSI SQL / ODBC timestamp literal: `YYYY-MM-DD HH:mm[:ss[.fffffffff]]`.
+ * RegExp matching a SQL timestamp literal without a time zone: `YYYY-MM-DD HH:MM:SS[.fffffffff]`.
  *
- * - Uses a space separator (never `T`), always zero-padded.
- * - Fractional seconds use `.` only (not `,`) and support 1–9 digits.
- * - Shape-only validation; real calendar validation is delegated to
- *   `Temporal.PlainDateTime.from` in `parseSql`.
+ * The grammar is SQL-92 §5.3 `<timestamp string>` and the ODBC `ts` escape
+ * (`yyyy-mm-dd hh:mm:ss[.f...]`):
+ *
+ * - `<date value> <space> <time value>`: a single space separator, never `T`.
+ * - Syntax Rule 21: the year is four digits and every other field two digits, zero-padded. No
+ *   sign and no expanded year.
+ * - Table 10: YEAR `0001`–`9999`, MONTH `01`–`12`, DAY `01`–`31`, HOUR `00`–`23`, MINUTE
+ *   `00`–`59`.
+ * - Seconds are required (`<time value>` is `<hours value>:<minutes value>:<seconds value>`).
+ * - `<seconds value> ::= <seconds integer value> [ <period> [ <seconds fraction> ] ]`: an optional
+ *   `.` then up to 9 fraction digits. SQL-92 leaves the precision to the implementation; 9 is
+ *   Temporal's nanosecond.
+ * - SECOND `60`–`61` does not match, although Table 10 allows them: GMT rejects leap seconds
+ *   because Temporal would read one as `:59`.
+ * - Shape-only validation; the calendar date is checked by `Temporal.PlainDateTime.from` in
+ *   `parseSql`.
+ *
+ * Capture groups: 1 month, 2 day, 3 hour. The year, minute, second and fraction are not
+ * captured.
  *
  * @example sqlDateTime.test("2024-03-15 14:30:00.123456789") // true
- * @example sqlDateTime.test("2024-03-15 14:30")               // true (seconds omitted)
- * @example sqlDateTime.test("2024-03-15T14:30:00")            // false (T separator)
+ * @example sqlDateTime.test("0001-01-01 00:00:00")           // true (the first year SQL allows)
+ * @example sqlDateTime.test("2024-03-15 14:30:00.")          // true (period with no fraction)
+ * @example sqlDateTime.test("2024-03-15 14:30")              // false (seconds are required)
+ * @example sqlDateTime.test("0000-01-01 00:00:00")           // false (year outside 0001–9999)
+ * @example sqlDateTime.test("+002024-03-15 14:30:00")        // false (expanded year)
+ * @example sqlDateTime.test("2024-03-15T14:30:00")           // false (T separator)
  * @example sqlDateTime.test("2024-3-5 14:30:00")             // false (unpadded)
- * @example sqlDateTime.test("2024-03-15 14:30:60")           // false (invalid second)
+ * @example sqlDateTime.test("2024-03-15 14:30:60")           // false (leap second; GMT rejects it)
  */
-export const sqlDateTime = /^(?:\d{4}|[+-]\d{6})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01]) (0[0-9]|1[0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:\.[0-9]{1,9})?)?$/;
+export const sqlDateTime = /^(?!0000)\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01]) (0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](?:\.[0-9]{0,9})?$/;

package/dist/regex/time-zone-like.d.ts

@@ -1,22 +1,31 @@
 /**
- * RegExp matching a timezone identifier in one of three forms:
+ * RegExp matching the shape of a time zone identifier: Temporal's `TimeZoneIdentifier` grammar
+ * (§14.6.2 Time Zone Identifiers), `UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
  *
- *  1. Literal `UTC` or `GMT`.
- *  2. IANA-style bracketed zone: `Area/Locality` (e.g. `America/New_York`, `Asia/Tokyo`),
- *     with support for arbitrarily deep nesting (`Area/SubArea/Locality`).
- *  3. Any other `[A-Za-z_+-]+(?:/[A-Za-z0-9_+-]+)+` shape — permissive enough to accept
- *     custom or future zone identifiers without rejecting them at the shape layer.
- *
- * This is a SHAPE-ONLY check used by `isValidZonedDateTime` and similar validators.
- * Real timezone validation (existence, IANA database membership) is delegated to
- * `Temporal.Zone.from` in `internal/calendarZonedString.ts`.
+ * - An offset identifier (`UTCOffset[~SubMinutePrecision]`): an ASCII sign and a two-digit hour
+ *   `00`–`23`, optionally followed by two minute digits `00`–`59`, with or without `:` (`+05`,
+ *   `+0530`, `-08:00`). No seconds and no fraction. `Intl.DateTimeFormat` accepts the same
+ *   offsets (ECMA-402 `IsTimeZoneOffsetString`).
+ * - An IANA name (`TimeZoneIANAName`): one or more `/`-separated components. Each starts with a
+ *   letter, `.` or `_` (`TZLeadingChar`) and continues with letters, digits, `.`, `_`, `-` or `+`
+ *   (`TZChar`). So single-component names match (`UTC`, `Japan`, `Zulu`, `EST5EDT`, `GMT+0`,
+ *   `NZ-CHAT`), as do `Area/Location` names at any depth (`America/Argentina/Buenos_Aires`,
+ *   `Etc/GMT+5`). Temporal must accept every Zone and Link name in the IANA database, and tzdb's
+ *   `backward` file has more than forty slash-less ones.
+ * - Letter case is not checked: ECMA-402 matches an identifier ASCII-case-insensitively, so `utc`
+ *   and `america/new_york` name the same zones as `UTC` and `America/New_York`.
+ * - SHAPE ONLY. Whether the name exists is decided by Temporal: its only consumer,
+ *   `isValidTimeZone`, also requires `Temporal.ZonedDateTime.from` to accept the zone.
  *
  * @example timeZoneLike.test("UTC")              // true
- * @example timeZoneLike.test("GMT")              // true
  * @example timeZoneLike.test("America/New_York") // true
- * @example timeZoneLike.test("Asia/Tokyo")       // true
- * @example timeZoneLike.test("Custom/Zone")      // true (permissive)
- * @example timeZoneLike.test("+05:00")           // false (numeric offset, not a zone id)
- * @example timeZoneLike.test("UTC+05:00")        // false (mixed form)
+ * @example timeZoneLike.test("Japan")            // true (single-component IANA link)
+ * @example timeZoneLike.test("Etc/GMT+5")        // true
+ * @example timeZoneLike.test("Custom/Zone")      // true (shape only; existence is not checked)
+ * @example timeZoneLike.test("+05:00")           // true (an offset identifier)
+ * @example timeZoneLike.test("-0800")            // true (a basic-format offset identifier)
+ * @example timeZoneLike.test("+05:00:00")        // false (no seconds in an offset identifier)
+ * @example timeZoneLike.test("-foo/bar")         // false (a name cannot start with - or +)
+ * @example timeZoneLike.test("UTC+05:00")        // false (":" is not a name character)
  */
 export declare const timeZoneLike: RegExp;

package/dist/regex/time-zone-like.js

@@ -1,22 +1,31 @@
 /**
- * RegExp matching a timezone identifier in one of three forms:
+ * RegExp matching the shape of a time zone identifier: Temporal's `TimeZoneIdentifier` grammar
+ * (§14.6.2 Time Zone Identifiers), `UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
  *
- *  1. Literal `UTC` or `GMT`.
- *  2. IANA-style bracketed zone: `Area/Locality` (e.g. `America/New_York`, `Asia/Tokyo`),
- *     with support for arbitrarily deep nesting (`Area/SubArea/Locality`).
- *  3. Any other `[A-Za-z_+-]+(?:/[A-Za-z0-9_+-]+)+` shape — permissive enough to accept
- *     custom or future zone identifiers without rejecting them at the shape layer.
- *
- * This is a SHAPE-ONLY check used by `isValidZonedDateTime` and similar validators.
- * Real timezone validation (existence, IANA database membership) is delegated to
- * `Temporal.Zone.from` in `internal/calendarZonedString.ts`.
+ * - An offset identifier (`UTCOffset[~SubMinutePrecision]`): an ASCII sign and a two-digit hour
+ *   `00`–`23`, optionally followed by two minute digits `00`–`59`, with or without `:` (`+05`,
+ *   `+0530`, `-08:00`). No seconds and no fraction. `Intl.DateTimeFormat` accepts the same
+ *   offsets (ECMA-402 `IsTimeZoneOffsetString`).
+ * - An IANA name (`TimeZoneIANAName`): one or more `/`-separated components. Each starts with a
+ *   letter, `.` or `_` (`TZLeadingChar`) and continues with letters, digits, `.`, `_`, `-` or `+`
+ *   (`TZChar`). So single-component names match (`UTC`, `Japan`, `Zulu`, `EST5EDT`, `GMT+0`,
+ *   `NZ-CHAT`), as do `Area/Location` names at any depth (`America/Argentina/Buenos_Aires`,
+ *   `Etc/GMT+5`). Temporal must accept every Zone and Link name in the IANA database, and tzdb's
+ *   `backward` file has more than forty slash-less ones.
+ * - Letter case is not checked: ECMA-402 matches an identifier ASCII-case-insensitively, so `utc`
+ *   and `america/new_york` name the same zones as `UTC` and `America/New_York`.
+ * - SHAPE ONLY. Whether the name exists is decided by Temporal: its only consumer,
+ *   `isValidTimeZone`, also requires `Temporal.ZonedDateTime.from` to accept the zone.
  *
  * @example timeZoneLike.test("UTC")              // true
- * @example timeZoneLike.test("GMT")              // true
  * @example timeZoneLike.test("America/New_York") // true
- * @example timeZoneLike.test("Asia/Tokyo")       // true
- * @example timeZoneLike.test("Custom/Zone")      // true (permissive)
- * @example timeZoneLike.test("+05:00")           // false (numeric offset, not a zone id)
- * @example timeZoneLike.test("UTC+05:00")        // false (mixed form)
+ * @example timeZoneLike.test("Japan")            // true (single-component IANA link)
+ * @example timeZoneLike.test("Etc/GMT+5")        // true
+ * @example timeZoneLike.test("Custom/Zone")      // true (shape only; existence is not checked)
+ * @example timeZoneLike.test("+05:00")           // true (an offset identifier)
+ * @example timeZoneLike.test("-0800")            // true (a basic-format offset identifier)
+ * @example timeZoneLike.test("+05:00:00")        // false (no seconds in an offset identifier)
+ * @example timeZoneLike.test("-foo/bar")         // false (a name cannot start with - or +)
+ * @example timeZoneLike.test("UTC+05:00")        // false (":" is not a name character)
  */
-export const timeZoneLike = /^(?:UTC|GMT|[A-Za-z_+-]+(?:\/[A-Za-z0-9_+-]+)+)$/;
+export const timeZoneLike = /^(?:[+-](?:[01][0-9]|2[0-3])(?::?[0-5][0-9])?|[A-Za-z._][A-Za-z0-9._+-]*(?:\/[A-Za-z._][A-Za-z0-9._+-]*)*)$/;

package/dist/regex/time.d.ts

@@ -18,12 +18,15 @@ export declare const hour: RegExp;
  */
 export declare const minute: RegExp;
 /**
- * RegExp matching an ISO 8601 second: `00`–`59`.
+ * RegExp matching a second of `00`–`59`.
+ *
+ * - Temporal's `TimeSecond` and RFC 3339's `time-second` both admit `60` (a leap second). GMT
+ *   rejects it by decision, because Temporal would read it as `:59`; `leapSecond` detects one.
  *
  * @example second.test("00") // true
  * @example second.test("30") // true
  * @example second.test("59") // true
- * @example second.test("60") // false (out of range; leap seconds use a different pattern)
+ * @example second.test("60") // false (a leap second; GMT rejects it, see `leapSecond`)
  */
 export declare const second: RegExp;
 /**
@@ -34,13 +37,17 @@ export declare const second: RegExp;
  *
  * @example fractionalSecond.test("123")       // true (milliseconds)
  * @example fractionalSecond.test("123456789") // true (nanoseconds)
- * @example fractionalSecond.test("0")         // false (must be 1–9 digits)
+ * @example fractionalSecond.test("1234567890") // false (more than 9 digits)
  * @example fractionalSecond.test("")          // false (empty)
  */
 export declare const fractionalSecond: RegExp;
 /**
  * Backward-compatible alias for `fractionalSecond`. Prefer `fractionalSecond` for new
  * usage — the pattern matches 1–9 digits of fractional seconds, not just milliseconds.
+ *
+ * @example millisecond.test("123")        // true
+ * @example millisecond.test("123456789")  // true (nanoseconds, despite the name)
+ * @example millisecond.test("1234567890") // false (more than 9 digits)
  */
 export declare const millisecond: RegExp;
 /**
@@ -50,16 +57,23 @@ export declare const millisecond: RegExp;
  * - Minutes and seconds: `00`–`59`, zero-padded.
  * - Seconds are optional; fractional seconds use `.` or `,` followed by 1–9 digits.
  * - No timezone designator — this is a plain/local time only.
+ * - Second `60` does not match: GMT rejects leap seconds (Temporal's `TimeSecond` admits one
+ *   and would read it as `:59`).
  * - Shape-only validation; real field validation is delegated to
- *   `Temporal.PlainTime.from` in `parseTime`.
+ *   `Temporal.PlainTime.from` in `isValidTime`.
+ *
+ * Capture groups: 1 hour. The minute, second and fraction are not captured.
  *
- * Capture groups: 1 hour, 2 minute, 3 second (optional), 4 fractional (optional).
+ * The written form only, with no RFC 9557 annotation. `isValidTime` reads more: it matches this
+ * against the part before the first `[` and lets Temporal read the annotations
+ * (`"…[u-ca=iso8601]"`, an elective `"…[foo=bar]"`).
  *
  * @example plainTime.test("14:30")              // true
  * @example plainTime.test("14:30:00")           // true
  * @example plainTime.test("14:30:00.123")       // true (fractional seconds)
  * @example plainTime.test("14:30:00,123")       // true (comma separator)
  * @example plainTime.test("24:00:00")           // false (hour out of range)
- * @example plainTime.test("14:30:60")           // false (second out of range)
+ * @example plainTime.exec("14:30:45.5")?.slice(1) // ["14"] (hour)
+ * @example plainTime.test("14:30:60")           // false (leap second; GMT rejects it)
  */
 export declare const plainTime: RegExp;

package/dist/regex/time.js

@@ -18,12 +18,15 @@ export const hour = /^(0[0-9]|1[0-9]|2[0-3])$/;
  */
 export const minute = /^[0-5][0-9]$/;
 /**
- * RegExp matching an ISO 8601 second: `00`–`59`.
+ * RegExp matching a second of `00`–`59`.
+ *
+ * - Temporal's `TimeSecond` and RFC 3339's `time-second` both admit `60` (a leap second). GMT
+ *   rejects it by decision, because Temporal would read it as `:59`; `leapSecond` detects one.
  *
  * @example second.test("00") // true
  * @example second.test("30") // true
  * @example second.test("59") // true
- * @example second.test("60") // false (out of range; leap seconds use a different pattern)
+ * @example second.test("60") // false (a leap second; GMT rejects it, see `leapSecond`)
  */
 export const second = /^[0-5][0-9]$/;
 /**
@@ -34,13 +37,17 @@ export const second = /^[0-5][0-9]$/;
  *
  * @example fractionalSecond.test("123")       // true (milliseconds)
  * @example fractionalSecond.test("123456789") // true (nanoseconds)
- * @example fractionalSecond.test("0")         // false (must be 1–9 digits)
+ * @example fractionalSecond.test("1234567890") // false (more than 9 digits)
  * @example fractionalSecond.test("")          // false (empty)
  */
 export const fractionalSecond = /^[0-9]{1,9}$/;
 /**
  * Backward-compatible alias for `fractionalSecond`. Prefer `fractionalSecond` for new
  * usage — the pattern matches 1–9 digits of fractional seconds, not just milliseconds.
+ *
+ * @example millisecond.test("123")        // true
+ * @example millisecond.test("123456789")  // true (nanoseconds, despite the name)
+ * @example millisecond.test("1234567890") // false (more than 9 digits)
  */
 export const millisecond = fractionalSecond;
 /**
@@ -50,16 +57,23 @@ export const millisecond = fractionalSecond;
  * - Minutes and seconds: `00`–`59`, zero-padded.
  * - Seconds are optional; fractional seconds use `.` or `,` followed by 1–9 digits.
  * - No timezone designator — this is a plain/local time only.
+ * - Second `60` does not match: GMT rejects leap seconds (Temporal's `TimeSecond` admits one
+ *   and would read it as `:59`).
  * - Shape-only validation; real field validation is delegated to
- *   `Temporal.PlainTime.from` in `parseTime`.
+ *   `Temporal.PlainTime.from` in `isValidTime`.
+ *
+ * Capture groups: 1 hour. The minute, second and fraction are not captured.
  *
- * Capture groups: 1 hour, 2 minute, 3 second (optional), 4 fractional (optional).
+ * The written form only, with no RFC 9557 annotation. `isValidTime` reads more: it matches this
+ * against the part before the first `[` and lets Temporal read the annotations
+ * (`"…[u-ca=iso8601]"`, an elective `"…[foo=bar]"`).
  *
  * @example plainTime.test("14:30")              // true
  * @example plainTime.test("14:30:00")           // true
  * @example plainTime.test("14:30:00.123")       // true (fractional seconds)
  * @example plainTime.test("14:30:00,123")       // true (comma separator)
  * @example plainTime.test("24:00:00")           // false (hour out of range)
- * @example plainTime.test("14:30:60")           // false (second out of range)
+ * @example plainTime.exec("14:30:45.5")?.slice(1) // ["14"] (hour)
+ * @example plainTime.test("14:30:60")           // false (leap second; GMT rejects it)
  */
 export const plainTime = /^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:[.,][0-9]{1,9})?)?$/;

package/dist/regex/unix.d.ts

@@ -1,23 +1,31 @@
 /**
  * RegExp matching a Unix timestamp in seconds: exactly 10 digits.
  *
- * - Covers the range from `0000000000` (1970-01-01T00:00:00Z) through
- *   `3999999999` (2096-10-11T03:33:19Z), which is the practical range for
- *   10-digit Unix-second timestamps.
+ * - Matches `0000000000` (1970-01-01T00:00:00Z) through `9999999999`
+ *   (2286-11-20T17:46:39Z).
+ * - Does not match an unpadded value (`"999999999"`, `"0"`), so every real timestamp before
+ *   `1000000000` (2001-09-09T01:46:40Z) needs zero-padding to match, and never matches a
+ *   negative (pre-1970) timestamp.
  *
  * @example unixSeconds.test("1710511800") // true
  * @example unixSeconds.test("0000000000") // true (epoch)
+ * @example unixSeconds.test("9999999999") // true (2286-11-20T17:46:39Z)
+ * @example unixSeconds.test("999999999")  // false (unpadded; 2001-09-09T01:46:39Z)
+ * @example unixSeconds.test("-1")         // false (negative)
  * @example unixSeconds.test("17105118001") // false (11 digits)
  */
 export declare const unixSeconds: RegExp;
 /**
  * RegExp matching a Unix timestamp in milliseconds: exactly 13 digits.
  *
- * - Covers the range from `0000000000000` (1970-01-01T00:00:00Z) through
- *   `3999999999999` (2096-10-11T03:33:19.999Z).
+ * - Matches `0000000000000` (1970-01-01T00:00:00Z) through `9999999999999`
+ *   (2286-11-20T17:46:39.999Z).
+ * - Does not match an unpadded value, so every real timestamp before `1000000000000`
+ *   (2001-09-09T01:46:40Z) needs zero-padding to match, and never matches a negative one.
  *
  * @example unixMilliseconds.test("1710511800123") // true
  * @example unixMilliseconds.test("0000000000000")  // true (epoch)
+ * @example unixMilliseconds.test("999999999999")   // false (unpadded, 12 digits)
  * @example unixMilliseconds.test("17105118001")    // false (11 digits)
  */
 export declare const unixMilliseconds: RegExp;

package/dist/regex/unix.js

@@ -1,23 +1,31 @@
 /**
  * RegExp matching a Unix timestamp in seconds: exactly 10 digits.
  *
- * - Covers the range from `0000000000` (1970-01-01T00:00:00Z) through
- *   `3999999999` (2096-10-11T03:33:19Z), which is the practical range for
- *   10-digit Unix-second timestamps.
+ * - Matches `0000000000` (1970-01-01T00:00:00Z) through `9999999999`
+ *   (2286-11-20T17:46:39Z).
+ * - Does not match an unpadded value (`"999999999"`, `"0"`), so every real timestamp before
+ *   `1000000000` (2001-09-09T01:46:40Z) needs zero-padding to match, and never matches a
+ *   negative (pre-1970) timestamp.
  *
  * @example unixSeconds.test("1710511800") // true
  * @example unixSeconds.test("0000000000") // true (epoch)
+ * @example unixSeconds.test("9999999999") // true (2286-11-20T17:46:39Z)
+ * @example unixSeconds.test("999999999")  // false (unpadded; 2001-09-09T01:46:39Z)
+ * @example unixSeconds.test("-1")         // false (negative)
  * @example unixSeconds.test("17105118001") // false (11 digits)
  */
 export const unixSeconds = /^\d{10}$/;
 /**
  * RegExp matching a Unix timestamp in milliseconds: exactly 13 digits.
  *
- * - Covers the range from `0000000000000` (1970-01-01T00:00:00Z) through
- *   `3999999999999` (2096-10-11T03:33:19.999Z).
+ * - Matches `0000000000000` (1970-01-01T00:00:00Z) through `9999999999999`
+ *   (2286-11-20T17:46:39.999Z).
+ * - Does not match an unpadded value, so every real timestamp before `1000000000000`
+ *   (2001-09-09T01:46:40Z) needs zero-padding to match, and never matches a negative one.
  *
  * @example unixMilliseconds.test("1710511800123") // true
  * @example unixMilliseconds.test("0000000000000")  // true (epoch)
+ * @example unixMilliseconds.test("999999999999")   // false (unpadded, 12 digits)
  * @example unixMilliseconds.test("17105118001")    // false (11 digits)
  */
 export const unixMilliseconds = /^\d{13}$/;

package/dist/regex/utc-date-time.d.ts

@@ -1,20 +1,30 @@
 /**
  * RegExp matching ISO 8601 UTC datetime: `<date>T<time>Z` with optional fractional
- * seconds. The timezone designator accepts `Z` or `z` (lowercase is accepted for
- * leniency, though GMT's own formatter always emits uppercase).
+ * seconds, in ISO 8601 extended format. The designator is an upper-case `Z`:
+ * a lower-case `z`, which RFC 3339 §5.6 and Temporal also read, does not match (`rfc3339DateTime`
+ * is the RFC 3339 pattern that accepts it).
  *
- * - Date half: `YYYY-MM-DD` or `±YYYYYY-MM-DD` (6-digit year with sign).
+ * - Date half: `YYYY-MM-DD` or `±YYYYYY-MM-DD` (6-digit year with sign, never `-000000`,
+ *   which is a Syntax Error in Temporal's `DateYear`).
  * - Time half: `HH:mm` with optional `:ss[.fffffffff]` (fractional seconds use `.` or `,`).
- * - No numeric offset — only the `Z`/`z` UTC designator is accepted.
- * - Shape-only validation; real calendar validation is delegated to
- *   `Temporal.PlainDateTime.from` in `parseUtcDateTime`.
+ * - Second `60` does not match. Temporal's `TimeSecond` admits it, but GMT rejects leap
+ *   seconds because Temporal would read one as `:59`.
+ * - No numeric offset — only the `Z` UTC designator is accepted.
+ * - Shape-only validation; real validation is delegated to `Temporal.Instant.from` in
+ *   `isValidUtc`.
  *
- * Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second (optional),
- * 7 fractional (optional).
+ * Capture groups: 1 month, 2 day, 3 hour. The year, minute, second and fraction are not
+ * captured.
+ *
+ * The written form only, with no RFC 9557 annotation. `isValidUtc` reads more: it matches this
+ * against the part before the first `[` and lets Temporal read the annotations
+ * (`"…[u-ca=iso8601]"`, an elective `"…[foo=bar]"`).
  *
  * @example utcDateTime.test("2024-03-15T14:30:00Z")       // true
- * @example utcDateTime.test("2024-03-15T14:30z")          // true (lowercase z)
+ * @example utcDateTime.test("2024-03-15T14:30z")          // false (lower-case z)
  * @example utcDateTime.test("2024-03-15T14:30:00.123Z")   // true (fractional seconds)
+ * @example utcDateTime.exec("2024-03-15T14:30:45.5Z")?.slice(1) // ["03", "15", "14"] (month, day, hour)
+ * @example utcDateTime.test("-000000-01-01T00:00Z")       // false (negative zero year)
  * @example utcDateTime.test("2024-03-15T14:30:00+00:00")  // false (numeric offset)
  * @example utcDateTime.test("2024-03-15T14:30:00")        // false (no timezone)
  */

package/dist/regex/utc-date-time.js

@@ -1,21 +1,31 @@
 /**
  * RegExp matching ISO 8601 UTC datetime: `<date>T<time>Z` with optional fractional
- * seconds. The timezone designator accepts `Z` or `z` (lowercase is accepted for
- * leniency, though GMT's own formatter always emits uppercase).
+ * seconds, in ISO 8601 extended format. The designator is an upper-case `Z`:
+ * a lower-case `z`, which RFC 3339 §5.6 and Temporal also read, does not match (`rfc3339DateTime`
+ * is the RFC 3339 pattern that accepts it).
  *
- * - Date half: `YYYY-MM-DD` or `±YYYYYY-MM-DD` (6-digit year with sign).
+ * - Date half: `YYYY-MM-DD` or `±YYYYYY-MM-DD` (6-digit year with sign, never `-000000`,
+ *   which is a Syntax Error in Temporal's `DateYear`).
  * - Time half: `HH:mm` with optional `:ss[.fffffffff]` (fractional seconds use `.` or `,`).
- * - No numeric offset — only the `Z`/`z` UTC designator is accepted.
- * - Shape-only validation; real calendar validation is delegated to
- *   `Temporal.PlainDateTime.from` in `parseUtcDateTime`.
+ * - Second `60` does not match. Temporal's `TimeSecond` admits it, but GMT rejects leap
+ *   seconds because Temporal would read one as `:59`.
+ * - No numeric offset — only the `Z` UTC designator is accepted.
+ * - Shape-only validation; real validation is delegated to `Temporal.Instant.from` in
+ *   `isValidUtc`.
  *
- * Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second (optional),
- * 7 fractional (optional).
+ * Capture groups: 1 month, 2 day, 3 hour. The year, minute, second and fraction are not
+ * captured.
+ *
+ * The written form only, with no RFC 9557 annotation. `isValidUtc` reads more: it matches this
+ * against the part before the first `[` and lets Temporal read the annotations
+ * (`"…[u-ca=iso8601]"`, an elective `"…[foo=bar]"`).
  *
  * @example utcDateTime.test("2024-03-15T14:30:00Z")       // true
- * @example utcDateTime.test("2024-03-15T14:30z")          // true (lowercase z)
+ * @example utcDateTime.test("2024-03-15T14:30z")          // false (lower-case z)
  * @example utcDateTime.test("2024-03-15T14:30:00.123Z")   // true (fractional seconds)
+ * @example utcDateTime.exec("2024-03-15T14:30:45.5Z")?.slice(1) // ["03", "15", "14"] (month, day, hour)
+ * @example utcDateTime.test("-000000-01-01T00:00Z")       // false (negative zero year)
  * @example utcDateTime.test("2024-03-15T14:30:00+00:00")  // false (numeric offset)
  * @example utcDateTime.test("2024-03-15T14:30:00")        // false (no timezone)
  */
-export const utcDateTime = /^(?:\d{4}|[+-]\d{6})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:[.,]\d{1,9})?)?[Zz]$/;
+export const utcDateTime = /^(?:\d{4}|\+\d{6}|-(?!0{6})\d{6})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9](?:[.,]\d{1,9})?)?Z$/;

package/dist/regex/utc-offset.d.ts

@@ -0,0 +1,24 @@
+/**
+ * RegExp matching an ISO 8601 UTC offset in the extended form GMT's offset-instant pair
+ * stores: `±HH:MM`, optionally `±HH:MM:SS`.
+ *
+ * - Anchored, so it matches a whole offset rather than the offset half of a datetime string.
+ * - `Z` is deliberately **not** matched. `Z` is a designator meaning "this string is already
+ *   UTC"; the pair's `offset` field records where the event happened, and for UTC that is
+ *   `+00:00`. Accepting both would give one fact two spellings.
+ * - Seconds are allowed because IANA offsets were not always whole minutes: `Africa/Monrovia`
+ *   ran at `-00:44:30` until 1972, and `toOffsetInstant` reports it as written rather than
+ *   rounding a real offset to a convenient one.
+ * - Sub-second offsets are rejected. ISO 8601 permits them and `Temporal.Instant.from` parses
+ *   them, but no zone, and no standard that stores this pair, has ever used one.
+ * - Shape only. Whether the offset is in Temporal's representable range is a separate check —
+ *   `internal/utcOffsetString.ts` applies both.
+ *
+ * @example utcOffset.test("-04:00") // true
+ * @example utcOffset.test("+05:45") // true
+ * @example utcOffset.test("-00:44:30") // true (Africa/Monrovia before 1972)
+ * @example utcOffset.test("Z") // false (a designator, not an offset)
+ * @example utcOffset.test("-0400") // false (basic format)
+ * @example utcOffset.test("+24:00") // false (out of range)
+ */
+export declare const utcOffset: RegExp;

package/dist/regex/utc-offset.js

@@ -0,0 +1,24 @@
+/**
+ * RegExp matching an ISO 8601 UTC offset in the extended form GMT's offset-instant pair
+ * stores: `±HH:MM`, optionally `±HH:MM:SS`.
+ *
+ * - Anchored, so it matches a whole offset rather than the offset half of a datetime string.
+ * - `Z` is deliberately **not** matched. `Z` is a designator meaning "this string is already
+ *   UTC"; the pair's `offset` field records where the event happened, and for UTC that is
+ *   `+00:00`. Accepting both would give one fact two spellings.
+ * - Seconds are allowed because IANA offsets were not always whole minutes: `Africa/Monrovia`
+ *   ran at `-00:44:30` until 1972, and `toOffsetInstant` reports it as written rather than
+ *   rounding a real offset to a convenient one.
+ * - Sub-second offsets are rejected. ISO 8601 permits them and `Temporal.Instant.from` parses
+ *   them, but no zone, and no standard that stores this pair, has ever used one.
+ * - Shape only. Whether the offset is in Temporal's representable range is a separate check —
+ *   `internal/utcOffsetString.ts` applies both.
+ *
+ * @example utcOffset.test("-04:00") // true
+ * @example utcOffset.test("+05:45") // true
+ * @example utcOffset.test("-00:44:30") // true (Africa/Monrovia before 1972)
+ * @example utcOffset.test("Z") // false (a designator, not an offset)
+ * @example utcOffset.test("-0400") // false (basic format)
+ * @example utcOffset.test("+24:00") // false (out of range)
+ */
+export const utcOffset = /^[+-](?:[01][0-9]|2[0-3]):[0-5][0-9](?::[0-5][0-9])?$/;

package/dist/span/calculate/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./spanMs.js";
+export * from "./spanNs.js";
+export * from "./spanWallClock.js";

package/dist/span/calculate/index.js

@@ -0,0 +1,3 @@
+export * from "./spanMs.js";
+export * from "./spanNs.js";
+export * from "./spanWallClock.js";

package/dist/span/calculate/spanMs.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Return the exact elapsed milliseconds between two ISO 8601 instant strings.
+ *
+ * The universal span primitive for profiling and observability. Fractional, like
+ * `performance.now()` — a sub-millisecond span is reported as a fraction, not rounded away.
+ *
+ * - Signed: negative when `start` is after `end`, so `spanMs(b, a)` is exactly
+ *   `-spanMs(a, b)`.
+ * - Measures **exact elapsed time**, never calendar distance. A wall-clock day containing a
+ *   DST transition is 23 or 25 hours (or 24.5, in `Australia/Lord_Howe`), and `spanMs`
+ *   reports the hours that actually elapsed. `spanWallClock` answers the calendar question;
+ *   conflating the two is the most common span bug there is.
+ * - Accepts anything `toNanoseconds` does: the full RFC 9557 instant grammar, no leap
+ *   seconds; calendar and elective annotations are ignored, as `Temporal.Instant.from` ignores
+ *   them. An offset designator (`Z`, `±HH:MM`) is
+ *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
+ *   which is the one string shape `spanWallClock` accepts and these two do not. The
+ *   endpoints need not share a zone; an instant is an instant.
+ * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
+ *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
+ *   with the offset is not checked. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - Returns `null` on invalid input, not `0` — `0` is the span between an instant and itself.
+ *   `null`, not `NaN`, because that is GMT's sentinel for every number-returning function:
+ *   it is the one a caller already checks for, and the only one `strictNullChecks` forces
+ *   them to handle. A `NaN` would type as plain `number` and propagate silently through
+ *   arithmetic. `spanNs` and `spanWallClock` return `null` for the same reason.
+ * - **Safe range.** Returns `null` when the exact span exceeds `Number.MAX_SAFE_INTEGER`
+ *   milliseconds (±9_007_199_254_740_991 ms, about ±285,000 years), which two instants at
+ *   opposite ends of `Temporal.Instant`'s range do. A sub-millisecond fraction counts
+ *   toward that ceiling, so any number returned is a safe integer or below. Use `spanNs`
+ *   past it — it carries the exact value as a `bigint`.
+ *   Sub-millisecond fidelity goes first, long before the ceiling: a double carries the
+ *   nanosecond digits exactly only while the span is under 2^53 ns, roughly 104 days.
+ * - Leap seconds are not counted. UTC repeats a second rather than numbering a 61st one, so
+ *   a span across one is a second short of the physical elapsed time; against a smeared
+ *   clock (Google, AWS, Meta) the error is up to a second spread over the smear window.
+ *   Leap-second-exact spans need a TAI scale, which GMT does not yet ship.
+ *
+ * @param start ISO 8601 instant string the span is measured from
+ * @param end ISO 8601 instant string the span is measured to
+ * @returns exact elapsed milliseconds, negative when start is after end, or null on invalid input
+ *
+ * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:01Z") // 1000
+ * @example spanMs("2024-03-10T12:00:01Z", "2024-03-10T12:00:00Z") // -1000
+ * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0
+ * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00.123456789Z") // 123.456789
+ * @example spanMs("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 82800000 — 23 hours, not 24
+ * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is ignored
+ * @example spanMs("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // null — past the safe integer range, use spanNs
+ * @example spanMs("2024-03-10T12:00:00Z", "invalid") // null
+ */
+export declare function spanMs(start: string, end: string): number | null;