@northguild/gmt 1.15.0 → 1.16.0

package/dist/internal/resolveLocale.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A locale argument: one BCP 47 tag, or a preference list of tags (ECMA-402 `locales`).
+ */
+export type LocalesArgument = string | string[];
+/**
+ * Resolve a `locale` argument to the single BCP 47 tag a locale-aware function reads.
+ *
+ * - Follows ECMA-402 CanonicalizeLocaleList: a string is a one-tag list, every tag is
+ *   canonicalized (`"EN-us"` → `"en-US"`) and duplicates are dropped.
+ * - The first tag with available locale data wins (`Intl.DateTimeFormat.supportedLocalesOf`), as
+ *   ECMA-402's locale negotiation picks; a list with no available tag keeps its first tag, exactly
+ *   as that tag passed alone would be read.
+ * - `undefined` and an empty list resolve to the default locale.
+ * - A malformed tag anywhere in the list, a non-string element, or any other type is invalid and
+ *   resolves to `null`, which callers map to their sentinel (ECMA-402 throws a RangeError/TypeError).
+ *
+ * @param locales raw locale argument from caller input
+ * @returns the resolved BCP 47 tag, or `null` when the argument is invalid
+ */
+export declare function resolveLocale(locales: unknown): string | null;
+/**
+ * Resolve the `locale` argument of a function whose locale is required, to the single BCP 47 tag
+ * it reads, or `null` (the caller's sentinel).
+ *
+ * - An omitted locale (`undefined`) and an empty list both name no locale, so both are `null`.
+ *   ECMA-402 would resolve an empty list to the host default locale; a required locale exists to
+ *   keep the result independent of the host, so GMT treats `[]` as omitted (house rule).
+ * - Anything else resolves as `resolveLocale` does.
+ *
+ * @param locales raw locale argument from caller input
+ * @returns the resolved BCP 47 tag, or `null` when the argument is omitted, empty or invalid
+ *
+ * @example resolveRequiredLocale("EN-us") // "en-US"
+ * @example resolveRequiredLocale(undefined) // null
+ * @example resolveRequiredLocale([]) // null
+ */
+export declare function resolveRequiredLocale(locales: unknown): string | null;

package/dist/internal/resolveLocale.js

