@northguild/gmt 1.14.2 → 1.15.0

package/dist/regex/calendar-date.js

@@ -1,11 +1,20 @@
-// GMT's own calendar-annotated PlainDate string: the calendar-native year/month/day
-// (e.g. Hebrew year 5785), tagged with the calendar identifier — not Temporal's own
-// `[u-ca=...]` annotation convention, which keeps the ISO/proleptic-Gregorian digits and
-// only tags the calendar. See convertDateToCalendar for the rationale.
-//
-// The optional trailing `;era=<name>` captures an era identifier (e.g. "reiwa"), needed
-// only for the "japanese" calendar: unlike every other supported calendar, Temporal's
-// `.year` for "japanese" stays proleptic (does not reset at an era change), so the
-// era-relative year (Temporal's `.eraYear`) has to be paired with the era name to be
-// unambiguous. See formatCalendarDate/parseCalendarDateValue for how it round-trips.
+/**
+ * RegExp matching GMT's own calendar-annotated PlainDate string: the calendar-native
+ * year/month/day (e.g. Hebrew year 5785), tagged with the calendar identifier — not
+ * Temporal's own `[u-ca=...]` annotation convention, which keeps the ISO/proleptic-
+ * Gregorian digits and only tags the calendar. See `convertDateToCalendar` for the
+ * rationale.
+ *
+ * The optional trailing `;era=<name>` captures an era identifier (e.g. "reiwa"), needed
+ * only for the "japanese" calendar: unlike every other supported calendar, Temporal's
+ * `.year` for "japanese" stays proleptic (does not reset at an era change), so the
+ * era-relative year (Temporal's `.eraYear`) has to be paired with the era name to be
+ * unambiguous. See `formatCalendarDate`/`parseCalendarDateValue` for how it round-trips.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 calendar id, 5 era (optional).
+ *
+ * @example calendarDate.test("5785-01-01[u-ca=hebrew]")              // true
+ * @example calendarDate.test("5785-01-01[u-ca=japanese;era=reiwa]")  // true
+ * @example calendarDate.test("2024-03-15")                           // false (no calendar tag)
+ */
 export const calendarDate = /^(\d{4,6})-(\d{2})-(\d{2})\[u-ca=([a-z][a-z0-9-]*)(?:;era=([a-z]+))?\]$/;

package/dist/regex/calendar-zoned-date-time.d.ts

