@northguild/gmt 1.14.2 → 1.16.0

package/dist/precision/convert/toPgMicroseconds.js

@@ -0,0 +1,42 @@
+import { MIN_PG_MICROSECONDS, NANOSECONDS_PER_MICROSECOND, parseInstantNanoseconds, PG_EPOCH_OFFSET_MICROSECONDS, } from "../../internal/index.js";
+import { truncateNanoseconds } from "../calculate/index.js";
+/**
+ * Convert an ISO 8601 instant string to PostgreSQL's internal `timestamptz` value.
+ *
+ * - PostgreSQL stores a `timestamp`/`timestamptz` as a signed 64-bit count of microseconds
+ *   since 2000-01-01T00:00:00Z — not since the Unix epoch. The wire protocol's binary format
+ *   carries this same value; only the text format and the client libraries convert to 1970.
+ * - Sub-microsecond digits floor away, via `truncateNanoseconds(..., "us")`, so the grid stays
+ *   uniform either side of the epoch. `timestamptz` has no finer resolution to write them to.
+ * - **Instants outside PostgreSQL's own timestamp range are invalid input.** It starts at
+ *   `-004713-11-24T00:00:00Z` (Julian Day 0 — the manual's "4713 BC", counted in the Julian
+ *   calendar), which is 40× later than the earliest instant `Temporal` can represent, so an
+ *   in-range `Temporal` instant is not automatically an in-range PostgreSQL one. The upper
+ *   end is the other way round: PostgreSQL stops at 294276 AD, past what `Temporal` holds,
+ *   so the instant range binds there first.
+ * - Returns `0n` on invalid input. `0n` is also the PostgreSQL epoch itself (2000-01-01) —
+ *   validate the string first with `isValidInstant` when the two must be told apart.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
+ * @returns microseconds since 2000-01-01 as a bigint, or 0n on invalid input
+ *
+ * @example toPgMicroseconds("2000-01-01T00:00:00Z") // 0n — the PostgreSQL epoch
+ * @example toPgMicroseconds("1970-01-01T00:00:00Z") // -946684800000000n
+ * @example toPgMicroseconds("2024-03-10T12:34:56.789Z") // 763389296789000n
+ * @example toPgMicroseconds("2024-03-10T12:00:00.123456789Z") // 763387200123456n — floors to microseconds
+ * @example toPgMicroseconds("-005000-01-01T00:00:00Z") // 0n — before PostgreSQL's 4713 BC minimum
+ * @example toPgMicroseconds("2024-03-10T12:00:00") // 0n — no offset designator
+ * @example toPgMicroseconds("invalid") // 0n
+ */
+export function toPgMicroseconds(isoString) {
+    const nanoseconds = parseInstantNanoseconds(isoString);
+    if (nanoseconds === null) {
+        return 0n;
+    }
+    const microseconds = truncateNanoseconds(nanoseconds, "us") / NANOSECONDS_PER_MICROSECOND -
+        PG_EPOCH_OFFSET_MICROSECONDS;
+    if (microseconds < MIN_PG_MICROSECONDS) {
+        return 0n;
+    }
+    return microseconds;
+}

package/dist/precision/format/formatNanoseconds.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Format nanoseconds since the Unix epoch as a decimal string, for JSON and other
+ * text transports.
+ *
+ * - `JSON.stringify` throws a `TypeError` on a `bigint`, so a nanosecond timestamp cannot
+ *   go into a JSON payload as-is. This is the bridge every consumer needs; do not hand-roll it.
+ * - The output is a canonical decimal integer: an optional `-`, then digits, no leading zeros,
+ *   no exponent, no separators. `parseNanoseconds` is its exact inverse.
+ * - **Put the result in JSON as a string, not a number.** It is itself only the value —
+ *   `{ observedAt: formatNanoseconds(n) }` serialises to `{"observedAt":"1710072000123456789"}`.
+ *   Emitted unquoted it is a JSON number, and `JSON.parse` rounds it back through a double
+ *   to `1710072000123456800` — the exact loss this namespace exists to prevent.
+ * - Rejects values outside the range `Temporal.Instant` can represent
+ *   (±8_640_000_000_000_000_000_000n), so anything formatted here can be read back and rendered.
+ * - Returns "" on invalid input.
+ *
+ * @param nanoseconds nanoseconds since the Unix epoch (bigint)
+ * @returns decimal string form of the value, or "" on invalid input
+ *
+ * @example formatNanoseconds(1710072000123456789n) // "1710072000123456789"
+ * @example formatNanoseconds(0n) // "0"
+ * @example formatNanoseconds(-1000000000n) // "-1000000000"
+ * @example formatNanoseconds(1710072000123456789) // "" — number, not bigint
+ * @example formatNanoseconds(8640000000000000000001n) // "" — outside the instant range
+ */
+export declare function formatNanoseconds(nanoseconds: bigint): string;