@@ -0,0 +1,59 @@
+/**
+ * Resolve a `locale` argument to the single BCP 47 tag a locale-aware function reads.
+ *
+ * - Follows ECMA-402 CanonicalizeLocaleList: a string is a one-tag list, every tag is
+ *   canonicalized (`"EN-us"` → `"en-US"`) and duplicates are dropped.
+ * - The first tag with available locale data wins (`Intl.DateTimeFormat.supportedLocalesOf`), as
+ *   ECMA-402's locale negotiation picks; a list with no available tag keeps its first tag, exactly
+ *   as that tag passed alone would be read.
+ * - `undefined` and an empty list resolve to the default locale.
+ * - A malformed tag anywhere in the list, a non-string element, or any other type is invalid and
+ *   resolves to `null`, which callers map to their sentinel (ECMA-402 throws a RangeError/TypeError).
+ *
+ * @param locales raw locale argument from caller input
+ * @returns the resolved BCP 47 tag, or `null` when the argument is invalid
+ */
+export function resolveLocale(locales) {
+    if (locales !== undefined &&
+        typeof locales !== "string" &&
+        !Array.isArray(locales)) {
+        return null;
+    }
+    try {
+        const canonical = Intl.getCanonicalLocales(locales);
+        if (canonical.length === 0) {
+            return new Intl.DateTimeFormat().resolvedOptions().locale;
+        }
+        if (canonical.length === 1)
+            return canonical[0] ?? null;
+        return (Intl.DateTimeFormat.supportedLocalesOf(canonical)[0] ??
+            canonical[0] ??
+            null);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the `locale` argument of a function whose locale is required, to the single BCP 47 tag
+ * it reads, or `null` (the caller's sentinel).
+ *
+ * - An omitted locale (`undefined`) and an empty list both name no locale, so both are `null`.
+ *   ECMA-402 would resolve an empty list to the host default locale; a required locale exists to
+ *   keep the result independent of the host, so GMT treats `[]` as omitted (house rule).
+ * - Anything else resolves as `resolveLocale` does.
+ *
+ * @param locales raw locale argument from caller input
+ * @returns the resolved BCP 47 tag, or `null` when the argument is omitted, empty or invalid
+ *
+ * @example resolveRequiredLocale("EN-us") // "en-US"
+ * @example resolveRequiredLocale(undefined) // null
+ * @example resolveRequiredLocale([]) // null
+ */
+export function resolveRequiredLocale(locales) {
+    if (locales === undefined)
+        return null;
+    if (Array.isArray(locales) && locales.length === 0)
+        return null;
+    return resolveLocale(locales);
+}

package/dist/internal/resolveManualRoundingOptions.d.ts

@@ -0,0 +1,23 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Read `roundingIncrement` and `roundingMode` the way Temporal does, for a rounding GMT computes
+ * itself (a date unit that Temporal's own `round()` does not accept).
+ *
+ * - `roundingIncrement` follows GetRoundingIncrementOption: `undefined` is 1; any other value is
+ *   truncated towards zero (ToIntegerWithTruncation), and a non-finite value or one below 1 after
+ *   truncation is rejected.
+ * - `roundingMode` follows GetRoundingModeOption: `undefined` is `"halfExpand"`; a value outside the
+ *   nine modes is rejected.
+ *
+ * @param roundingIncrement caller-supplied increment
+ * @param roundingMode caller-supplied rounding mode
+ * @returns the resolved increment and mode, or null when Temporal would throw a RangeError
+ *
+ * @example resolveManualRoundingOptions(1.5, undefined) // { increment: 1, mode: "halfExpand" }
+ * @example resolveManualRoundingOptions(0.9, "floor") // null
+ * @example resolveManualRoundingOptions(2, "bogus" as never) // null
+ */
+export declare function resolveManualRoundingOptions(roundingIncrement: number | undefined, roundingMode: Temporal.RoundingMode | undefined): {
+    increment: number;
+    mode: Temporal.RoundingMode;
+} | null;

package/dist/internal/resolveManualRoundingOptions.js

@@ -0,0 +1,39 @@
+/** The nine rounding modes of Temporal's GetRoundingModeOption (Temporal §14.5.2.2). */
+const ROUNDING_MODES = [
+    "ceil",
+    "floor",
+    "expand",
+    "trunc",
+    "halfCeil",
+    "halfFloor",
+    "halfExpand",
+    "halfTrunc",
+    "halfEven",
+];
+/**
+ * Read `roundingIncrement` and `roundingMode` the way Temporal does, for a rounding GMT computes
+ * itself (a date unit that Temporal's own `round()` does not accept).
+ *
+ * - `roundingIncrement` follows GetRoundingIncrementOption: `undefined` is 1; any other value is
+ *   truncated towards zero (ToIntegerWithTruncation), and a non-finite value or one below 1 after
+ *   truncation is rejected.
+ * - `roundingMode` follows GetRoundingModeOption: `undefined` is `"halfExpand"`; a value outside the
+ *   nine modes is rejected.
+ *
+ * @param roundingIncrement caller-supplied increment
+ * @param roundingMode caller-supplied rounding mode
+ * @returns the resolved increment and mode, or null when Temporal would throw a RangeError
+ *
+ * @example resolveManualRoundingOptions(1.5, undefined) // { increment: 1, mode: "halfExpand" }
+ * @example resolveManualRoundingOptions(0.9, "floor") // null
+ * @example resolveManualRoundingOptions(2, "bogus" as never) // null
+ */
+export function resolveManualRoundingOptions(roundingIncrement, roundingMode) {
+    const increment = roundingIncrement === undefined ? 1 : Math.trunc(roundingIncrement);
+    if (!Number.isFinite(increment) || increment < 1)
+        return null;
+    if (roundingMode !== undefined && !ROUNDING_MODES.includes(roundingMode)) {
+        return null;
+    }
+    return { increment, mode: roundingMode ?? "halfExpand" };
+}

package/dist/internal/resolveMinimalDaysInFirstWeek.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve the minimal-days-in-first-week rule for the locale week-year functions.
+ *
+ * - ECMA-402 does not expose a locale's `minimalDays`: `Intl.Locale.prototype.getWeekInfo` returns
+ *   only `firstDay` and `weekend` (Intl Locale Info, WeekInfoOfLocale; the field was dropped in
+ *   tc39/proposal-intl-locale-info#86). So the value comes from the caller, never the runtime.
+ * - Omitted, it is the ISO 8601 value `4` on every runtime, so one input has one answer.
+ * - Returns `null` for a value that is not an integer from 1 to 7 — the width of a week.
+ *
+ * @param options optional: minimalDays (integer 1–7)
+ * @returns the minimal days to use, or null when `minimalDays` is out of range
+ *
+ * @example resolveMinimalDaysInFirstWeek() // 4
+ * @example resolveMinimalDaysInFirstWeek({ minimalDays: 1 }) // 1
+ * @example resolveMinimalDaysInFirstWeek({ minimalDays: 0 }) // null
+ */
+export declare function resolveMinimalDaysInFirstWeek(options?: {
+    minimalDays?: number;
+}): number | null;

package/dist/internal/resolveMinimalDaysInFirstWeek.js

@@ -0,0 +1,28 @@
+/**
+ * The ISO 8601 minimal-days value: week 1 is the first week with at least 4 days in January.
+ */
+const ISO_MINIMAL_DAYS_IN_FIRST_WEEK = 4;
+/**
+ * Resolve the minimal-days-in-first-week rule for the locale week-year functions.
+ *
+ * - ECMA-402 does not expose a locale's `minimalDays`: `Intl.Locale.prototype.getWeekInfo` returns
+ *   only `firstDay` and `weekend` (Intl Locale Info, WeekInfoOfLocale; the field was dropped in
+ *   tc39/proposal-intl-locale-info#86). So the value comes from the caller, never the runtime.
+ * - Omitted, it is the ISO 8601 value `4` on every runtime, so one input has one answer.
+ * - Returns `null` for a value that is not an integer from 1 to 7 — the width of a week.
+ *
+ * @param options optional: minimalDays (integer 1–7)
+ * @returns the minimal days to use, or null when `minimalDays` is out of range
+ *
+ * @example resolveMinimalDaysInFirstWeek() // 4
+ * @example resolveMinimalDaysInFirstWeek({ minimalDays: 1 }) // 1
+ * @example resolveMinimalDaysInFirstWeek({ minimalDays: 0 }) // null
+ */
+export function resolveMinimalDaysInFirstWeek(options) {
+    const minimalDays = options?.minimalDays;
+    if (minimalDays === undefined)
+        return ISO_MINIMAL_DAYS_IN_FIRST_WEEK;
+    return Number.isInteger(minimalDays) && minimalDays >= 1 && minimalDays <= 7
+        ? minimalDays
+        : null;
+}

package/dist/internal/resolveOverflow.d.ts

@@ -2,6 +2,12 @@ import type { Overflow } from "../types/index.js";
 /**
  * Resolve an optional overflow value to its default ("constrain") when unset.
  *
+ * - Only an *omitted* member takes the default. Temporal's GetOption reads any other value,
+ *   `null` included, through ToString, so `{ overflow: null }` is the string "null" and a
+ *   RangeError — never "constrain" (Chromium 153: "Value null out of range for
+ *   Temporal.PlainDate.prototype.add options property overflow"). Passing it through is what
+ *   lets the caller's `catch` return its sentinel.
+ *
  * @param overflow optional overflow value
  * @example resolveOverflow(undefined) // "constrain"
  * @example resolveOverflow("reject") // "reject"

package/dist/internal/resolveOverflow.js

@@ -1,11 +1,17 @@
 /**
  * Resolve an optional overflow value to its default ("constrain") when unset.
  *
+ * - Only an *omitted* member takes the default. Temporal's GetOption reads any other value,
+ *   `null` included, through ToString, so `{ overflow: null }` is the string "null" and a
+ *   RangeError — never "constrain" (Chromium 153: "Value null out of range for
+ *   Temporal.PlainDate.prototype.add options property overflow"). Passing it through is what
+ *   lets the caller's `catch` return its sentinel.
+ *
  * @param overflow optional overflow value
  * @example resolveOverflow(undefined) // "constrain"
  * @example resolveOverflow("reject") // "reject"
  * @returns the resolved overflow value
  */
 export function resolveOverflow(overflow) {
-    return overflow ?? "constrain";
+    return overflow === undefined ? "constrain" : overflow;
 }

package/dist/internal/resolveReadingTimeZone.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve the `timeZone` option a UTC reader uses to read a value's wall-clock fields.
+ *
+ * - `undefined` (the option omitted) resolves to `"UTC"`.
+ * - A valid IANA zone (or `"UTC"`) resolves to itself.
+ * - Any other value is invalid and resolves to `null`, which callers map to their sentinel.
+ *
+ * @param timeZone raw option value from caller input
+ * @returns the zone to read in, or `null` when the value is invalid
+ */
+export declare function resolveReadingTimeZone(timeZone: unknown): string | null;

package/dist/internal/resolveReadingTimeZone.js

@@ -0,0 +1,18 @@
+import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
+/**
+ * Resolve the `timeZone` option a UTC reader uses to read a value's wall-clock fields.
+ *
+ * - `undefined` (the option omitted) resolves to `"UTC"`.
+ * - A valid IANA zone (or `"UTC"`) resolves to itself.
+ * - Any other value is invalid and resolves to `null`, which callers map to their sentinel.
+ *
+ * @param timeZone raw option value from caller input
+ * @returns the zone to read in, or `null` when the value is invalid
+ */
+export function resolveReadingTimeZone(timeZone) {
+    if (timeZone === undefined || timeZone === "UTC")
+        return "UTC";
+    return typeof timeZone === "string" && isValidTimeZone(timeZone)
+        ? timeZone
+        : null;
+}

package/dist/internal/resolveUnixIntervalPair.d.ts

@@ -0,0 +1,30 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import { type UnixEpochUnit } from "./unixEpochValue.js";
+export interface ResolvedUnixInterval {
+    startVal: Temporal.ZonedDateTime;
+    endVal: Temporal.ZonedDateTime;
+    resolvedUnit: Temporal.DateTimeUnit;
+    epochUnit: UnixEpochUnit;
+}
+/**
+ * Resolve the shared arguments of `intervalLengthUnix`, `intervalCountUnix` and
+ * `splitIntervalByUnitUnix`: a non-reversed epoch pair in `epochUnit`, a singular-or-plural
+ * `DateTimeUnit`, and the zone both ends are read in.
+ *
+ * - Epochs follow the one `unix/` grammar (`parseUnixEpochValue`) and must name Temporal instants.
+ * - `epochUnit` defaults to `"milliseconds"`; `timeZone` defaults to `"UTC"` (`"local"` is the
+ *   system zone, an unknown zone is invalid).
+ *
+ * @param start interval start epoch
+ * @param end interval end epoch
+ * @param unit unit name, singular or plural
+ * @param options optional `{ epochUnit, timeZone }`
+ * @returns the zoned ends, singular unit and epoch unit, or null on invalid input
+ *
+ * @example resolveUnixIntervalPair(0, 86400, "days", { epochUnit: "seconds" })?.resolvedUnit // "day"
+ * @example resolveUnixIntervalPair(10, 0, "day") // null (reversed)
+ */
+export declare function resolveUnixIntervalPair(start: unknown, end: unknown, unit: unknown, options?: {
+    epochUnit?: unknown;
+    timeZone?: unknown;
+}): ResolvedUnixInterval | null;

package/dist/internal/resolveUnixIntervalPair.js

@@ -0,0 +1,53 @@
+import { normalizeTimeZone } from "./normalizeTimeZone.js";
+import { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
+import { parseUnixEpochInterval, resolveUnixEpochUnit, unixEpochToInstant, } from "./unixEpochValue.js";
+import { isValidDateTimeUnit } from "../plain/validate/index.js";
+/**
+ * Resolve the shared arguments of `intervalLengthUnix`, `intervalCountUnix` and
+ * `splitIntervalByUnitUnix`: a non-reversed epoch pair in `epochUnit`, a singular-or-plural
+ * `DateTimeUnit`, and the zone both ends are read in.
+ *
+ * - Epochs follow the one `unix/` grammar (`parseUnixEpochValue`) and must name Temporal instants.
+ * - `epochUnit` defaults to `"milliseconds"`; `timeZone` defaults to `"UTC"` (`"local"` is the
+ *   system zone, an unknown zone is invalid).
+ *
+ * @param start interval start epoch
+ * @param end interval end epoch
+ * @param unit unit name, singular or plural
+ * @param options optional `{ epochUnit, timeZone }`
+ * @returns the zoned ends, singular unit and epoch unit, or null on invalid input
+ *
+ * @example resolveUnixIntervalPair(0, 86400, "days", { epochUnit: "seconds" })?.resolvedUnit // "day"
+ * @example resolveUnixIntervalPair(10, 0, "day") // null (reversed)
+ */
+export function resolveUnixIntervalPair(start, end, unit, options) {
+    const interval = parseUnixEpochInterval(start, end);
+    const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+    const timeZone = normalizeTimeZone(options?.timeZone);
+    if (interval === null ||
+        epochUnit === null ||
+        !timeZone ||
+        typeof unit !== "string") {
+        return null;
+    }
+    const resolvedUnit = resolveDateTimeUnit(unit);
+    if (!isValidDateTimeUnit(resolvedUnit)) {
+        return null;
+    }
+    const startInstant = unixEpochToInstant(interval.start, epochUnit);
+    const endInstant = unixEpochToInstant(interval.end, epochUnit);
+    if (startInstant === null || endInstant === null) {
+        return null;
+    }
+    try {
+        return {
+            startVal: startInstant.toZonedDateTimeISO(timeZone),
+            endVal: endInstant.toZonedDateTimeISO(timeZone),
+            resolvedUnit,
+            epochUnit,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/resolveWeekStartsOn.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve a `weekStartsOn` option value.
+ *
+ * - `undefined` (the option omitted) resolves to `"monday"`, the ISO 8601 week start.
+ * - `"monday"` and `"sunday"` resolve to themselves.
+ * - Any other value is invalid and resolves to `null`, which callers map to their sentinel — as
+ *   Temporal's GetOption rejects a string outside the allowed list.
+ *
+ * @param weekStartsOn raw option value from caller input
+ * @returns `"monday"`, `"sunday"`, or `null` when the value is invalid
+ */
+export declare function resolveWeekStartsOn(weekStartsOn: unknown): "monday" | "sunday" | null;

package/dist/internal/resolveWeekStartsOn.js

@@ -0,0 +1,18 @@
+/**
+ * Resolve a `weekStartsOn` option value.
+ *
+ * - `undefined` (the option omitted) resolves to `"monday"`, the ISO 8601 week start.
+ * - `"monday"` and `"sunday"` resolve to themselves.
+ * - Any other value is invalid and resolves to `null`, which callers map to their sentinel — as
+ *   Temporal's GetOption rejects a string outside the allowed list.
+ *
+ * @param weekStartsOn raw option value from caller input
+ * @returns `"monday"`, `"sunday"`, or `null` when the value is invalid
+ */
+export function resolveWeekStartsOn(weekStartsOn) {
+    if (weekStartsOn === undefined)
+        return "monday";
+    return weekStartsOn === "monday" || weekStartsOn === "sunday"
+        ? weekStartsOn
+        : null;
+}

package/dist/internal/rfc5322DateTime.d.ts

@@ -0,0 +1,26 @@
+/** Date-time fields read from an RFC 5322 `date-time`, before calendar validation. */
+export interface Rfc5322DateTimeFields {
+    /** ISO day of week 1 (Monday) – 7 (Sunday), when the input names one. */
+    dayOfWeek: number | undefined;
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    /** `±HH:MM`; `-0000` and every zone RFC 5322 maps to it are `+00:00`. */
+    offset: string;
+}
+/**
+ * Read the fields of an RFC 5322 `date-time` as a conformant receiver must:
+ * the §3.3 syntax plus the §4 obsolete syntax (CFWS between tokens, 2- and
+ * 3-digit years, alphabetic zones), with case-insensitive names.
+ *
+ * - Shape and name checks only: the calendar date, the time of day and the
+ *   day of week are left to the caller (`Temporal.PlainDateTime.from` with
+ *   `overflow: "reject"`).
+ *
+ * @param value candidate RFC 5322 date-time
+ * @returns the fields, or `null` when `value` is not a `date-time`
+ */
+export declare function readRfc5322DateTime(value: string): Rfc5322DateTimeFields | null;

package/dist/internal/rfc5322DateTime.js

@@ -0,0 +1,176 @@
+import { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES, } from "./englishCalendarNames.js";
+// RFC 5322 §4.3 obs-zone: UT/GMT and the North American zones, with the
+// offsets that section gives them.
+const NAMED_ZONE_OFFSETS = {
+    UT: "+00:00",
+    GMT: "+00:00",
+    EST: "-05:00",
+    EDT: "-04:00",
+    CST: "-06:00",
+    CDT: "-05:00",
+    MST: "-07:00",
+    MDT: "-06:00",
+    PST: "-08:00",
+    PDT: "-07:00",
+};
+// Stands in for a folded comment. NUL may appear in a message only as an
+// obsolete quoted-pair inside a comment (obs-qp = "\" (%d0 / …), RFC 5322
+// §4.1), which folding removes, so any other NUL makes the input invalid and
+// every NUL left after folding is a folded comment.
+const COMMENT = "\u0000";
+// The receiver grammar: RFC 5322 §3.3 plus the §4.3 obsolete forms, after
+// every comment has become COMMENT. `C` is one unit of CFWS (WSP, a folded
+// line, or a comment); ABNF literals are case-insensitive (RFC 5234 §2.3).
+//   date-time = [ day-of-week "," ] date time [CFWS]
+//   day-of-week = [CFWS] day-name [CFWS]      (current: [FWS] day-name)
+//   day = [CFWS] 1*2DIGIT [CFWS]              (current: [FWS] 1*2DIGIT FWS)
+//   year = [CFWS] 2*DIGIT [CFWS]              (current: FWS 4*DIGIT FWS)
+//   hour, minute, second = [CFWS] 2DIGIT [CFWS]
+//   zone = (FWS ("+" / "-") 4DIGIT) / obs-zone
+// A numeric zone needs FWS, so the character before its sign must be WSP.
+// Capture groups: 1 day-name, 2 day, 3 month, 4 year, 5 hour, 6 minute,
+// 7 second, 8 numeric zone, 9 alphabetic zone.
+const C = "(?:[ \\t\\u0000]|\\r\\n[ \\t])*";
+const RECEIVER_DATE_TIME = new RegExp(`^${C}(?:([A-Za-z]{3})${C},${C})?(\\d{1,2})${C}([A-Za-z]{3})${C}(\\d{2,})${C}` +
+    `(\\d{2})${C}:${C}(\\d{2})${C}(?::${C}(\\d{2})${C})?` +
+    `(?:(?<=[ \\t])([+-]\\d{4})|([A-Za-z]+))${C}$`);
+// comment = "(" *([FWS] ccontent) [FWS] ")", ccontent = ctext / quoted-pair
+// / comment, quoted-pair = "\" (VCHAR / WSP) / obs-qp (RFC 5322 §3.2.2 for
+// comment and ccontent, §3.2.1 for quoted-pair, §4.1 for obs-qp). One
+// left-to-right pass with a depth counter replaces each outermost
+// comment by COMMENT, so the work is linear in the input at any nesting depth.
+// A backslash escapes the character after it inside a comment; outside one
+// it is literal (and the receiver grammar rejects it). Returns null for an
+// unbalanced parenthesis, and for a NUL after an even run of backslashes (not
+// an obs-qp, so not allowed anywhere).
+function foldComments(value) {
+    if (hasUnquotedNul(value))
+        return null;
+    let folded = "";
+    let index = 0;
+    while (index < value.length) {
+        const char = value[index];
+        // A ")" with no comment open.
+        if (char === ")")
+            return null;
+        if (char === "(") {
+            index = commentEnd(value, index);
+            if (index < 0)
+                return null;
+            folded += COMMENT;
+        }
+        else {
+            folded += char;
+            index += 1;
+        }
+    }
+    return folded;
+}
+// Index just after the ")" that closes the comment opened at `start`, or -1
+// when it never closes. A backslash quotes the character after it.
+function commentEnd(value, start) {
+    let depth = 0;
+    for (let index = start; index < value.length; index++) {
+        const char = value[index];
+        if (char === "\\") {
+            index += 1;
+        }
+        else if (char === "(") {
+            depth += 1;
+        }
+        else if (char === ")") {
+            depth -= 1;
+            if (depth === 0)
+                return index + 1;
+        }
+    }
+    return -1;
+}
+// True when a NUL follows an even run of backslashes (none included), so it
+// is not an obs-qp.
+function hasUnquotedNul(value) {
+    let backslashRun = 0;
+    for (const char of value) {
+        if (char === COMMENT && backslashRun % 2 === 0)
+            return true;
+        backslashRun = char === "\\" ? backslashRun + 1 : 0;
+    }
+    return false;
+}
+// RFC 5322 §4.3: a 2-digit year 00–49 adds 2000, 50–99 adds 1900; a 3-digit
+// year adds 1900. Four or more digits are the year itself.
+function interpretYear(digits) {
+    const year = Number(digits);
+    if (digits.length === 2)
+        return year < 50 ? year + 2000 : year + 1900;
+    if (digits.length === 3)
+        return year + 1900;
+    return year;
+}
+function numericZoneOffset(zone) {
+    // "the last two digits of the zone MUST be within the range 00 through 59"
+    if (Number(zone.slice(3)) > 59)
+        return null;
+    return `${zone.slice(0, 3)}:${zone.slice(3)}`;
+}
+function alphabeticZoneOffset(zone) {
+    const upper = zone.toUpperCase();
+    const named = NAMED_ZONE_OFFSETS[upper];
+    if (named !== undefined)
+        return named;
+    // Military zones are %d65-73 / %d75-90 (A–I, K–Z, either case): J is not
+    // one. Those and any other multi-character alphabetic zone "SHOULD all be
+    // considered equivalent to -0000", which Temporal writes as +00:00.
+    if (upper === "J")
+        return null;
+    return "+00:00";
+}
+function indexOfName(names, name) {
+    const wanted = name.toLowerCase();
+    return names.findIndex((candidate) => candidate.toLowerCase() === wanted);
+}
+/**
+ * Read the fields of an RFC 5322 `date-time` as a conformant receiver must:
+ * the §3.3 syntax plus the §4 obsolete syntax (CFWS between tokens, 2- and
+ * 3-digit years, alphabetic zones), with case-insensitive names.
+ *
+ * - Shape and name checks only: the calendar date, the time of day and the
+ *   day of week are left to the caller (`Temporal.PlainDateTime.from` with
+ *   `overflow: "reject"`).
+ *
+ * @param value candidate RFC 5322 date-time
+ * @returns the fields, or `null` when `value` is not a `date-time`
+ */
+export function readRfc5322DateTime(value) {
+    const folded = foldComments(value);
+    if (folded === null)
+        return null;
+    const match = RECEIVER_DATE_TIME.exec(folded);
+    if (match === null)
+        return null;
+    const [, dayName, day, monthName, year, hour, minute, second, numericZone, alphabeticZone,] = match;
+    const month = indexOfName(ENGLISH_MONTH_NAMES, monthName) + 1;
+    if (month === 0)
+        return null;
+    let dayOfWeek;
+    if (dayName !== undefined) {
+        dayOfWeek = indexOfName(ENGLISH_WEEKDAY_NAMES, dayName) + 1;
+        if (dayOfWeek === 0)
+            return null;
+    }
+    const offset = numericZone === undefined
+        ? alphabeticZoneOffset(alphabeticZone)
+        : numericZoneOffset(numericZone);
+    if (offset === null)
+        return null;
+    return {
+        dayOfWeek,
+        year: interpretYear(year),
+        month,
+        day: Number(day),
+        hour: Number(hour),
+        minute: Number(minute),
+        second: second === undefined ? 0 : Number(second),
+        offset,
+    };
+}