@@ -1 +1,46 @@
+/**
+ * RegExp matching GMT's own calendar-annotated ZonedDateTime string — the zoned sibling of
+ * `calendarDate` (regex/calendar-date.ts). Shape:
+ *
+ *   <calendar-native-date>T<time><offset>[u-ca=<id>[;era=<era>]][<timeZone>]
+ *   5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]
+ *   0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]
+ *
+ * The date half (`(\d{4,6})-(\d{2})-(\d{2})`) and the annotation half
+ * (`\[u-ca=([a-z][a-z0-9-]*)(?:;era=([a-z]+))?\]`) are deliberately byte-identical to
+ * `calendarDate`'s, so the two grammars cannot drift apart —
+ * `calendar-zoned-date-time.test.ts` asserts every `convertDateToCalendar` output splices
+ * into this pattern.
+ *
+ * SEGMENT ORDERING: `[u-ca=...]` comes BEFORE `[timeZone]` — the reverse of RFC 9557.
+ * This is deliberate and load-bearing, not an oversight, and it must not be "fixed" to
+ * match Temporal's own string convention. Verified against @js-temporal/polyfill@0.5.1:
+ *
+ *  1. GMT's digits are calendar-native (Hebrew year 5784, not ISO year 5784), so a GMT
+ *     string is never a valid RFC 9557 string — round-trippability through
+ *     `Temporal.ZonedDateTime.from` was never achievable, and the `;era=` suffix makes it
+ *     impossible regardless of ordering.
+ *  2. RFC 9557's own ordering is actively dangerous here.
+ *     `Temporal.ZonedDateTime.from("5784-01-01T14:30:00-05:00[America/New_York][u-ca=hebrew]")`
+ *     SUCCEEDS, silently reading `5784-01-01` as ISO year 5784 — a ~3760-year misparse
+ *     with no error. GMT's ordering makes that same shape uniformly rejected:
+ *     `Temporal.ZonedDateTime.from("...-05:00[u-ca=hebrew][America/New_York]")` throws
+ *     `RangeError: invalid RFC 9557 string` for all 13 calendars.
+ *  3. `isValidZonedDateTime` is imported by ~90 non-test files, only ~18 of which are in
+ *     scope. With `[u-ca=]` first, every out-of-scope function fails closed (returns its
+ *     sentinel) rather than silently returning an answer computed against the wrong calendar.
+ *
+ * The offset stays between the time and the bracketed tail, so `<date>T<time><offset>`
+ * remains a contiguous, familiar ISO-8601 head; only the bracketed tail reorders.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 time, 5 offset (optional), 6 calendar id,
+ * 7 era (optional), 8 time zone. As with every GMT grammar regex, a match proves SHAPE
+ * ONLY — real field/calendar/era/zone validation is delegated to
+ * `Temporal.*.from(fields, { overflow: "reject" })` in `internal/calendarZonedString.ts`
+ * (see `context/coding-standards.md`'s scoped manual-string-parsing exception, rule 2).
+ *
+ * @example calendarZonedDateTime.test("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]") // true
+ * @example calendarZonedDateTime.test("0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]") // true
+ * @example calendarZonedDateTime.test("2024-03-15T14:30:00Z") // false (no calendar tag)
+ */
 export declare const calendarZonedDateTime: RegExp;

package/dist/regex/calendar-zoned-date-time.js