package/dist/precision/format/formatNanoseconds.js

@@ -0,0 +1,32 @@
+import { isValidEpochNanoseconds } from "../../internal/index.js";
+/**
+ * Format nanoseconds since the Unix epoch as a decimal string, for JSON and other
+ * text transports.
+ *
+ * - `JSON.stringify` throws a `TypeError` on a `bigint`, so a nanosecond timestamp cannot
+ *   go into a JSON payload as-is. This is the bridge every consumer needs; do not hand-roll it.
+ * - The output is a canonical decimal integer: an optional `-`, then digits, no leading zeros,
+ *   no exponent, no separators. `parseNanoseconds` is its exact inverse.
+ * - **Put the result in JSON as a string, not a number.** It is itself only the value —
+ *   `{ observedAt: formatNanoseconds(n) }` serialises to `{"observedAt":"1710072000123456789"}`.
+ *   Emitted unquoted it is a JSON number, and `JSON.parse` rounds it back through a double
+ *   to `1710072000123456800` — the exact loss this namespace exists to prevent.
+ * - Rejects values outside the range `Temporal.Instant` can represent
+ *   (±8_640_000_000_000_000_000_000n), so anything formatted here can be read back and rendered.
+ * - Returns "" on invalid input.
+ *
+ * @param nanoseconds nanoseconds since the Unix epoch (bigint)
+ * @returns decimal string form of the value, or "" on invalid input
+ *
+ * @example formatNanoseconds(1710072000123456789n) // "1710072000123456789"
+ * @example formatNanoseconds(0n) // "0"
+ * @example formatNanoseconds(-1000000000n) // "-1000000000"
+ * @example formatNanoseconds(1710072000123456789) // "" — number, not bigint
+ * @example formatNanoseconds(8640000000000000000001n) // "" — outside the instant range
+ */
+export function formatNanoseconds(nanoseconds) {
+    if (!isValidEpochNanoseconds(nanoseconds)) {
+        return "";
+    }
+    return nanoseconds.toString();
+}

package/dist/precision/format/index.d.ts

@@ -0,0 +1 @@
+export * from "./formatNanoseconds.js";

package/dist/precision/format/index.js

@@ -0,0 +1 @@
+export * from "./formatNanoseconds.js";

package/dist/precision/index.d.ts

@@ -0,0 +1,6 @@
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";
+export * from "./convert/index.js";
+export * from "./format/index.js";
+export * from "./parse/index.js";
+export * from "./validate/index.js";

package/dist/precision/index.js

@@ -0,0 +1,7 @@
+// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
+export * from "@js-temporal/polyfill";
+export * from "./calculate/index.js";
+export * from "./convert/index.js";
+export * from "./format/index.js";
+export * from "./parse/index.js";
+export * from "./validate/index.js";

package/dist/precision/parse/index.d.ts

@@ -0,0 +1 @@
+export * from "./parseNanoseconds.js";

package/dist/precision/parse/index.js

@@ -0,0 +1 @@
+export * from "./parseNanoseconds.js";

