@northguild/gmt 1.17.0 → 1.19.0

package/dist/internal/ediGrammar.js

@@ -0,0 +1,384 @@
+/** What each half of a value of each kind is: a period of dates is two dates. */
+const VALUE_KIND = {
+    date: "date",
+    time: "time",
+    dateTime: "dateTime",
+    offsetDateTime: "offsetDateTime",
+    datePeriod: "date",
+    dateTimePeriod: "dateTime",
+    dateRange: "date",
+    dateTimeRange: "dateTime",
+};
+/** Hour, 00–23. */
+const HH = "([01][0-9]|2[0-3])";
+/** Minute, 00–59. */
+const MI = "([0-5][0-9])";
+/** The regex source of each part: one capture group, the field's whole range of digits. */
+const FRAGMENT = {
+    // Century and year: four digits.
+    CCYY: "(\\d{4})",
+    // Month, 01–12.
+    MM: "(0[1-9]|1[0-2])",
+    // Day of month, 01–31.
+    DD: "(0[1-9]|[12][0-9]|3[01])",
+    HH,
+    MI,
+    // Second, 00–59. `60` does not match: GMT rejects a leap second, which Temporal would read as 59.
+    SS: "([0-5][0-9])",
+    // Element 337: "D = tenths (0-9)". One digit.
+    SD: "(\\d)",
+    // Element 337: "DD = hundredths (00-99)". Two digits.
+    SDD: "(\\d{2})",
+    // 2379 codes 205 and 208: "Z is plus (+) or minus (-)", then hours and minutes.
+    ZS: "([+-])",
+    ZH: HH,
+    ZM: MI,
+    // 2379 codes 303 and 304: a signed hour `[+-]HH`, 00–23 (Rec 7 ¶12), or the literals `UTC` and
+    // `GMT`. Nothing else is read: no UN/EDIFACT text defines a zone abbreviation, and a sign or a
+    // digit outside a valid signed hour (`+24`, `000`) is a broken offset (GMT rule; see the file
+    // header).
+    ZZZ: "([+-](?:[01][0-9]|2[0-3])|UTC|GMT)",
+};
+/** The `ZHHMM` offset of 2379 codes 205 and 208: sign, hours, minutes. */
+const ZHHMM = ["ZS", "ZH", "ZM"];
+/** The parts' sources joined, anchored, flagless; a period's halves joined by `join`. */
+function grammarOf(layout, join) {
+    const source = (parts) => parts.map((part) => FRAGMENT[part]).join("");
+    const end = layout.end === undefined ? "" : `${join}${source(layout.end)}`;
+    return new RegExp(`^${source(layout.start)}${end}$`);
+}
+/** A grammar table from a layout table, in the layout table's key order. */
+function grammarsOf(layouts, join) {
+    const grammars = {};
+    for (const code of Object.keys(layouts)) {
+        grammars[code] = grammarOf(layouts[code], join);
+    }
+    return grammars;
+}
+/**
+ * The 11 UNTDID 2379 codes GMT reads, in directory order: a date (`102`), a date and time
+ * (`203`, `204`), a date and time with a `ZHHMM` offset (`205`, `208`), a date and time with
+ * three zone characters (`303`, `304`), a time (`401`, `402`) and a period (`718`, `719`).
+ *
+ * Every other 2379 code returns the sentinel; the file header lists the ones cut and why.
+ */
+export const EDIFACT_DTM_FORMATS = [
+    "102",
+    "203",
+    "204",
+    "205",
+    "208",
+    "303",
+    "304",
+    "401",
+    "402",
+    "718",
+    "719",
+];
+/**
+ * UNTDID 2379 code → its kind and its value's parts. Typed kind by kind from the public unions,
+ * so a missing code, and a code filed under a kind its union does not name, both fail typecheck.
+ */
+const EDIFACT_DTM_LAYOUT = {
+    // 102 CCYYMMDD — "Calendar date: C = Century ; Y = Year ; M = Month ; D = Day."
+    "102": { kind: "date", start: ["CCYY", "MM", "DD"] },
+    // 203 CCYYMMDDHHMM — "Calendar date including time with minutes"
+    "203": { kind: "dateTime", start: ["CCYY", "MM", "DD", "HH", "MI"] },
+    // 204 CCYYMMDDHHMMSS — "Calendar date including time with seconds"
+    "204": { kind: "dateTime", start: ["CCYY", "MM", "DD", "HH", "MI", "SS"] },
+    // 205 CCYYMMDDHHMMZHHMM — "Calendar date including time and time zone expressed in hours and minutes."
+    "205": {
+        kind: "offsetDateTime",
+        start: ["CCYY", "MM", "DD", "HH", "MI", ...ZHHMM],
+    },
+    // 208 CCYYMMDDHHMMSSZHHMM — "Calendar date including time with seconds, with Time Zone: … Z = leading plus/minus sign, HHMM = difference to UTC in Hours and Minutes." (D.12A on)
+    "208": {
+        kind: "offsetDateTime",
+        start: ["CCYY", "MM", "DD", "HH", "MI", "SS", ...ZHHMM],
+    },
+    // 303 CCYYMMDDHHMMZZZ — "See 203 plus Z=Time zone."
+    "303": {
+        kind: "offsetDateTime",
+        start: ["CCYY", "MM", "DD", "HH", "MI", "ZZZ"],
+    },
+    // 304 CCYYMMDDHHMMSSZZZ — "See 204 plus Z=Time zone."
+    "304": {
+        kind: "offsetDateTime",
+        start: ["CCYY", "MM", "DD", "HH", "MI", "SS", "ZZZ"],
+    },
+    // 401 HHMM — "Time without seconds: H = Hour; m = Minute."
+    "401": { kind: "time", start: ["HH", "MI"] },
+    // 402 HHMMSS — "Time with seconds: H = Hour; m = Minute; s = Seconds."
+    "402": { kind: "time", start: ["HH", "MI", "SS"] },
+    // 718 CCYYMMDD-CCYYMMDD — "A period of time specified by giving the start date followed by the end date (both including century)."
+    "718": {
+        kind: "datePeriod",
+        start: ["CCYY", "MM", "DD"],
+        end: ["CCYY", "MM", "DD"],
+    },
+    // 719 CCYYMMDDHHMM-CCYYMMDDHHMM — "A period of time which includes the century, year, month, day, hour and minute."
+    "719": {
+        kind: "dateTimePeriod",
+        start: ["CCYY", "MM", "DD", "HH", "MI"],
+        end: ["CCYY", "MM", "DD", "HH", "MI"],
+    },
+};
+/**
+ * UNTDID 2379 code → the anchored, flagless grammar of its value. A period's halves are run
+ * together with nothing between them: every directory read gives a period "without hyphen" (the
+ * file header quotes each entry).
+ */
+export const EDIFACT_DTM_GRAMMAR = grammarsOf(EDIFACT_DTM_LAYOUT, "");
+/**
+ * The 10 X12 1250 codes GMT reads: a date (`D8`, `DB`), a date and time (`DT`, `RTS`), a time
+ * (`TM`, `TS`), a range of dates (`RD8`, `RD`) and a range of date-times (`RDT`, `DTS`).
+ *
+ * The other 32 of the 42 codes return the sentinel; the file header lists the ones cut and why.
+ * `TS` is also a code of data element 623, with an unrelated meaning there.
+ */
+export const X12_DATE_TIME_PERIOD_FORMATS = ["D8", "DB", "DT", "RTS", "TM", "TS", "RD8", "RD", "RDT", "DTS"];
+/**
+ * X12 1250 code → its kind and its value's parts. Typed kind by kind from the public unions, so
+ * a missing code, and a code filed under a kind its union does not name, both fail typecheck.
+ */
+const X12_DATE_TIME_PERIOD_LAYOUT = {
+    // D8 CCYYMMDD — "Date Expressed in Format CCYYMMDD"
+    D8: { kind: "date", start: ["CCYY", "MM", "DD"] },
+    // DB MMDDCCYY — "Date Expressed in Format MMDDCCYY"
+    DB: { kind: "date", start: ["MM", "DD", "CCYY"] },
+    // DT CCYYMMDDHHMM — "Date and Time Expressed in Format CCYYMMDDHHMM"
+    DT: { kind: "dateTime", start: ["CCYY", "MM", "DD", "HH", "MI"] },
+    // RTS CCYYMMDDHHMMSS — "Date and Time Expressed in Format CCYYMMDDHHMMSS" (one date-time despite the R)
+    RTS: { kind: "dateTime", start: ["CCYY", "MM", "DD", "HH", "MI", "SS"] },
+    // TM HHMM — "Time Expressed in Format HHMM"
+    TM: { kind: "time", start: ["HH", "MI"] },
+    // TS HHMMSS — "Time Expressed in Format HHMMSS"
+    TS: { kind: "time", start: ["HH", "MI", "SS"] },
+    // RD8 CCYYMMDD-CCYYMMDD — "Range of Dates Expressed in Format CCYYMMDD-CCYYMMDD"
+    RD8: {
+        kind: "dateRange",
+        start: ["CCYY", "MM", "DD"],
+        end: ["CCYY", "MM", "DD"],
+    },
+    // RD MMDDCCYY-MMDDCCYY — "Range of Dates Expressed in Format MMDDCCYY-MMDDCCYY"
+    RD: {
+        kind: "dateRange",
+        start: ["MM", "DD", "CCYY"],
+        end: ["MM", "DD", "CCYY"],
+    },
+    // RDT CCYYMMDDHHMM-CCYYMMDDHHMM — "Range of Date and Time, Expressed in Format CCYYMMDDHHMM-CCYYMMDDHHMM"
+    RDT: {
+        kind: "dateTimeRange",
+        start: ["CCYY", "MM", "DD", "HH", "MI"],
+        end: ["CCYY", "MM", "DD", "HH", "MI"],
+    },
+    // DTS CCYYMMDDHHMMSS-CCYYMMDDHHMMSS — "Range of Date and Time Expressed in Format CCYYMMDDHHMMSS-CCYYMMDDHHMMSS" (a range despite having no R)
+    DTS: {
+        kind: "dateTimeRange",
+        start: ["CCYY", "MM", "DD", "HH", "MI", "SS"],
+        end: ["CCYY", "MM", "DD", "HH", "MI", "SS"],
+    },
+};
+/**
+ * X12 1250 code → the anchored, flagless grammar of its value. A range's halves are joined by
+ * exactly one hyphen, the one X12 transmits.
+ */
+export const X12_DATE_TIME_PERIOD_GRAMMAR = grammarsOf(X12_DATE_TIME_PERIOD_LAYOUT, "-");
+/**
+ * X12 data element 337 (Time), the time element of `AT7`, `G62` and `DTM-03`: "Time expressed in
+ * 24-hour clock time as follows: HHMM, or HHMMSS, or HHMMSSD, or HHMMSSDD, where H = hours
+ * (00-23), M = minutes (00-59), S = integer seconds (00-59) and DD = decimal seconds; decimal
+ * seconds are expressed as follows: D = tenths (0-9) and DD = hundredths (00-99)", length 4 to 8
+ * (release 005010, https://www.stedi.com/edi/x12-005010/element/337).
+ *
+ * Mask → its parts, keyed by the element's own four masks in the order the definition gives
+ * them. Not a 1250 table: the element has no format qualifier, its four- and six-digit forms
+ * coincide with `TM` and `TS`, and no 1250 code holds decimal seconds. Typed from the public
+ * union, so a missing form fails typecheck.
+ */
+export const X12_TIME_ELEMENT_LAYOUT = {
+    // HHMM — "H = hours (00-23), M = minutes (00-59)"
+    HHMM: { kind: "time", start: ["HH", "MI"] },
+    // HHMMSS — "S = integer seconds (00-59)"
+    HHMMSS: { kind: "time", start: ["HH", "MI", "SS"] },
+    // HHMMSSD — "D = tenths (0-9)"
+    HHMMSSD: { kind: "time", start: ["HH", "MI", "SS", "SD"] },
+    // HHMMSSDD — "DD = hundredths (00-99)"
+    HHMMSSDD: { kind: "time", start: ["HH", "MI", "SS", "SDD"] },
+};
+/**
+ * The four forms of X12 data element 337, shortest first: the layout table's own keys, so the
+ * list cannot name a form the table lacks.
+ */
+export const X12_TIME_ELEMENT_FORMS = Object.keys(X12_TIME_ELEMENT_LAYOUT);
+/**
+ * Element 337 form → the anchored, flagless grammar of its value. The four masks have four
+ * lengths (4, 6, 7 and 8 digits), so a value fits one form or none, and the reader needs no
+ * qualifier to tell them apart.
+ */
+export const X12_TIME_ELEMENT_GRAMMAR = grammarsOf(X12_TIME_ELEMENT_LAYOUT, "");
+/**
+ * The milliseconds one unit of each decimal-seconds part is worth: a tenth of a second is 100
+ * and a hundredth is 10. The reader multiplies by it and the writer divides by it, so the two
+ * agree on what `D` and `DD` mean.
+ */
+export const MILLISECONDS_PER_DECIMAL_SECOND = { SD: 100, SDD: 10 };
+/**
+ * Look a form of X12 data element 337 up by its mask, for the writer
+ * (`writeX12TimeElement`), whose caller names the form. The reader (`readX12Time`) is given no
+ * form: it tries the grammar of each form in the same table.
+ *
+ * - Matching is exact and by own key, so `"__proto__"`, `" HHMM"` and `"hhmm"` are not forms.
+ * - Null for a data element 1250 code (`TM`, `TS`): a qualifier is not a mask.
+ * - Null for a non-string argument.
+ *
+ * @param form the element's mask: `HHMM`, `HHMMSS`, `HHMMSSD` or `HHMMSSDD`
+ * @returns the form's parts in mask order, as a single time, or null
+ *
+ * @example x12TimeElementLayoutOf("HHMMSSDD") // { kind: "time", start: ["HH", "MI", "SS", "SDD"] }
+ * @example x12TimeElementLayoutOf("TS") // null (a 1250 code, not a mask)
+ * @example x12TimeElementLayoutOf("__proto__") // null
+ */
+export function x12TimeElementLayoutOf(form) {
+    return typeof form === "string" &&
+        Object.hasOwn(X12_TIME_ELEMENT_LAYOUT, form)
+        ? X12_TIME_ELEMENT_LAYOUT[form]
+        : null;
+}
+/**
+ * The 56 X12 623 codes, release 008010, in dictionary order: `01`–`12` (UTC+1 … UTC+12), `13`–`24`
+ * (UTC−12 … UTC−1, descending), `25`–`29` (the half-hour offsets, added in release 006010), then
+ * the 27 letter codes. Release 005010 has the 51 codes other than `25`–`29`. Membership is by
+ * this list, never by shape. `TS`, `TT`, `CD` and `MD` are also codes of data element 1250, with
+ * unrelated meanings there.
+ */
+export const X12_TIME_CODES = [
+    // fallow-ignore-next-line code-duplication -- the 56 DE 623 codes as a runtime list; `X12TimeCode` in types/edi.ts is the same enumeration in type position
+    "01",
+    "02",
+    "03",
+    "04",
+    "05",
+    "06",
+    "07",
+    "08",
+    "09",
+    "10",
+    "11",
+    "12",
+    "13",
+    "14",
+    "15",
+    "16",
+    "17",
+    "18",
+    "19",
+    "20",
+    "21",
+    "22",
+    "23",
+    "24",
+    "25",
+    "26",
+    "27",
+    "28",
+    "29",
+    "AD",
+    "AS",
+    "AT",
+    "CD",
+    "CS",
+    "CT",
+    "ED",
+    "ES",
+    "ET",
+    "GM",
+    "HD",
+    "HS",
+    "HT",
+    "LT",
+    "MD",
+    "MS",
+    "MT",
+    "ND",
+    "NS",
+    "NT",
+    "PD",
+    "PS",
+    "PT",
+    "TD",
+    "TS",
+    "TT",
+    "UT",
+];
+const EDI_CODE_TABLES = {
+    edifact: {
+        layouts: EDIFACT_DTM_LAYOUT,
+        grammars: EDIFACT_DTM_GRAMMAR,
+        // UNTDID 2379, every directory read (twelve, from D.93A to D.22B): a period is given
+        // "without hyphen".
+        rangeSeparator: "",
+    },
+    x12: {
+        layouts: X12_DATE_TIME_PERIOD_LAYOUT,
+        grammars: X12_DATE_TIME_PERIOD_GRAMMAR,
+        // X12 1250: each range definition gives the format with its hyphen.
+        rangeSeparator: "-",
+    },
+};
+/**
+ * Look a format code up in its standard's tables: the one lookup the classifier, the reader and
+ * the writer share.
+ *
+ * - Matching is exact and by own key, so `"__proto__"`, `" 102"` and `"d8"` are not codes.
+ * - Null for a code that is not read (`101`, `209`, `D6`, `UN`), like an unknown code.
+ * - Null for a standard that is not `"edifact"` or `"x12"`, and for a non-string argument.
+ *
+ * @param standard which element the code belongs to
+ * @param code the 2379 or 1250 format code
+ * @returns the code's kind, layout, grammar and range separator, or null
+ *
+ * @example ediCodeOf("edifact", "718") // { kind: "datePeriod", valueKind: "date", layout: { kind: "datePeriod", start: ["CCYY", "MM", "DD"], end: [...] }, grammar: /^…$/, rangeSeparator: "" }
+ * @example ediCodeOf("x12", "RD8") // { kind: "dateRange", valueKind: "date", layout: {...}, grammar: /^…$/, rangeSeparator: "-" }
+ * @example ediCodeOf("edifact", "101") // null (a two-digit year: not read)
+ * @example ediCodeOf("edifact", "D8") // null (an X12 code)
+ */
+export function ediCodeOf(standard, code) {
+    if (typeof standard !== "string" || typeof code !== "string") {
+        return null;
+    }
+    if (!Object.hasOwn(EDI_CODE_TABLES, standard)) {
+        return null;
+    }
+    const table = EDI_CODE_TABLES[standard];
+    if (!Object.hasOwn(table.layouts, code)) {
+        return null;
+    }
+    const layout = table.layouts[code];
+    const grammar = table.grammars[code];
+    return {
+        kind: layout.kind,
+        valueKind: VALUE_KIND[layout.kind],
+        layout,
+        grammar,
+        rangeSeparator: table.rangeSeparator,
+    };
+}
+/**
+ * Look a format code up as a code of one kind: null unless the code is in its standard's tables
+ * under exactly that kind. Each public function names its own kind here, so a code of another
+ * kind (`203` given to a date function) is refused before any value is read.
+ *
+ * @param standard which element the code belongs to
+ * @param kind the kind of value the calling function reads or writes
+ * @param code the 2379 or 1250 format code
+ * @returns the code's entry, or null when the code is not one of that kind
+ *
+ * @example ediCodeOfKind("edifact", "date", "102") // { kind: "date", … }
+ * @example ediCodeOfKind("edifact", "date", "203") // null (a date-time code)
+ * @example ediCodeOfKind("x12", "dateRange", "RD8") // { kind: "dateRange", … }
+ */
+export function ediCodeOfKind(standard, kind, code) {
+    const entry = ediCodeOf(standard, code);
+    return entry !== null && entry.kind === kind ? entry : null;
+}