@@ -1,41 +1,46 @@
-// GMT's own calendar-annotated ZonedDateTime string — the zoned sibling of `calendarDate`
-// (regex/calendar-date.ts). Shape:
-//
-//   <calendar-native-date>T<time><offset>[u-ca=<id>[;era=<era>]][<timeZone>]
-//   5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]
-//   0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]
-//
-// The date half (`(\d{4,6})-(\d{2})-(\d{2})`) and the annotation half
-// (`\[u-ca=([a-z][a-z0-9-]*)(?:;era=([a-z]+))?\]`) are deliberately byte-identical to
-// `calendarDate`'s, so the two grammars cannot drift apart — `calendar-zoned-date-time.test.ts`
-// asserts every `convertDateToCalendar` output splices into this pattern.
-//
-// ---------------------------------------------------------------------------------------
-// SEGMENT ORDERING: `[u-ca=...]` comes BEFORE `[timeZone]` — the reverse of RFC 9557.
-// ---------------------------------------------------------------------------------------
-// This is deliberate and load-bearing, not an oversight, and it must not be "fixed" to match
-// Temporal's own string convention. Verified against @js-temporal/polyfill@0.5.1:
-//
-//  1. GMT's digits are calendar-native (Hebrew year 5784, not ISO year 5784), so a GMT string is
-//     never a valid RFC 9557 string in the first place — E1's decision D1. Round-trippability
-//     through `Temporal.ZonedDateTime.from` was never achievable, and the `;era=` suffix (below)
-//     makes it impossible regardless of ordering.
-//  2. RFC 9557's own ordering is actively dangerous here.
-//     `Temporal.ZonedDateTime.from("5784-01-01T14:30:00-05:00[America/New_York][u-ca=hebrew]")`
-//     SUCCEEDS, silently reading `5784-01-01` as ISO year 5784 — a ~3760-year misparse with no
-//     error anywhere. GMT's ordering makes that same string shape uniformly rejected instead:
-//     `Temporal.ZonedDateTime.from("...-05:00[u-ca=hebrew][America/New_York]")` throws
-//     `RangeError: invalid RFC 9557 string` for all 13 calendars.
-//  3. `isValidZonedDateTime` is imported by ~90 non-test files, only ~18 of which are in E7's
-//     scope. With `[u-ca=]` first, every out-of-scope function fails closed (returns its
-//     sentinel) rather than silently returning an answer computed against the wrong calendar.
-//
-// The offset stays between the time and the bracketed tail, so `<date>T<time><offset>` remains a
-// contiguous, familiar ISO-8601 head; only the bracketed tail reorders.
-//
-// Capture groups: 1 year, 2 month, 3 day, 4 time, 5 offset (optional), 6 calendar id, 7 era
-// (optional), 8 time zone. As with every GMT grammar regex, a match proves SHAPE ONLY — real
-// field/calendar/era/zone validation is delegated to `Temporal.*.from(fields, { overflow:
-// "reject" })` in `internal/calendarZonedString.ts` (see `context/coding-standards.md`'s scoped
-// manual-string-parsing exception, rule 2).
+/**
+ * RegExp matching GMT's own calendar-annotated ZonedDateTime string — the zoned sibling of
+ * `calendarDate` (regex/calendar-date.ts). Shape:
+ *
+ *   <calendar-native-date>T<time><offset>[u-ca=<id>[;era=<era>]][<timeZone>]
+ *   5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]
+ *   0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]
+ *
+ * The date half (`(\d{4,6})-(\d{2})-(\d{2})`) and the annotation half
+ * (`\[u-ca=([a-z][a-z0-9-]*)(?:;era=([a-z]+))?\]`) are deliberately byte-identical to
+ * `calendarDate`'s, so the two grammars cannot drift apart —
+ * `calendar-zoned-date-time.test.ts` asserts every `convertDateToCalendar` output splices
+ * into this pattern.
+ *
+ * SEGMENT ORDERING: `[u-ca=...]` comes BEFORE `[timeZone]` — the reverse of RFC 9557.
+ * This is deliberate and load-bearing, not an oversight, and it must not be "fixed" to
+ * match Temporal's own string convention. Verified against @js-temporal/polyfill@0.5.1:
+ *
+ *  1. GMT's digits are calendar-native (Hebrew year 5784, not ISO year 5784), so a GMT
+ *     string is never a valid RFC 9557 string — round-trippability through
+ *     `Temporal.ZonedDateTime.from` was never achievable, and the `;era=` suffix makes it
+ *     impossible regardless of ordering.
+ *  2. RFC 9557's own ordering is actively dangerous here.
+ *     `Temporal.ZonedDateTime.from("5784-01-01T14:30:00-05:00[America/New_York][u-ca=hebrew]")`
+ *     SUCCEEDS, silently reading `5784-01-01` as ISO year 5784 — a ~3760-year misparse
+ *     with no error. GMT's ordering makes that same shape uniformly rejected:
+ *     `Temporal.ZonedDateTime.from("...-05:00[u-ca=hebrew][America/New_York]")` throws
+ *     `RangeError: invalid RFC 9557 string` for all 13 calendars.
+ *  3. `isValidZonedDateTime` is imported by ~90 non-test files, only ~18 of which are in
+ *     scope. With `[u-ca=]` first, every out-of-scope function fails closed (returns its
+ *     sentinel) rather than silently returning an answer computed against the wrong calendar.
+ *
+ * The offset stays between the time and the bracketed tail, so `<date>T<time><offset>`
+ * remains a contiguous, familiar ISO-8601 head; only the bracketed tail reorders.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 time, 5 offset (optional), 6 calendar id,
+ * 7 era (optional), 8 time zone. As with every GMT grammar regex, a match proves SHAPE
+ * ONLY — real field/calendar/era/zone validation is delegated to
+ * `Temporal.*.from(fields, { overflow: "reject" })` in `internal/calendarZonedString.ts`
+ * (see `context/coding-standards.md`'s scoped manual-string-parsing exception, rule 2).
+ *
+ * @example calendarZonedDateTime.test("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]") // true
+ * @example calendarZonedDateTime.test("0031-04-30T12:00:00+09:00[u-ca=japanese;era=heisei][Asia/Tokyo]") // true
+ * @example calendarZonedDateTime.test("2024-03-15T14:30:00Z") // false (no calendar tag)
+ */
 export const calendarZonedDateTime = /^(\d{4,6})-(\d{2})-(\d{2})T(\d{2}:\d{2}(?::\d{2}(?:[.,]\d{1,9})?)?)((?:[+-]\d{2}:\d{2}(?::\d{2}(?:[.,]\d{1,9})?)?)|[Zz])?\[u-ca=([a-z][a-z0-9-]*)(?:;era=([a-z]+))?\]\[([^[\]]+)\]$/;

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