package/dist/precision/parse/parseNanoseconds.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parse a decimal string produced by `formatNanoseconds` — typically one field of a JSON
+ * payload — back to nanoseconds since the Unix epoch.
+ *
+ * - Takes the string *value*, not JSON text: pass `JSON.parse(payload).observedAt`, not the
+ *   payload itself. A quoted `"\"123\""` is rejected, because the quotes are not part of a
+ *   decimal integer.
+ * - Accepts only a canonical decimal integer — an optional `-` then digits with no leading
+ *   zeros. Exponents, fractions, hex, separators, a `+` sign and surrounding whitespace are
+ *   rejected rather than coerced, so a payload written by another language's serialiser
+ *   either reads back exactly or fails loudly.
+ * - Rejects values outside the range `Temporal.Instant` can represent
+ *   (±8_640_000_000_000_000_000_000n).
+ * - Returns `0n` on invalid input. `0n` is also the epoch itself — `isValidNanoPattern`
+ *   tells the two apart, and accepts exactly what this parses.
+ *
+ * @param value decimal string form of a nanosecond timestamp (e.g. "1710072000123456789")
+ * @returns nanoseconds since the Unix epoch as a bigint, or 0n on invalid input
+ *
+ * @example parseNanoseconds("1710072000123456789") // 1710072000123456789n
+ * @example parseNanoseconds("-1000000000") // -1000000000n
+ * @example parseNanoseconds("1.5") // 0n
+ * @example parseNanoseconds("1e18") // 0n
+ * @example parseNanoseconds("8640000000000000000001") // 0n — outside the instant range
+ * @example parseNanoseconds(1710072000123456789) // 0n — number, not string
+ */
+export declare function parseNanoseconds(value: string): bigint;

package/dist/precision/parse/parseNanoseconds.js

@@ -0,0 +1,32 @@
+import { isValidNanoPattern } from "../validate/isValidNanoPattern.js";
+/**
+ * Parse a decimal string produced by `formatNanoseconds` — typically one field of a JSON
+ * payload — back to nanoseconds since the Unix epoch.
+ *
+ * - Takes the string *value*, not JSON text: pass `JSON.parse(payload).observedAt`, not the
+ *   payload itself. A quoted `"\"123\""` is rejected, because the quotes are not part of a
+ *   decimal integer.
+ * - Accepts only a canonical decimal integer — an optional `-` then digits with no leading
+ *   zeros. Exponents, fractions, hex, separators, a `+` sign and surrounding whitespace are
+ *   rejected rather than coerced, so a payload written by another language's serialiser
+ *   either reads back exactly or fails loudly.
+ * - Rejects values outside the range `Temporal.Instant` can represent
+ *   (±8_640_000_000_000_000_000_000n).
+ * - Returns `0n` on invalid input. `0n` is also the epoch itself — `isValidNanoPattern`
+ *   tells the two apart, and accepts exactly what this parses.
+ *
+ * @param value decimal string form of a nanosecond timestamp (e.g. "1710072000123456789")
+ * @returns nanoseconds since the Unix epoch as a bigint, or 0n on invalid input
+ *
+ * @example parseNanoseconds("1710072000123456789") // 1710072000123456789n
+ * @example parseNanoseconds("-1000000000") // -1000000000n
+ * @example parseNanoseconds("1.5") // 0n
+ * @example parseNanoseconds("1e18") // 0n
+ * @example parseNanoseconds("8640000000000000000001") // 0n — outside the instant range
+ * @example parseNanoseconds(1710072000123456789) // 0n — number, not string
+ */
+export function parseNanoseconds(value) {
+    // Shape, length and range all live in the validator, so `isValidNanoPattern(v)` and
+    // "parseNanoseconds(v) is a real value" can never disagree.
+    return isValidNanoPattern(value) ? BigInt(value) : 0n;
+}

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

@@ -0,0 +1,3 @@
+export * from "./isValidInstant.js";
+export * from "./isValidNanoPattern.js";
+export * from "./isValidNanoseconds.js";

package/dist/precision/validate/index.js

@@ -0,0 +1,3 @@
+export * from "./isValidInstant.js";
+export * from "./isValidNanoPattern.js";
+export * from "./isValidNanoseconds.js";

