@northguild/gmt 1.14.2 → 1.16.0

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

@@ -1,7 +1,34 @@
-// ANSI SQL / ODBC timestamp literal: space-separated (never "T"), always
-// zero-padded (unlike RFC 2822's lenient 1-2 digit day), with an optional
-// fractional-seconds component. This checks *shape* only — `parseSql` still
-// hands the extracted string to `Temporal.PlainDateTime.from` for real
-// calendar validation, same as GMT's other `isValid*` + `Temporal.*.from`
-// pairs.
-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})?)?$/;
+/**
+ * RegExp matching a SQL timestamp literal without a time zone: `YYYY-MM-DD HH:MM:SS[.fffffffff]`.
+ *
+ * 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("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 (leap second; GMT rejects it)
+ */
+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 +1,31 @@
+/**
+ * RegExp matching the shape of a time zone identifier: Temporal's `TimeZoneIdentifier` grammar
+ * (§14.6.2 Time Zone Identifiers), `UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
+ *
+ * - 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("America/New_York") // true
+ * @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 +1,31 @@
-export const timeZoneLike = /^(?:UTC|GMT|[A-Za-z_+-]+(?:\/[A-Za-z0-9_+-]+)+)$/;
+/**
+ * RegExp matching the shape of a time zone identifier: Temporal's `TimeZoneIdentifier` grammar
+ * (§14.6.2 Time Zone Identifiers), `UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
+ *
+ * - 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("America/New_York") // true
+ * @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 = /^(?:[+-](?:[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

@@ -1,6 +1,79 @@
+/**
+ * RegExp matching an ISO 8601 hour in extended format: `00`–`23`.
+ *
+ * @example hour.test("00") // true
+ * @example hour.test("12") // true
+ * @example hour.test("23") // true
+ * @example hour.test("24") // false (out of range)
+ * @example hour.test("9")  // false (not zero-padded)
+ */
 export declare const hour: RegExp;
+/**
+ * RegExp matching an ISO 8601 minute: `00`–`59`.
+ *
+ * @example minute.test("00") // true
+ * @example minute.test("30") // true
+ * @example minute.test("59") // true
+ * @example minute.test("60") // false (out of range)
+ */
 export declare const minute: RegExp;
+/**
+ * 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 (a leap second; GMT rejects it, see `leapSecond`)
+ */
 export declare const second: RegExp;
+/**
+ * RegExp matching 1–9 fractional-second digits (nanosecond precision).
+ *
+ * - Used for the fractional portion after `.` or `,` in time strings.
+ * - Backward-compatible alias `millisecond` points to this same pattern.
+ *
+ * @example fractionalSecond.test("123")       // true (milliseconds)
+ * @example fractionalSecond.test("123456789") // true (nanoseconds)
+ * @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;
+/**
+ * RegExp matching ISO 8601 local time (extended): `HH:mm[:ss[.fffffffff]]`.
+ *
+ * - Hours: `00`–`23`, zero-padded.
+ * - 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 `isValidTime`.
+ *
+ * Capture groups: 1 hour. The minute, second and fraction are not captured.
+ *
+ * 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.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

@@ -1,9 +1,79 @@
-// regex patterns exported for usage
+/**
+ * RegExp matching an ISO 8601 hour in extended format: `00`–`23`.
+ *
+ * @example hour.test("00") // true
+ * @example hour.test("12") // true
+ * @example hour.test("23") // true
+ * @example hour.test("24") // false (out of range)
+ * @example hour.test("9")  // false (not zero-padded)
+ */
 export const hour = /^(0[0-9]|1[0-9]|2[0-3])$/;
+/**
+ * RegExp matching an ISO 8601 minute: `00`–`59`.
+ *
+ * @example minute.test("00") // true
+ * @example minute.test("30") // true
+ * @example minute.test("59") // true
+ * @example minute.test("60") // false (out of range)
+ */
 export const minute = /^[0-5][0-9]$/;
+/**
+ * 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 (a leap second; GMT rejects it, see `leapSecond`)
+ */
 export const second = /^[0-5][0-9]$/;