@@ -1 +1,19 @@
+/**
+ * RegExp matching ISO 8601 local date-time (extended): `<date>T<time>`.
+ *
+ * - Date half: `YYYY-MM-DD` or `±YYYYYY-MM-DD` (6-digit year with sign).
+ * - Time half: `HH:mm` with optional `:ss[.fffffffff]` (fractional seconds use `.` or `,`).
+ * - No timezone designator — this is a plain/local date-time only.
+ * - Shape-only validation; real calendar validation is delegated to
+ *   `Temporal.PlainDateTime.from` in `parseDateTime`.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second (optional),
+ * 7 fractional (optional).
+ *
+ * @example plainDateTime.test("2024-03-15T14:30:00")       // true
+ * @example plainDateTime.test("2024-03-15T14:30")          // true (seconds omitted)
+ * @example plainDateTime.test("+000031-04-30T12:00:00.123") // true (6-digit year)
+ * @example plainDateTime.test("2024-03-15 14:30:00")       // false (space separator)
+ * @example plainDateTime.test("2024-03-15T14:30:00Z")      // false (has timezone)
+ */
 export declare const plainDateTime: RegExp;

package/dist/regex/date-time.js

@@ -1,2 +1,19 @@
-// ISO 8601 local date-time (extended): <date>T<time>
+/**
+ * RegExp matching ISO 8601 local date-time (extended): `<date>T<time>`.
+ *
+ * - Date half: `YYYY-MM-DD` or `±YYYYYY-MM-DD` (6-digit year with sign).
+ * - Time half: `HH:mm` with optional `:ss[.fffffffff]` (fractional seconds use `.` or `,`).
+ * - No timezone designator — this is a plain/local date-time only.
+ * - Shape-only validation; real calendar validation is delegated to
+ *   `Temporal.PlainDateTime.from` in `parseDateTime`.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second (optional),
+ * 7 fractional (optional).
+ *
+ * @example plainDateTime.test("2024-03-15T14:30:00")       // true
+ * @example plainDateTime.test("2024-03-15T14:30")          // true (seconds omitted)
+ * @example plainDateTime.test("+000031-04-30T12:00:00.123") // true (6-digit year)
+ * @example plainDateTime.test("2024-03-15 14:30:00")       // false (space separator)
+ * @example plainDateTime.test("2024-03-15T14:30:00Z")      // false (has timezone)
+ */
 export const plainDateTime = /^(?:\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](?:[.,][0-9]{1,9})?)?$/;

package/dist/regex/date.d.ts

@@ -1,4 +1,20 @@
 export declare const year: RegExp;
 export declare const month: RegExp;
 export declare const day: RegExp;
+/**
+ * RegExp matching ISO 8601 calendar date (extended): `YYYY-MM-DD` or `±YYYYYY-MM-DD`.
+ *
+ * - Year: 4-digit (`2024`) or 6-digit with sign (`+000031` / `-000031`).
+ * - Month: `01`–`12`, zero-padded.
+ * - Day: `01`–`31`, zero-padded (shape-only; real calendar validation is delegated to
+ *   `Temporal.PlainDate.from` in `parseDate`).
+ *
+ * Capture groups: 1 year, 2 month, 3 day.
+ *
+ * @example plainDate.test("2024-03-15")       // true
+ * @example plainDate.test("+000031-04-30")    // true (6-digit year)
+ * @example plainDate.test("-000031-04-30")    // true (negative 6-digit year)
+ * @example plainDate.test("2024-3-15")        // false (unpadded month)
+ * @example plainDate.test("2024-03-00")       // false (day zero)
+ */
 export declare const plainDate: RegExp;