package/dist/precision/validate/isValidInstant.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Validate whether a string is an ISO 8601 instant string the `precision/` namespace accepts.
+ *
+ * The predicate `toNanoseconds` was missing. `toNanoseconds` returns `0n` for both the epoch
+ * and a rejected string, and the only public validator close enough to reach for —
+ * `isValidUtc` — is *narrower* than this grammar: it gates on GMT's stricter
+ * `<date>T<time>Z` shape and rejects the offsets and bracketed zones `toNanoseconds` parses. Validating with it discards valid
+ * input. This accepts exactly what `toNanoseconds` does, so the two never disagree.
+ *
+ * - Requires an offset designator (`Z`, `±HH:MM`); a bracketed IANA zone may follow, but a
+ *   bracket alone is not enough.
+ * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
+ *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
+ *   with the offset is not checked.
+ * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
+ *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
+ *   lower-case `z` and an hour-only time or offset return `false`, although
+ *   `Temporal.Instant.from` reads them.
+ * - Rejects leap seconds in every separator and format variant.
+ * - Reads RFC 9557 annotations as `Temporal.Instant.from` does: a calendar or elective annotation
+ *   is ignored, and an unknown critical one (`[!foo=bar]`) is rejected.
+ * - Returns `false` for non-strings and empty strings.
+ *
+ * @param value candidate ISO 8601 instant string
+ * @returns boolean indicating whether `toNanoseconds` will parse it
+ *
+ * @example isValidInstant("2024-03-10T12:00:00Z") // true
+ * @example isValidInstant("1970-01-01T00:00:00Z") // true — the epoch, where toNanoseconds returns 0n
+ * @example isValidInstant("2024-03-10T12:00:00-05:00[America/New_York]") // true
+ * @example isValidInstant("2024-03-10T12:00:00Z[Not/AZone]") // true — the zone annotation is not checked
+ * @example isValidInstant("2024-03-10T12:00:00-05:00") // true — isValidUtc says false
+ * @example isValidInstant("2024-03-10 12:00:00Z") // false — space separator (extended format only)
+ * @example isValidInstant("2024-03-10T12:00:00") // false — no offset designator
+ * @example isValidInstant("2016-12-31T23:59:60Z") // false — leap second
+ * @example isValidInstant("invalid") // false
+ */
+export declare function isValidInstant(value: string): boolean;

package/dist/precision/validate/isValidInstant.js

@@ -0,0 +1,40 @@
+import { parseInstantNanoseconds } from "../../internal/index.js";
+/**
+ * Validate whether a string is an ISO 8601 instant string the `precision/` namespace accepts.
+ *
+ * The predicate `toNanoseconds` was missing. `toNanoseconds` returns `0n` for both the epoch
+ * and a rejected string, and the only public validator close enough to reach for —
+ * `isValidUtc` — is *narrower* than this grammar: it gates on GMT's stricter
+ * `<date>T<time>Z` shape and rejects the offsets and bracketed zones `toNanoseconds` parses. Validating with it discards valid
+ * input. This accepts exactly what `toNanoseconds` does, so the two never disagree.
+ *
+ * - Requires an offset designator (`Z`, `±HH:MM`); a bracketed IANA zone may follow, but a
+ *   bracket alone is not enough.
+ * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
+ *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
+ *   with the offset is not checked.
+ * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
+ *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
+ *   lower-case `z` and an hour-only time or offset return `false`, although
+ *   `Temporal.Instant.from` reads them.
+ * - Rejects leap seconds in every separator and format variant.
+ * - Reads RFC 9557 annotations as `Temporal.Instant.from` does: a calendar or elective annotation
+ *   is ignored, and an unknown critical one (`[!foo=bar]`) is rejected.
+ * - Returns `false` for non-strings and empty strings.
+ *
+ * @param value candidate ISO 8601 instant string
+ * @returns boolean indicating whether `toNanoseconds` will parse it
+ *
+ * @example isValidInstant("2024-03-10T12:00:00Z") // true
+ * @example isValidInstant("1970-01-01T00:00:00Z") // true — the epoch, where toNanoseconds returns 0n
+ * @example isValidInstant("2024-03-10T12:00:00-05:00[America/New_York]") // true
+ * @example isValidInstant("2024-03-10T12:00:00Z[Not/AZone]") // true — the zone annotation is not checked
+ * @example isValidInstant("2024-03-10T12:00:00-05:00") // true — isValidUtc says false
+ * @example isValidInstant("2024-03-10 12:00:00Z") // false — space separator (extended format only)
+ * @example isValidInstant("2024-03-10T12:00:00") // false — no offset designator
+ * @example isValidInstant("2016-12-31T23:59:60Z") // false — leap second
+ * @example isValidInstant("invalid") // false
+ */
+export function isValidInstant(value) {
+    return parseInstantNanoseconds(value) !== null;
+}