+/**
+ * RegExp matching 1–9 fractional-second digits (nanosecond precision).
+ *
+ * - Used for the fractional portion after `.` or `,` in time strings.
+ * - Backward-compatible alias `millisecond` points to this same pattern.
+ *
+ * @example fractionalSecond.test("123")       // true (milliseconds)
+ * @example fractionalSecond.test("123456789") // true (nanoseconds)
+ * @example fractionalSecond.test("1234567890") // false (more than 9 digits)
+ * @example fractionalSecond.test("")          // false (empty)
+ */
 export const fractionalSecond = /^[0-9]{1,9}$/;
-// Backward-compatible alias; prefer fractionalSecond for new usage.
+/**
+ * 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;
-// ISO 8601 local time (extended): HH:mm[:ss[.fffffffff]]
+/**
+ * RegExp matching ISO 8601 local time (extended): `HH:mm[:ss[.fffffffff]]`.
+ *
+ * - Hours: `00`–`23`, zero-padded.
+ * - 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 `isValidTime`.
+ *
+ * Capture groups: 1 hour. The minute, second and fraction are not captured.
+ *
+ * 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.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,2 +1,31 @@
+/**
+ * RegExp matching a Unix timestamp in seconds: exactly 10 digits.
+ *
+ * - 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.
+ *
+ * - 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,2 +1,31 @@
+/**
+ * RegExp matching a Unix timestamp in seconds: exactly 10 digits.
+ *
+ * - 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.
+ *
+ * - 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 +1,31 @@
+/**
+ * RegExp matching ISO 8601 UTC datetime: `<date>T<time>Z` with optional fractional
+ * 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, never `-000000`,
+ *   which is a Syntax Error in Temporal's `DateYear`).
+ * - Time half: `HH:mm` with optional `:ss[.fffffffff]` (fractional seconds use `.` or `,`).
+ * - 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 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")          // 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 declare const utcDateTime: RegExp;

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

@@ -1,2 +1,31 @@
-// ISO 8601 UTC datetime: <date>T<time>Z with optional fractional seconds
-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]$/;
+/**
+ * RegExp matching ISO 8601 UTC datetime: `<date>T<time>Z` with optional fractional
+ * 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, never `-000000`,
+ *   which is a Syntax Error in Temporal's `DateYear`).
+ * - Time half: `HH:mm` with optional `:ss[.fffffffff]` (fractional seconds use `.` or `,`).
+ * - 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 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")          // 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{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;

package/dist/span/calculate/spanMs.js

@@ -0,0 +1,80 @@
+import { spanNs } from "./spanNs.js";
+/** Nanoseconds in a millisecond. */
+const NANOSECONDS_PER_MILLISECOND = 1000000n;
+/**
+ * The largest span, in nanoseconds, whose exact millisecond value a `number` still holds.
+ *
+ * Guarding here rather than on the truncated whole-millisecond part matters: a span of
+ * `MAX_SAFE_INTEGER` milliseconds *plus* a fraction passes a whole-millisecond check and
+ * then rounds up to 2^53 on recombination, returning an unsafe integer from a function
+ * documented to return the sentinel past the safe range.
+ */
+const MAX_SAFE_NANOSECONDS = BigInt(Number.MAX_SAFE_INTEGER) * NANOSECONDS_PER_MILLISECOND;
+/**
+ * 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 function spanMs(start, end) {
+    const nanoseconds = spanNs(start, end);
+    if (nanoseconds === null) {
+        return null;
+    }
+    if (nanoseconds > MAX_SAFE_NANOSECONDS ||
+        nanoseconds < -MAX_SAFE_NANOSECONDS) {
+        return null;
+    }
+    // Split rather than dividing the whole bigint through a double: Number(nanoseconds) is
+    // already lossy past 2^53 ns (~104 days), which would corrupt the millisecond part too.
+    // BigInt division truncates toward zero and `%` keeps the dividend's sign, so both halves
+    // flip together and spanMs(b, a) === -spanMs(a, b) holds exactly.
+    const milliseconds = nanoseconds / NANOSECONDS_PER_MILLISECOND;
+    const remainder = nanoseconds % NANOSECONDS_PER_MILLISECOND;
+    return Number(milliseconds) + Number(remainder) / 1e6;
+}