package/dist/regex/date.js

@@ -1,5 +1,20 @@
 export const year = /^(?:\d{4}|[+-]\d{6})$/;
 export const month = /^(0[1-9]|1[0-2])$/;
 export const day = /^(0[1-9]|[12][0-9]|3[01])$/;
-// ISO 8601 calendar date (extended): YYYY-MM-DD or ±YYYYYY-MM-DD
+/**
+ * RegExp matching ISO 8601 calendar date (extended): `YYYY-MM-DD` or `±YYYYYY-MM-DD`.
+ *
+ * - Year: 4-digit (`2024`) or 6-digit with sign (`+000031` / `-000031`).
+ * - Month: `01`–`12`, zero-padded.
+ * - Day: `01`–`31`, zero-padded (shape-only; real calendar validation is delegated to
+ *   `Temporal.PlainDate.from` in `parseDate`).
+ *
+ * Capture groups: 1 year, 2 month, 3 day.
+ *
+ * @example plainDate.test("2024-03-15")       // true
+ * @example plainDate.test("+000031-04-30")    // true (6-digit year)
+ * @example plainDate.test("-000031-04-30")    // true (negative 6-digit year)
+ * @example plainDate.test("2024-3-15")        // false (unpadded month)
+ * @example plainDate.test("2024-03-00")       // false (day zero)
+ */
 export const plainDate = /^(?:\d{4}|[+-]\d{6})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$/;

package/dist/regex/http-date.d.ts

@@ -1 +1,16 @@
+/**
+ * RegExp matching RFC 7231 §7.1.1.1 IMF-fixdate — the only form GMT's `formatHttp`
+ * emits, and the only form `parseHttp` accepts. Day, year, and time-of-day fields are
+ * all fixed-width per the grammar (unlike RFC 2822's leniently-sized day); the trailing
+ * "GMT" literal is mandatory, never a numeric offset. The obsolete RFC 850 and asctime
+ * HTTP-date forms are a documented limitation (see `parseHttp`'s JSDoc), not supported
+ * here.
+ *
+ * Capture groups: 1 day-of-week, 2 day, 3 month, 4 year, 5 hour, 6 minute, 7 second.
+ *
+ * @example httpDate.test("Wed, 09 Jun 2021 10:18:14 GMT") // true
+ * @example httpDate.test("Jun 09 2021 10:18:14 GMT")      // false (missing day-of-week)
+ * @example httpDate.test("Wed, 9 Jun 2021 10:18:14 GMT")  // false (single-digit day)
+ * @example httpDate.test("Wed, 09 Jun 2021 10:18:14 +0000") // false (numeric offset)
+ */
 export declare const httpDate: RegExp;

package/dist/regex/http-date.js

@@ -1,7 +1,16 @@
-// RFC 7231 §7.1.1.1 IMF-fixdate — the only form GMT's `formatHttp` emits, and
-// the only form `parseHttp` accepts. Day, year, and time-of-day fields are
-// all fixed-width per the grammar (unlike RFC 2822's leniently-sized day);
-// the trailing "GMT" literal is mandatory, never a numeric offset. The
-// obsolete RFC 850 and asctime HTTP-date forms are a documented limitation
-// (see `parseHttp`'s JSDoc), not supported here.
+/**
+ * RegExp matching RFC 7231 §7.1.1.1 IMF-fixdate — the only form GMT's `formatHttp`
+ * emits, and the only form `parseHttp` accepts. Day, year, and time-of-day fields are
+ * all fixed-width per the grammar (unlike RFC 2822's leniently-sized day); the trailing
+ * "GMT" literal is mandatory, never a numeric offset. The obsolete RFC 850 and asctime
+ * HTTP-date forms are a documented limitation (see `parseHttp`'s JSDoc), not supported
+ * here.
+ *
+ * Capture groups: 1 day-of-week, 2 day, 3 month, 4 year, 5 hour, 6 minute, 7 second.
+ *
+ * @example httpDate.test("Wed, 09 Jun 2021 10:18:14 GMT") // true
+ * @example httpDate.test("Jun 09 2021 10:18:14 GMT")      // false (missing day-of-week)
+ * @example httpDate.test("Wed, 9 Jun 2021 10:18:14 GMT")  // false (single-digit day)
+ * @example httpDate.test("Wed, 09 Jun 2021 10:18:14 +0000") // false (numeric offset)
+ */
 export const httpDate = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/;