package/dist/precision/validate/isValidNanoPattern.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Validate whether a string is a nanosecond timestamp `parseNanoseconds` will parse.
+ *
+ * `parseNanoseconds` returns `0n` for both `"0"` and garbage, so this is how the two are
+ * told apart — the check its own JSDoc asks callers to make.
+ *
+ * - Shape **and** range: a canonical decimal integer (optional `-`, digits, no leading
+ *   zeros) that also falls inside what `Temporal.Instant` can represent. Shape alone is
+ *   `nanosecondDecimal` in `regex/`.
+ * - Length is checked before `BigInt`, so an arbitrarily long payload string is rejected
+ *   rather than converted.
+ * - Takes the string *value*, not JSON text — `JSON.parse(payload).observedAt`, not the
+ *   payload. A quoted `"\"123\""` is not a decimal integer.
+ * - Returns `false` for non-strings.
+ *
+ * @param value candidate decimal string form of a nanosecond timestamp
+ * @returns boolean indicating whether `parseNanoseconds` will parse it
+ *
+ * @example isValidNanoPattern("1710072000123456789") // true
+ * @example isValidNanoPattern("0") // true — the epoch, where parseNanoseconds returns 0n
+ * @example isValidNanoPattern("-1000000000") // true
+ * @example isValidNanoPattern("8640000000000000000001") // false — outside the instant range
+ * @example isValidNanoPattern("01") // false — leading zero
+ * @example isValidNanoPattern("1e18") // false
+ * @example isValidNanoPattern("garbage") // false
+ */
+export declare function isValidNanoPattern(value: string): boolean;

package/dist/precision/validate/isValidNanoPattern.js