package/dist/internal/englishCalendarNames.d.ts

@@ -5,7 +5,9 @@ export declare const ENGLISH_MONTH_NAMES: readonly ["Jan", "Feb", "Mar", "Apr",
  * The `Mon, 15 Jul 2024 12:00:00` stem RFC 5322 date-time and RFC 9110 IMF-fixdate share: English
  * day and month names, zero-padded fields, read from the date-time's own wall clock.
  *
- * @param zdt the date-time; the caller has already rejected a year outside 0-9999
+ * @param zdt the date-time; the caller has already rejected a year its grammar cannot hold: a
+ *   negative one for RFC 5322 (`year = 4*DIGIT`, so five digits are written in full), and any
+ *   outside 0000–9999 for RFC 9110 (`year = 4DIGIT`)
  * @returns the stem, without a zone or `GMT` suffix
  * @example englishDateTimeStem(Temporal.ZonedDateTime.from("2024-07-15T12:00:05+00:00[UTC]")) // "Mon, 15 Jul 2024 12:00:05"
  * @example englishDateTimeStem(Temporal.ZonedDateTime.from("0099-01-03T04:05:06+00:00[UTC]")) // "Sat, 03 Jan 0099 04:05:06"

package/dist/internal/englishCalendarNames.js

@@ -2,8 +2,7 @@
 // RFC 7231) mandate English weekday/month
 // abbreviations regardless of the caller's locale — these are fixed,
 // non-locale-adaptive grammars, not a display format, so hardcoding the
-// English names here is not the i18n bug it would be in a formatter (see
-// roadmap Decision 1 / J13's "Why this survives Decision 1").
+// English names here is not the i18n bug it would be in a formatter.
 // Index 0 = Monday, aligned with Temporal's 1-7 `dayOfWeek` via `[dayOfWeek - 1]`.
 export const ENGLISH_WEEKDAY_NAMES = [
     "Mon",
@@ -33,7 +32,9 @@ export const ENGLISH_MONTH_NAMES = [
  * The `Mon, 15 Jul 2024 12:00:00` stem RFC 5322 date-time and RFC 9110 IMF-fixdate share: English
  * day and month names, zero-padded fields, read from the date-time's own wall clock.
  *
- * @param zdt the date-time; the caller has already rejected a year outside 0-9999
+ * @param zdt the date-time; the caller has already rejected a year its grammar cannot hold: a
+ *   negative one for RFC 5322 (`year = 4*DIGIT`, so five digits are written in full), and any
+ *   outside 0000–9999 for RFC 9110 (`year = 4DIGIT`)
  * @returns the stem, without a zone or `GMT` suffix
  * @example englishDateTimeStem(Temporal.ZonedDateTime.from("2024-07-15T12:00:05+00:00[UTC]")) // "Mon, 15 Jul 2024 12:00:05"
  * @example englishDateTimeStem(Temporal.ZonedDateTime.from("0099-01-03T04:05:06+00:00[UTC]")) // "Sat, 03 Jan 0099 04:05:06"

package/dist/internal/epochNanoseconds.d.ts

@@ -8,6 +8,8 @@ export declare const MIN_EPOCH_NANOSECONDS = -8640000000000000000000n;
  * +10^8 days from the Unix epoch, i.e. `+275760-09-13T00:00:00Z`.
  */
 export declare const MAX_EPOCH_NANOSECONDS = 8640000000000000000000n;
+/** TC39 `CheckISODaysRange`: a date may sit at most 10^8 days from the Unix epoch. */
+export declare const MAX_ISO_EPOCH_DAYS = 100000000;
 /**
  * Digits in `MAX_EPOCH_NANOSECONDS` (22) — the longest a decimal form of an in-range
  * epoch-nanosecond value can be, sign excluded.

package/dist/internal/epochNanoseconds.js

@@ -8,6 +8,8 @@ export const MIN_EPOCH_NANOSECONDS = -8640000000000000000000n;
  * +10^8 days from the Unix epoch, i.e. `+275760-09-13T00:00:00Z`.
  */
 export const MAX_EPOCH_NANOSECONDS = 8640000000000000000000n;
+/** TC39 `CheckISODaysRange`: a date may sit at most 10^8 days from the Unix epoch. */
+export const MAX_ISO_EPOCH_DAYS = 100_000_000;
 /**
  * Digits in `MAX_EPOCH_NANOSECONDS` (22) — the longest a decimal form of an in-range
  * epoch-nanosecond value can be, sign excluded.

package/dist/internal/exactDuration.d.ts

@@ -0,0 +1,37 @@
+/**
+ * An ISO 8601 duration as exact elapsed nanoseconds, signed, or `null` when it is not one.
+ *
+ * The transport rule for a span of exact time (`transitTime`, `classifyPunctuality`,
+ * `nextDeparture`, …):
+ *
+ * - Hours, minutes, seconds and fractions are elapsed time, and a day is 24 hours exactly. That
+ *   is how TC39 Temporal's `Duration.prototype.round` and `total` read a day when no
+ *   `relativeTo` is given.
+ * - Years, months and weeks return `null`: `round` and `total` require a `relativeTo` for them,
+ *   so they have no exact length on their own. A zero calendar component (`P0Y1D`) changes
+ *   nothing. (`Temporal.Instant#add` accepts no date unit at all, days included; callers add the
+ *   nanoseconds this returns instead.)
+ * - The result keeps the duration's sign, so a caller that needs a non-negative amount checks
+ *   `< 0n` itself. `-PT0S` is `0n`.
+ * - Summed in bigint, so it stays exact past 2^53 ns and across the whole instant range.
+ *
+ * @param value candidate ISO 8601 duration string
+ * @returns the duration in nanoseconds, negative for a negative duration, or null on invalid input
+ *
+ * @example exactDurationNanoseconds("PT1H") // 3600000000000n
+ * @example exactDurationNanoseconds("-PT5M") // -300000000000n
+ * @example exactDurationNanoseconds("P1D") // 86400000000000n
+ * @example exactDurationNanoseconds("P1W") // null
+ */
+export declare function exactDurationNanoseconds(value: unknown): bigint | null;
+/**
+ * `exactDurationNanoseconds` for an amount that may not be negative — a tolerance, a minimum
+ * connection — or `null`. Zero is allowed, and `-PT0S` is zero.
+ *
+ * @param value candidate ISO 8601 duration string
+ * @returns the duration in nanoseconds, zero or more, or null on invalid input or a negative duration
+ *
+ * @example nonNegativeExactDurationNanoseconds("PT15M") // 900000000000n
+ * @example nonNegativeExactDurationNanoseconds("-PT15M") // null
+ */
+export declare function nonNegativeExactDurationNanoseconds(value: unknown): bigint | null;

package/dist/internal/exactDuration.js

@@ -0,0 +1,64 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { NANOSECONDS_PER_DAY, NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, } from "./foreignEpochs.js";
+const NANOSECONDS_PER_HOUR = 3600000000000n;
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+/**
+ * An ISO 8601 duration as exact elapsed nanoseconds, signed, or `null` when it is not one.
+ *
+ * The transport rule for a span of exact time (`transitTime`, `classifyPunctuality`,
+ * `nextDeparture`, …):
+ *
+ * - Hours, minutes, seconds and fractions are elapsed time, and a day is 24 hours exactly. That
+ *   is how TC39 Temporal's `Duration.prototype.round` and `total` read a day when no
+ *   `relativeTo` is given.
+ * - Years, months and weeks return `null`: `round` and `total` require a `relativeTo` for them,
+ *   so they have no exact length on their own. A zero calendar component (`P0Y1D`) changes
+ *   nothing. (`Temporal.Instant#add` accepts no date unit at all, days included; callers add the
+ *   nanoseconds this returns instead.)
+ * - The result keeps the duration's sign, so a caller that needs a non-negative amount checks
+ *   `< 0n` itself. `-PT0S` is `0n`.
+ * - Summed in bigint, so it stays exact past 2^53 ns and across the whole instant range.
+ *
+ * @param value candidate ISO 8601 duration string
+ * @returns the duration in nanoseconds, negative for a negative duration, or null on invalid input
+ *
+ * @example exactDurationNanoseconds("PT1H") // 3600000000000n
+ * @example exactDurationNanoseconds("-PT5M") // -300000000000n
+ * @example exactDurationNanoseconds("P1D") // 86400000000000n
+ * @example exactDurationNanoseconds("P1W") // null
+ */
+export function exactDurationNanoseconds(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    try {
+        const duration = Temporal.Duration.from(value);
+        if (duration.years !== 0 || duration.months !== 0 || duration.weeks !== 0) {
+            return null;
+        }
+        return (BigInt(duration.days) * NANOSECONDS_PER_DAY +
+            BigInt(duration.hours) * NANOSECONDS_PER_HOUR +
+            BigInt(duration.minutes) * NANOSECONDS_PER_MINUTE +
+            BigInt(duration.seconds) * NANOSECONDS_PER_SECOND +
+            BigInt(duration.milliseconds) * NANOSECONDS_PER_MILLISECOND +
+            BigInt(duration.microseconds) * NANOSECONDS_PER_MICROSECOND +
+            BigInt(duration.nanoseconds));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `exactDurationNanoseconds` for an amount that may not be negative — a tolerance, a minimum
+ * connection — or `null`. Zero is allowed, and `-PT0S` is zero.
+ *
+ * @param value candidate ISO 8601 duration string
+ * @returns the duration in nanoseconds, zero or more, or null on invalid input or a negative duration
+ *
+ * @example nonNegativeExactDurationNanoseconds("PT15M") // 900000000000n
+ * @example nonNegativeExactDurationNanoseconds("-PT15M") // null
+ */
+export function nonNegativeExactDurationNanoseconds(value) {
+    const nanoseconds = exactDurationNanoseconds(value);
+    return nanoseconds === null || nanoseconds < 0n ? null : nanoseconds;
+}

package/dist/internal/exactMoment.d.ts

@@ -0,0 +1,72 @@
+/**
+ * How an exact moment was written, so a result can be written the same way: in a named zone
+ * (the bracket), at a UTC offset (its text exactly as written), or as a `Z` instant.
+ */
+export type MomentNotation = {
+    kind: "zone";
+    timeZone: string;
+} | {
+    kind: "offset";
+    offset: string;
+} | {
+    kind: "utc";
+};
+/** An exact moment: its epoch nanoseconds and how it was written. */
+export type ExactMoment = {
+    nanoseconds: bigint;
+    notation: MomentNotation;
+};
+/**
+ * Read an exact moment the way `transitTime` reads a departure, or `null`.
+ *
+ * - A zoned string (`…-04:00[America/New_York]`) is read through its bracket, which must name a
+ *   real zone that agrees with the offset, as `isValidZonedDateTime` requires. An offset written
+ *   to the minute agrees when it is the zone's sub-minute offset rounded (TC39
+ *   `ToTemporalZonedDateTime`, match-minutes), which is how `writeExactMoment` writes one.
+ * - A wall time with a bracket and no offset is read in that zone with the `"compatible"`
+ *   disambiguation policy (`context/reference/LOCAL_TIME_RESOLUTION.md`): an **ambiguous** wall
+ *   time, a fall-back hour the clock ran through twice, resolves to the **earlier** instant
+ *   (`2024-11-03T01:30:00[America/New_York]` is `01:30-04:00`), and a **nonexistent** one, a
+ *   spring-forward hour the clock skipped, to the **later** instant
+ *   (`2024-03-10T02:30:00[America/New_York]` is `03:30-04:00`). A caller that must not guess
+ *   refuses the offset-less form before calling, as `nextDeparture` does.
+ * - A string that names a zone the zoned read rejects is `null`; it never falls back to its
+ *   offset. That includes a zoned string whose local date is −271821-04-19, which
+ *   `Temporal.ZonedDateTime.from` refuses although its instant is in range.
+ * - Otherwise an instant (`Z` or an offset) as `parseInstantNanoseconds` reads it: calendar and
+ *   elective annotations are ignored and a critical unknown one is rejected. Its offset text is
+ *   kept exactly as written, sub-minute and `,` fractions included.
+ *
+ * @param value candidate zoned datetime or instant string
+ * @returns the moment's epoch nanoseconds and notation, or null on invalid input
+ *
+ * @example readExactMoment("2024-06-15T10:00:00+09:00") // { nanoseconds: 1718413200000000000n, notation: { kind: "offset", offset: "+09:00" } }
+ * @example readExactMoment("2024-06-15T10:00:00Z[Not/AZone]") // null
+ * @example readExactMoment("2024-03-10T02:30:00[America/New_York]") // { nanoseconds: 1710055800000000000n, notation: { kind: "zone", timeZone: "America/New_York" } } (nonexistent: the later instant, 03:30-04:00)
+ */
+export declare function readExactMoment(value: unknown): ExactMoment | null;
+/**
+ * Write epoch nanoseconds the way a moment was written: in its zone, at its offset text, or as a
+ * `Z` instant. `""` when the nanoseconds leave the instant range (±8.64e21 ns).
+ *
+ * - A zone notation is written as Temporal writes a `ZonedDateTime`: the offset in force at that
+ *   instant, rounded to the minute (`-00:45` for Monrovia's −00:44:30), then the bracket.
+ *   `readExactMoment` and `parseInstantNanoseconds` read that string back as the same instant,
+ *   with two exceptions, both Temporal's own. A wall time repeated inside a sub-minute offset
+ *   change reads as its first pass, in both readers (`parseInstantNanoseconds` states the
+ *   rule). And `readExactMoment`, a zoned read, refuses a string whose local date is
+ *   −271821-04-19 (`CheckISODaysRange` in `Temporal.ZonedDateTime.from`): the string written
+ *   for the first hours of the instant range in a zone west of Greenwich reads as `null` there,
+ *   and as its instant in `parseInstantNanoseconds`
+ *   (`context/domination/js-temporal-polyfill-bugs.md` § J).
+ * - An offset notation keeps its text as written. The wall clock is shifted, never the instant
+ *   (`wallClockAtOffset`), so the last hours of the range still write at a positive offset.
+ *
+ * @param nanoseconds epoch nanoseconds of the moment to write
+ * @param notation how to write it, from `readExactMoment`
+ * @returns the moment as a zoned, offset or `Z` string, or "" when it is out of range
+ *
+ * @example writeExactMoment(0n, { kind: "offset", offset: "+09:00" }) // "1970-01-01T09:00:00+09:00"
+ * @example writeExactMoment(0n, { kind: "zone", timeZone: "UTC" }) // "1970-01-01T00:00:00+00:00[UTC]"
+ */
+export declare function writeExactMoment(nanoseconds: bigint, notation: MomentNotation): string;