package/dist/regex/leap-second.d.ts

@@ -1 +1,13 @@
+/**
+ * RegExp fragment matching an ISO 8601 leap second: `T HH:mm:60[.fff]` followed by
+ * a timezone designator (`Z`, numeric offset, or `[` opening a bracketed annotation).
+ *
+ * - Detects second = 60 within a date-time string, not a full standalone value.
+ * - Used to identify and reject (or flag) leap-second values before Temporal parsing.
+ *
+ * @example leapSecond.test("2024-12-31T23:59:60Z")          // true
+ * @example leapSecond.test("2024-12-31T23:59:60.123+00:00") // true
+ * @example leapSecond.test("2024-12-31T23:59:59Z")          // false (second = 59)
+ * @example leapSecond.test("2024-12-31T23:59:60")           // false (no zone designator)
+ */
 export declare const leapSecond: RegExp;

package/dist/regex/leap-second.js

@@ -1,2 +1,13 @@
-// ISO 8601 leap second pattern (second = 60)
+/**
+ * RegExp fragment matching an ISO 8601 leap second: `T HH:mm:60[.fff]` followed by
+ * a timezone designator (`Z`, numeric offset, or `[` opening a bracketed annotation).
+ *
+ * - Detects second = 60 within a date-time string, not a full standalone value.
+ * - Used to identify and reject (or flag) leap-second values before Temporal parsing.
+ *
+ * @example leapSecond.test("2024-12-31T23:59:60Z")          // true
+ * @example leapSecond.test("2024-12-31T23:59:60.123+00:00") // true
+ * @example leapSecond.test("2024-12-31T23:59:59Z")          // false (second = 59)
+ * @example leapSecond.test("2024-12-31T23:59:60")           // false (no zone designator)
+ */
 export const leapSecond = /T\d{2}:\d{2}:60(?:[.,]\d+)?(?:[-+Zz[])/;

package/dist/regex/rfc-2822.d.ts

@@ -1 +1,19 @@
+/**
+ * RegExp matching RFC 5322 §3.3 date-time grammar (obsoletes RFC 2822, same shape).
+ * English day/month names are mandated by the spec regardless of locale — see
+ * `internal/englishCalendarNames.ts`. Day is `1*2DIGIT` per the formal grammar, so
+ * single-digit days are valid on input even though GMT's own formatter always emits the
+ * zero-padded 2-digit form. `zone` accepts a numeric offset or one of the obsolete named
+ * zones RFC 5322 §4.3 lists (UT/GMT plus the eight North American zones); any other
+ * obs-zone letter is unrecognized and treated as invalid rather than guessed at.
+ *
+ * Capture groups: 1 day-of-week (optional, for weekday-prefixed form), 2 day, 3 month,
+ * 4 year, 5 hour, 6 minute, 7 second (optional), 8 zone.
+ *
+ * @example rfc2822DateTime.test("Wed, 09 Jun 2021 10:18:14 GMT")   // true
+ * @example rfc2822DateTime.test("09 Jun 2021 10:18:14 +0000")       // true (no weekday)
+ * @example rfc2822DateTime.test("9 Jun 2021 10:18:14 PST")         // true (single-digit day)
+ * @example rfc2822DateTime.test("Wed, 09 Jun 2021 10:18:14 EST")   // true (named zone)
+ * @example rfc2822DateTime.test("2024-03-15T14:30:00Z")            // false (ISO shape)
+ */
 export declare const rfc2822DateTime: RegExp;

package/dist/regex/rfc-2822.js

@@ -1,9 +1,19 @@
-// RFC 5322 §3.3 date-time grammar (obsoletes RFC 2822, same date-time shape).
-// English day/month names are mandated by the spec regardless of locale — see
-// `internal/englishCalendarNames.ts`. Day is `1*2DIGIT` per the formal
-// grammar, so single-digit days are valid on input even though GMT's own
-// formatter always emits the zero-padded 2-digit form. `zone` accepts a
-// numeric offset or one of the obsolete named zones RFC 5322 §4.3 lists
-// (UT/GMT plus the eight North American zones); any other obs-zone letter is
-// unrecognized and treated as invalid rather than guessed at.
+/**
+ * RegExp matching RFC 5322 §3.3 date-time grammar (obsoletes RFC 2822, same shape).
+ * English day/month names are mandated by the spec regardless of locale — see
+ * `internal/englishCalendarNames.ts`. Day is `1*2DIGIT` per the formal grammar, so
+ * single-digit days are valid on input even though GMT's own formatter always emits the
+ * zero-padded 2-digit form. `zone` accepts a numeric offset or one of the obsolete named
+ * zones RFC 5322 §4.3 lists (UT/GMT plus the eight North American zones); any other
+ * obs-zone letter is unrecognized and treated as invalid rather than guessed at.
+ *
+ * Capture groups: 1 day-of-week (optional, for weekday-prefixed form), 2 day, 3 month,
+ * 4 year, 5 hour, 6 minute, 7 second (optional), 8 zone.
+ *
+ * @example rfc2822DateTime.test("Wed, 09 Jun 2021 10:18:14 GMT")   // true
+ * @example rfc2822DateTime.test("09 Jun 2021 10:18:14 +0000")       // true (no weekday)
+ * @example rfc2822DateTime.test("9 Jun 2021 10:18:14 PST")         // true (single-digit day)
+ * @example rfc2822DateTime.test("Wed, 09 Jun 2021 10:18:14 EST")   // true (named zone)
+ * @example rfc2822DateTime.test("2024-03-15T14:30:00Z")            // false (ISO shape)
+ */
 export const rfc2822DateTime = /^(?:(Mon|Tue|Wed|Thu|Fri|Sat|Sun), )?(\d{1,2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2})(?::(\d{2}))? (UT|GMT|EST|EDT|CST|CDT|MST|MDT|PST|PDT|[+-]\d{4})$/;

package/dist/regex/rfc-3339.d.ts

@@ -1 +1,20 @@
+/**
+ * RegExp matching an RFC 3339 §5.6 date-time: ISO 8601 with a mandatory offset
+ * (`Z` or `±HH:MM`).
+ *
+ * - Separator may be `T`, `t`, or a space.
+ * - Offset is mandatory. GMT's own zoned strings with a bracketed IANA zone annotation
+ *   (`"...+00:00[UTC]"`) do NOT match — use `calendarZonedDateTime` for those.
+ * - Shape-only validation; real calendar validation is delegated to
+ *   `Temporal.Instant.from` in `parseRfc3339`.
+ * - Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second,
+ *   7 fractional (optional), 8 offset.
+ *
+ * @example rfc3339DateTime.test("2024-03-15T14:30:00-04:00")      // true
+ * @example rfc3339DateTime.test("2024-03-15t14:30:00z")           // true
+ * @example rfc3339DateTime.test("2024-03-15 14:30:00Z")           // true (space separator)
+ * @example rfc3339DateTime.test("2024-03-15T14:30:00")           // false (no offset)
+ * @example rfc3339DateTime.test("2024-03-15T14:30:00+00:00[UTC]") // false (bracketed zone)
+ * @example rfc3339DateTime.test("2024-3-15T14:30:00Z")            // false (unpadded)
+ */
 export declare const rfc3339DateTime: RegExp;

package/dist/regex/rfc-3339.js

@@ -1,7 +1,20 @@
-// RFC 3339 §5.6 date-time — the same field grammar as ISO 8601 but with a
-// *mandatory* offset (Z or ±HH:MM) and a date/time separator that may be
-// "T", "t", or " ". GMT's own zoned strings additionally carry a bracketed
-// IANA zone annotation ("...+00:00[UTC]") that RFC 3339 does not permit,
-// which is why this needs its own regex rather than reusing `plainDateTime`
-// or `zoned`-style patterns (see roadmap J13's RFC 3339 go/no-go decision).
+/**
+ * RegExp matching an RFC 3339 §5.6 date-time: ISO 8601 with a mandatory offset
+ * (`Z` or `±HH:MM`).
+ *
+ * - Separator may be `T`, `t`, or a space.
+ * - Offset is mandatory. GMT's own zoned strings with a bracketed IANA zone annotation
+ *   (`"...+00:00[UTC]"`) do NOT match — use `calendarZonedDateTime` for those.
+ * - Shape-only validation; real calendar validation is delegated to
+ *   `Temporal.Instant.from` in `parseRfc3339`.
+ * - Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second,
+ *   7 fractional (optional), 8 offset.
+ *
+ * @example rfc3339DateTime.test("2024-03-15T14:30:00-04:00")      // true
+ * @example rfc3339DateTime.test("2024-03-15t14:30:00z")           // true
+ * @example rfc3339DateTime.test("2024-03-15 14:30:00Z")           // true (space separator)
+ * @example rfc3339DateTime.test("2024-03-15T14:30:00")           // false (no offset)
+ * @example rfc3339DateTime.test("2024-03-15T14:30:00+00:00[UTC]") // false (bracketed zone)
+ * @example rfc3339DateTime.test("2024-3-15T14:30:00Z")            // false (unpadded)
+ */
 export const rfc3339DateTime = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])[Tt ](0[0-9]|1[0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(\.[0-9]{1,9})?(Z|z|[+-][0-9]{2}:[0-9]{2})$/;

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

@@ -1 +1,15 @@
+/**
+ * RegExp matching an ANSI SQL / ODBC timestamp literal: `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`.
+ *
+ * @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("2024-3-5 14:30:00")             // false (unpadded)
+ * @example sqlDateTime.test("2024-03-15 14:30:60")           // false (invalid second)
+ */
 export declare const sqlDateTime: RegExp;

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

@@ -1,7 +1,15 @@
-// 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.
+/**
+ * RegExp matching an ANSI SQL / ODBC timestamp literal: `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`.
+ *
+ * @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("2024-3-5 14:30:00")             // false (unpadded)
+ * @example sqlDateTime.test("2024-03-15 14:30:60")           // false (invalid second)
+ */
 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})?)?$/;

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

@@ -1 +1,22 @@
+/**
+ * RegExp matching a timezone identifier in one of three forms:
+ *
+ *  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`.
+ *
+ * @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)
+ */
 export declare const timeZoneLike: RegExp;

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

@@ -1 +1,22 @@
+/**
+ * RegExp matching a timezone identifier in one of three forms:
+ *
+ *  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`.
+ *
+ * @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)
+ */
 export const timeZoneLike = /^(?:UTC|GMT|[A-Za-z_+-]+(?:\/[A-Za-z0-9_+-]+)+)$/;

package/dist/regex/time.d.ts

@@ -1,6 +1,65 @@
+/**
+ * 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 an ISO 8601 second: `00`–`59`.
+ *
+ * @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)
+ */
 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("0")         // false (must be 1–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.
+ */
 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.
+ * - Shape-only validation; real field validation is delegated to
+ *   `Temporal.PlainTime.from` in `parseTime`.
+ *
+ * Capture groups: 1 hour, 2 minute, 3 second (optional), 4 fractional (optional).
+ *
+ * @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)
+ */
 export declare const plainTime: RegExp;