@@ -0,0 +1,40 @@
+import { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "../../internal/index.js";
+import { nanosecondDecimal } from "../../regex/nanoseconds.js";
+/**
+ * Validate whether a string is a nanosecond timestamp `parseNanoseconds` will parse.
+ *
+ * `parseNanoseconds` returns `0n` for both `"0"` and garbage, so this is how the two are
+ * told apart — the check its own JSDoc asks callers to make.
+ *
+ * - Shape **and** range: a canonical decimal integer (optional `-`, digits, no leading
+ *   zeros) that also falls inside what `Temporal.Instant` can represent. Shape alone is
+ *   `nanosecondDecimal` in `regex/`.
+ * - Length is checked before `BigInt`, so an arbitrarily long payload string is rejected
+ *   rather than converted.
+ * - Takes the string *value*, not JSON text — `JSON.parse(payload).observedAt`, not the
+ *   payload. A quoted `"\"123\""` is not a decimal integer.
+ * - Returns `false` for non-strings.
+ *
+ * @param value candidate decimal string form of a nanosecond timestamp
+ * @returns boolean indicating whether `parseNanoseconds` will parse it
+ *
+ * @example isValidNanoPattern("1710072000123456789") // true
+ * @example isValidNanoPattern("0") // true — the epoch, where parseNanoseconds returns 0n
+ * @example isValidNanoPattern("-1000000000") // true
+ * @example isValidNanoPattern("8640000000000000000001") // false — outside the instant range
+ * @example isValidNanoPattern("01") // false — leading zero
+ * @example isValidNanoPattern("1e18") // false
+ * @example isValidNanoPattern("garbage") // false
+ */
+export function isValidNanoPattern(value) {
+    if (typeof value !== "string" || !nanosecondDecimal.test(value)) {
+        return false;
+    }
+    // Out of range by inspection once it is longer than MAX_EPOCH_NANOSECONDS, and stopping
+    // here keeps BigInt off an arbitrarily long payload string.
+    const digits = value.startsWith("-") ? value.length - 1 : value.length;
+    if (digits > MAX_EPOCH_NANOSECOND_DIGITS) {
+        return false;
+    }
+    return isValidEpochNanoseconds(BigInt(value));
+}

package/dist/precision/validate/isValidNanoseconds.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Validate whether a value is an epoch-nanosecond `bigint` the `precision/` namespace accepts.
+ *
+ * Every `precision/` function gates on this range, so anything it accepts is renderable by
+ * `fromNanoseconds`. Reach for it before `truncateNanoseconds`, whose `0n` return is both a
+ * legitimate result and the invalid-input sentinel.
+ *
+ * - Requires a `bigint`. A `number` is rejected outright rather than coerced: nanoseconds
+ *   since the epoch passed `Number.MAX_SAFE_INTEGER` in April 1970, so a `number` cannot
+ *   carry one exactly and silently accepting it would defeat the namespace.
+ * - The range is ±8_640_000_000_000_000_000_000n — what `Temporal.Instant` can represent.
+ * - **A span is not an epoch nanosecond value.** `spanNs` reaches twice this range, because
+ *   it measures a duration rather than naming an instant. Do not validate one with this.
+ *
+ * @param value candidate epoch-nanosecond value
+ * @returns boolean indicating whether the value is an in-range epoch-nanosecond bigint
+ *
+ * @example isValidNanoseconds(0n) // true — the epoch
+ * @example isValidNanoseconds(1710072000123456789n) // true
+ * @example isValidNanoseconds(-1000000000n) // true
+ * @example isValidNanoseconds(8640000000000000000001n) // false — outside the instant range
+ * @example isValidNanoseconds(0) // false — number, not bigint
+ * @example isValidNanoseconds("0") // false
+ */
+export declare function isValidNanoseconds(value: unknown): value is bigint;

package/dist/precision/validate/isValidNanoseconds.js

@@ -0,0 +1,28 @@
+import { isValidEpochNanoseconds } from "../../internal/index.js";
+/**
+ * Validate whether a value is an epoch-nanosecond `bigint` the `precision/` namespace accepts.
+ *
+ * Every `precision/` function gates on this range, so anything it accepts is renderable by
+ * `fromNanoseconds`. Reach for it before `truncateNanoseconds`, whose `0n` return is both a
+ * legitimate result and the invalid-input sentinel.
+ *
+ * - Requires a `bigint`. A `number` is rejected outright rather than coerced: nanoseconds
+ *   since the epoch passed `Number.MAX_SAFE_INTEGER` in April 1970, so a `number` cannot
+ *   carry one exactly and silently accepting it would defeat the namespace.
+ * - The range is ±8_640_000_000_000_000_000_000n — what `Temporal.Instant` can represent.
+ * - **A span is not an epoch nanosecond value.** `spanNs` reaches twice this range, because
+ *   it measures a duration rather than naming an instant. Do not validate one with this.
+ *
+ * @param value candidate epoch-nanosecond value
+ * @returns boolean indicating whether the value is an in-range epoch-nanosecond bigint
+ *
+ * @example isValidNanoseconds(0n) // true — the epoch
+ * @example isValidNanoseconds(1710072000123456789n) // true
+ * @example isValidNanoseconds(-1000000000n) // true
+ * @example isValidNanoseconds(8640000000000000000001n) // false — outside the instant range
+ * @example isValidNanoseconds(0) // false — number, not bigint
+ * @example isValidNanoseconds("0") // false
+ */
+export function isValidNanoseconds(value) {
+    return isValidEpochNanoseconds(value);
+}

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

@@ -1 +1,31 @@
+/**
+ * RegExp matching a calendar-annotated PlainDate string in the RFC 9557 form Temporal writes and
+ * reads: the ISO 8601 date, then one `[u-ca=<id>]` calendar annotation. The digits are always
+ * ISO; the annotation only names the calendar the date is presented in (RFC 9557 §3.3). This is
+ * exactly `Temporal.PlainDate#toString()` for a non-ISO calendar.
+ *
+ * YEAR: Temporal's `DateYear`, four digits or a sign plus six digits (`2024`, `+275760`,
+ * `-271821`), with `-000000` rejected as Temporal's early error rejects it.
+ *
+ * ANNOTATION: RFC 9557's `u-ca` key, lower-case, optionally with the critical flag
+ * (`[!u-ca=hebrew]`, which Temporal's `ParseISODateTime` accepts for a single calendar
+ * annotation). The value is alphanumeric components joined by single hyphens, in any case;
+ * `CanonicalizeCalendar` validates and lower-cases it. `;era=` is not RFC 9557 syntax.
+ *
+ * A match proves shape only: `Temporal.PlainDate.from` validates the date and the calendar id.
+ * This is the written form. GMT's calendar functions read more (`isValidCalendarDate`): a date-time
+ * in `plainDateTime`'s strict shape before the annotations (`"2024-10-03T14:30[u-ca=hebrew]"`, read
+ * as its date), and the rest of Temporal's annotation grammar, such as a time zone annotation or an
+ * elective `[foo=bar]`, which Temporal ignores. Basic format, a space or lower-case `t` separator
+ * and a UTC offset are rejected there as well as here.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 critical flag (`"!"` or undefined), 5 calendar id.
+ *
+ * @example calendarDate.test("2024-10-03[u-ca=hebrew]")          // true
+ * @example calendarDate.test("+275760-09-13[u-ca=hebrew]")       // true
+ * @example calendarDate.test("2024-10-03[!u-ca=japanese]")       // true (critical flag)
+ * @example calendarDate.test("0006-10-03[u-ca=japanese;era=reiwa]") // false (not RFC 9557)
+ * @example calendarDate.test("279517-10-11[u-ca=hebrew]")        // false (a six-digit year needs a sign)
+ * @example calendarDate.test("2024-03-15")                       // false (no calendar annotation)
+ */
 export declare const calendarDate: RegExp;

package/dist/regex/calendar-date.js

@@ -1,11 +1,31 @@
-// 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.
-export const calendarDate = /^(\d{4,6})-(\d{2})-(\d{2})\[u-ca=([a-z][a-z0-9-]*)(?:;era=([a-z]+))?\]$/;
+/**
+ * RegExp matching a calendar-annotated PlainDate string in the RFC 9557 form Temporal writes and
+ * reads: the ISO 8601 date, then one `[u-ca=<id>]` calendar annotation. The digits are always
+ * ISO; the annotation only names the calendar the date is presented in (RFC 9557 §3.3). This is
+ * exactly `Temporal.PlainDate#toString()` for a non-ISO calendar.
+ *
+ * YEAR: Temporal's `DateYear`, four digits or a sign plus six digits (`2024`, `+275760`,
+ * `-271821`), with `-000000` rejected as Temporal's early error rejects it.
+ *
+ * ANNOTATION: RFC 9557's `u-ca` key, lower-case, optionally with the critical flag
+ * (`[!u-ca=hebrew]`, which Temporal's `ParseISODateTime` accepts for a single calendar
+ * annotation). The value is alphanumeric components joined by single hyphens, in any case;
+ * `CanonicalizeCalendar` validates and lower-cases it. `;era=` is not RFC 9557 syntax.
+ *
+ * A match proves shape only: `Temporal.PlainDate.from` validates the date and the calendar id.
+ * This is the written form. GMT's calendar functions read more (`isValidCalendarDate`): a date-time
+ * in `plainDateTime`'s strict shape before the annotations (`"2024-10-03T14:30[u-ca=hebrew]"`, read
+ * as its date), and the rest of Temporal's annotation grammar, such as a time zone annotation or an
+ * elective `[foo=bar]`, which Temporal ignores. Basic format, a space or lower-case `t` separator
+ * and a UTC offset are rejected there as well as here.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 critical flag (`"!"` or undefined), 5 calendar id.
+ *
+ * @example calendarDate.test("2024-10-03[u-ca=hebrew]")          // true
+ * @example calendarDate.test("+275760-09-13[u-ca=hebrew]")       // true
+ * @example calendarDate.test("2024-10-03[!u-ca=japanese]")       // true (critical flag)
+ * @example calendarDate.test("0006-10-03[u-ca=japanese;era=reiwa]") // false (not RFC 9557)
+ * @example calendarDate.test("279517-10-11[u-ca=hebrew]")        // false (a six-digit year needs a sign)
+ * @example calendarDate.test("2024-03-15")                       // false (no calendar annotation)
+ */
+export const calendarDate = /^(\d{4}|\+\d{6}|-(?!0{6})\d{6})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])\[(!)?u-ca=([A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)\]$/;

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

@@ -1 +1,30 @@
+/**
+ * RegExp matching a calendar-annotated ZonedDateTime string in the RFC 9557 form Temporal writes
+ * and reads — the zoned sibling of `calendarDate` (regex/calendar-date.ts):
+ *
+ *   <date>T<time><offset>[<timeZone>][u-ca=<id>]
+ *   2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]
+ *
+ * This is exactly `Temporal.ZonedDateTime#toString()` for a non-ISO calendar. The digits are ISO
+ * and the calendar annotation follows the time zone annotation, in RFC 9557 §4.1 order. The date,
+ * time and offset are ISO 8601 extended format with an upper-case `Z`. The date
+ * half and the annotation are the same groups as `calendarDate`'s. The offset is optional; the
+ * time zone annotation may carry RFC 9557's critical flag (`[!America/New_York]`), and so may the
+ * calendar annotation.
+ *
+ * A match proves shape only: `internal/calendarZonedString.ts` hands the string to
+ * `Temporal.ZonedDateTime.from` (zone, offset, DST) and the calendar id to Temporal's
+ * `CanonicalizeCalendar`. This is the written form. GMT's calendar functions read more
+ * (`isValidCalendarZonedDateTime`): every date-time `isValidZonedDateTime` reads (the functions
+ * take the same strings as the non-calendar zoned functions, then the calendar annotation), and
+ * the rest of Temporal's annotation grammar, such as an elective `[foo=bar]`, which Temporal
+ * ignores.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 time, 5 offset (optional), 6 time zone annotation
+ * (with its critical flag, if any), 7 calendar critical flag (`"!"` or undefined), 8 calendar id.
+ *
+ * @example calendarZonedDateTime.test("2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]") // true
+ * @example calendarZonedDateTime.test("2024-02-24T14:30:00-05:00[u-ca=hebrew][America/New_York]") // false (calendar before zone)
+ * @example calendarZonedDateTime.test("2024-03-15T14:30:00Z[UTC]") // false (no calendar annotation)
+ */
 export declare const calendarZonedDateTime: RegExp;

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

@@ -1,41 +1,30 @@
-// 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).
-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]+))?\]\[([^[\]]+)\]$/;
+/**
+ * RegExp matching a calendar-annotated ZonedDateTime string in the RFC 9557 form Temporal writes
+ * and reads — the zoned sibling of `calendarDate` (regex/calendar-date.ts):
+ *
+ *   <date>T<time><offset>[<timeZone>][u-ca=<id>]
+ *   2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]
+ *
+ * This is exactly `Temporal.ZonedDateTime#toString()` for a non-ISO calendar. The digits are ISO
+ * and the calendar annotation follows the time zone annotation, in RFC 9557 §4.1 order. The date,
+ * time and offset are ISO 8601 extended format with an upper-case `Z`. The date
+ * half and the annotation are the same groups as `calendarDate`'s. The offset is optional; the
+ * time zone annotation may carry RFC 9557's critical flag (`[!America/New_York]`), and so may the
+ * calendar annotation.
+ *
+ * A match proves shape only: `internal/calendarZonedString.ts` hands the string to
+ * `Temporal.ZonedDateTime.from` (zone, offset, DST) and the calendar id to Temporal's
+ * `CanonicalizeCalendar`. This is the written form. GMT's calendar functions read more
+ * (`isValidCalendarZonedDateTime`): every date-time `isValidZonedDateTime` reads (the functions
+ * take the same strings as the non-calendar zoned functions, then the calendar annotation), and
+ * the rest of Temporal's annotation grammar, such as an elective `[foo=bar]`, which Temporal
+ * ignores.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 time, 5 offset (optional), 6 time zone annotation
+ * (with its critical flag, if any), 7 calendar critical flag (`"!"` or undefined), 8 calendar id.
+ *
+ * @example calendarZonedDateTime.test("2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]") // true
+ * @example calendarZonedDateTime.test("2024-02-24T14:30:00-05:00[u-ca=hebrew][America/New_York]") // false (calendar before zone)
+ * @example calendarZonedDateTime.test("2024-03-15T14:30:00Z[UTC]") // false (no calendar annotation)
+ */
+export const calendarZonedDateTime = /^(\d{4}|\+\d{6}|-(?!0{6})\d{6})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T(\d{2}:\d{2}(?::\d{2}(?:[.,]\d{1,9})?)?)((?:[+-]\d{2}:\d{2}(?::\d{2}(?:[.,]\d{1,9})?)?)|Z)?\[(!?[^[\]=!]+)\]\[(!)?u-ca=([A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)\]$/;