@northguild/gmt 1.15.0 → 1.16.0

package/dist/utc/interval/splitIntervalByUnitUtc.js

@@ -1,21 +1,39 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../regex/utc-date-time.js";
+import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isValidUtc } from "../validate/isValidUtc.js";
-import { resolveDurationUnit } from "../../internal/index.js";
+import { resolveDurationUnit, tileByUnit } from "../../internal/index.js";
+import { exceedsPieceLimit, resolveMaxPieces } from "../../internal/maxPieces.js";
+import { minSlicesForSpan } from "../../internal/splitStep.js";
 /**
  * Split a UTC interval into sub-intervals of `amount × unit`.
  *
- * - Returns an array of `{ start, end }` records that tile the interval.
+ * - Returns an array of `{ start, end }` records that tile the interval, each record's `end`
+ *   equal to the next record's `start`.
+ * - Every piece is half-open `[start, end)`: a boundary belongs only to the piece that starts
+ *   there, so the pieces share no value and together cover the interval exactly once (the rule
+ *   CORE-6's `splitIntervalAt` uses).
  * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
+ * - Calendar-unit boundaries (years, months, weeks, days) are computed from `start`
+ *   (`start + k × amount`, as Temporal and Luxon's `Interval.splitBy` do), so month-end starts
+ *   don't drift: a monthly split from January 31 lands on February 29, March 31, April 30.
+ * - Exact-unit boundaries (hours and smaller) step from the previous boundary. Exact units never
+ *   clamp, and stepping keeps nanosecond precision where `k × amount` would pass
+ *   `Number.MAX_SAFE_INTEGER`.
+ * - A step that resolves to the same instant as the previous boundary is skipped, so no empty
+ *   slice is produced. A step that goes backwards returns `[]`.
  * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
  * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
  *   leap-second strings).
+ * - `options.maxPieces` (positive safe integer, default `1_000_000`) bounds the output: a split
+ *   into more slices returns `[]`, decided from the span before stepping where it can be, and
+ *   otherwise as soon as slice `maxPieces + 1` is due. An invalid `maxPieces` also returns `[]`.
  *
  * @param start ISO UTC datetime string for the interval start
  * @param end ISO UTC datetime string for the interval end
  * @param unit duration unit string — any `DateTimeDurationUnit`
  * @param amount positive number of units per step
+ * @param options optional: `maxPieces` (positive safe integer, default `1_000_000`)
  * @returns array of `{ start, end }` records, or [] on invalid input
  *
  * @example splitIntervalByUnitUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "hour", 6) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T06:00:00Z" }, { start: "2024-01-01T06:00:00Z", end: "2024-01-01T12:00:00Z" }, { start: "2024-01-01T12:00:00Z", end: "2024-01-01T18:00:00Z" }, { start: "2024-01-01T18:00:00Z", end: "2024-01-02T00:00:00Z" }]
@@ -23,56 +41,59 @@ import { resolveDurationUnit } from "../../internal/index.js";
  * @example splitIntervalByUnitUtc("2024-01-01T00:00:00Z", "2024-01-01T00:00:00Z", "hour", 1) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T00:00:00Z" }]
  * @example splitIntervalByUnitUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "hour", 0) // []
  * @example splitIntervalByUnitUtc("invalid", "2024-01-02T00:00:00Z", "hour", 1) // []
+ * @example splitIntervalByUnitUtc("2024-01-01T00:00:00Z", "2024-01-01T01:30:00Z", "hour", 1, { maxPieces: 1 }) // [] (2 slices exceed the limit)
+ * @example splitIntervalByUnitUtc("2024-01-01T00:00:00Z", "2024-01-01T01:30:00Z", "hour", 1, { maxPieces: 2 }) // [{ start: "2024-01-01T00:00:00Z", end: "2024-01-01T01:00:00Z" }, { start: "2024-01-01T01:00:00Z", end: "2024-01-01T01:30:00Z" }]
+ * @example splitIntervalByUnitUtc("+275760-09-12T23:00:00Z", "+275760-09-13T00:00:00Z", "hour", 2) // [{ start: "+275760-09-12T23:00:00Z", end: "+275760-09-13T00:00:00Z" }] (the step past the last instant is trimmed to `end`)
  */
-export function splitIntervalByUnitUtc(start, end, unit, amount) {
-    if (typeof start !== "string" || typeof end !== "string") {
-        return [];
-    }
-    if (!utcDateTime.test(start) || !utcDateTime.test(end)) {
-        return [];
-    }
-    if (isLeapSecond(start) || isLeapSecond(end)) {
-        return [];
-    }
-    if (!isValidUtc(start) || !isValidUtc(end)) {
-        return [];
-    }
-    if (typeof unit !== "string") {
-        return [];
-    }
-    const resolvedUnit = resolveDurationUnit(unit);
-    if (!resolvedUnit) {
-        return [];
-    }
-    if (!Number.isFinite(amount) || amount <= 0) {
-        return [];
-    }
+export function splitIntervalByUnitUtc(start, end, unit, amount, options) {
     try {
-        const startInstant = Temporal.Instant.from(start);
-        const endInstant = Temporal.Instant.from(end);
-        if (Temporal.Instant.compare(startInstant, endInstant) > 0) {
+        if (typeof start !== "string" || typeof end !== "string") {
             return [];
         }
-        if (Temporal.Instant.compare(startInstant, endInstant) === 0) {
-            return [{ start: startInstant.toString(), end: endInstant.toString() }];
+        if (!isValidUtc(start) || !isValidUtc(end)) {
+            return [];
+        }
+        if (typeof unit !== "string") {
+            return [];
+        }
+        const resolvedUnit = resolveDurationUnit(unit);
+        // An unknown unit is invalid whatever the span, a zero-length one included.
+        if (!isValidDateTimeDurationUnit(resolvedUnit)) {
+            return [];
+        }
+        if (!Number.isFinite(amount) || amount <= 0) {
+            return [];
         }
-        const result = [];
-        for (let currentInstant = startInstant; Temporal.Instant.compare(currentInstant, endInstant) < 0;) {
-            const zoned = currentInstant.toZonedDateTimeISO("UTC");
-            const next = zoned.add({ [resolvedUnit]: amount }).toInstant();
-            if (Temporal.Instant.compare(next, currentInstant) === 0) {
+        const maxPieces = resolveMaxPieces(options);
+        if (maxPieces === null) {
+            return [];
+        }
+        try {
+            const startInstant = Temporal.Instant.from(start);
+            const endInstant = Temporal.Instant.from(end);
+            if (Temporal.Instant.compare(startInstant, endInstant) > 0) {
                 return [];
             }
-            const sliceEnd = Temporal.Instant.compare(next, endInstant) > 0 ? endInstant : next;
-            result.push({
-                start: currentInstant.toString(),
-                end: sliceEnd.toString(),
-            });
-            currentInstant = next;
+            if (Temporal.Instant.compare(startInstant, endInstant) === 0) {
+                return [{ start: startInstant.toString(), end: endInstant.toString() }];
+            }
+            const spanNs = Number(endInstant.epochNanoseconds - startInstant.epochNanoseconds);
+            if (exceedsPieceLimit(minSlicesForSpan(spanNs, resolvedUnit, amount, false), maxPieces)) {
+                return [];
+            }
+            const slices = tileByUnit(startInstant.toZonedDateTimeISO("UTC"), endInstant.toZonedDateTimeISO("UTC"), Temporal.ZonedDateTime.compare, resolvedUnit, amount, maxPieces);
+            return (slices ?? []).map(([sliceStart, sliceEnd]) => ({
+                start: sliceStart.toInstant().toString(),
+                end: sliceEnd.toInstant().toString(),
+            }));
+        }
+        catch {
+            return [];
         }
-        return result;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/utc/interval/validate/isValidUtcInterval.d.ts

@@ -6,6 +6,9 @@
  * - Equal `start === end` is valid.
  * - Leap-second strings return `false`.
  * - Invalid input or malformed strings return `false`.
+ * - Each endpoint must satisfy `isValidUtc`, so annotations are read as `Temporal.Instant.from` reads
+ *   them: a time zone annotation (`[Asia/Tokyo]`), any calendar annotation and an elective annotation
+ *   (`[foo=bar]`) are ignored; an unknown critical annotation (`[!foo=bar]`) is rejected.
  *
  * @param start ISO 8601 UTC datetime string (interval start)
  * @param end ISO 8601 UTC datetime string (interval end)
@@ -15,5 +18,7 @@
  * @example isValidUtcInterval("2024-01-01T10:00:00Z", "2024-01-01T10:00:00Z") // true
  * @example isValidUtcInterval("2024-12-31T23:59:59Z", "2024-01-01T10:00:00Z") // false
  * @example isValidUtcInterval("invalid", "2024-12-31T23:59:59Z") // false
+ * @example isValidUtcInterval("2024-01-01T10:00:00Z[u-ca=hebrew]", "2024-12-31T23:59:59Z[foo=bar]") // true (annotations ignored)
+ * @example isValidUtcInterval("2024-01-01T10:00:00Z[!foo=bar]", "2024-12-31T23:59:59Z") // false (unknown critical annotation)
  */
 export declare function isValidUtcInterval(start: string, end: string): boolean;

package/dist/utc/interval/validate/isValidUtcInterval.js

@@ -1,6 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isLeapSecond } from "../../../plain/validate/isLeapSecond.js";
-import { utcDateTime } from "../../../regex/utc-date-time.js";
+import { isValidUtc } from "../../validate/index.js";
 /**
  * Return true if `start` and `end` form a valid UTC interval — both parseable as
  * ISO UTC datetime strings and the instant at `start` is <= the instant at `end`.
@@ -9,6 +8,9 @@ import { utcDateTime } from "../../../regex/utc-date-time.js";
  * - Equal `start === end` is valid.
  * - Leap-second strings return `false`.
  * - Invalid input or malformed strings return `false`.
+ * - Each endpoint must satisfy `isValidUtc`, so annotations are read as `Temporal.Instant.from` reads
+ *   them: a time zone annotation (`[Asia/Tokyo]`), any calendar annotation and an elective annotation
+ *   (`[foo=bar]`) are ignored; an unknown critical annotation (`[!foo=bar]`) is rejected.
  *
  * @param start ISO 8601 UTC datetime string (interval start)
  * @param end ISO 8601 UTC datetime string (interval end)
@@ -18,15 +20,14 @@ import { utcDateTime } from "../../../regex/utc-date-time.js";
  * @example isValidUtcInterval("2024-01-01T10:00:00Z", "2024-01-01T10:00:00Z") // true
  * @example isValidUtcInterval("2024-12-31T23:59:59Z", "2024-01-01T10:00:00Z") // false
  * @example isValidUtcInterval("invalid", "2024-12-31T23:59:59Z") // false
+ * @example isValidUtcInterval("2024-01-01T10:00:00Z[u-ca=hebrew]", "2024-12-31T23:59:59Z[foo=bar]") // true (annotations ignored)
+ * @example isValidUtcInterval("2024-01-01T10:00:00Z[!foo=bar]", "2024-12-31T23:59:59Z") // false (unknown critical annotation)
  */
 export function isValidUtcInterval(start, end) {
     if (typeof start !== "string" || typeof end !== "string") {
         return false;
     }
-    if (!utcDateTime.test(start) || !utcDateTime.test(end)) {
-        return false;
-    }
-    if (isLeapSecond(start) || isLeapSecond(end)) {
+    if (!isValidUtc(start) || !isValidUtc(end)) {
         return false;
     }
     try {

package/dist/utc/parse/parseDateFromUtc.d.ts

@@ -2,12 +2,18 @@
  * Extract the date portion from a UTC datetime string.
  *
  * - Uses Temporal.Instant.from to parse, converts to UTC date.
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns ISO date string (e.g., "2024-03-17") or "" on invalid input
  *
  * @example parseDateFromUtc("2024-03-17T14:30:45Z") // "2024-03-17"
+ * @example parseDateFromUtc("2025-01-01T02:00:00Z", { timeZone: "America/New_York" }) // "2024-12-31"
  * @example parseDateFromUtc("invalid") // ""
  */
-export declare function parseDateFromUtc(value: string): string;
+export declare function parseDateFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseDateFromUtc.js

@@ -1,27 +1,32 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../validate/index.js";
+import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Extract the date portion from a UTC datetime string.
  *
  * - Uses Temporal.Instant.from to parse, converts to UTC date.
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns ISO date string (e.g., "2024-03-17") or "" on invalid input
  *
  * @example parseDateFromUtc("2024-03-17T14:30:45Z") // "2024-03-17"
+ * @example parseDateFromUtc("2025-01-01T02:00:00Z", { timeZone: "America/New_York" }) // "2024-12-31"
  * @example parseDateFromUtc("invalid") // ""
  */
-export function parseDateFromUtc(value) {
-    if (!isValidUtc(value)) {
-        return "";
-    }
+export function parseDateFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return dateTime.toPlainDate().toString();
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const dateTime = utcZonedDateTime(value, options);
+        return dateTime === null ? "" : dateTime.toPlainDate().toString();
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/parse/parseDayFromUtc.d.ts

@@ -2,12 +2,18 @@
  * Return the day of month (1-31) from a UTC datetime string.
  *
  * - Returns zero-padded string for day.
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns Day (01-31) or "" on invalid input
  *
  * @example parseDayFromUtc("2024-03-17T14:30:45Z") // "17"
+ * @example parseDayFromUtc("2024-03-17T02:30:45Z", { timeZone: "America/New_York" }) // "16"
  * @example parseDayFromUtc("invalid") // ""
  */
-export declare function parseDayFromUtc(value: string): string;
+export declare function parseDayFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseDayFromUtc.js

@@ -1,26 +1,32 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../validate/index.js";
+import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the day of month (1-31) from a UTC datetime string.
  *
  * - Returns zero-padded string for day.
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns Day (01-31) or "" on invalid input
  *
  * @example parseDayFromUtc("2024-03-17T14:30:45Z") // "17"
+ * @example parseDayFromUtc("2024-03-17T02:30:45Z", { timeZone: "America/New_York" }) // "16"
  * @example parseDayFromUtc("invalid") // ""
  */
-export function parseDayFromUtc(value) {
-    if (!isValidUtc(value))
-        return "";
+export function parseDayFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return dateTime.day.toString().padStart(2, "0");
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const dateTime = utcZonedDateTime(value, options);
+        return dateTime === null ? "" : dateTime.day.toString().padStart(2, "0");
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/parse/parseDayOfWeekFromUtc.d.ts

@@ -2,13 +2,19 @@
  * Return the day of week (1-7) from a UTC datetime string.
  *
  * - Monday=1 through Sunday=7.
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns Day of week (1-7) or null on invalid input
  *
  * @example parseDayOfWeekFromUtc("2024-03-17T14:30:45Z") // 7
  * @example parseDayOfWeekFromUtc("2024-03-18T00:00:00Z") // 1
+ * @example parseDayOfWeekFromUtc("2024-03-17T02:30:45Z", { timeZone: "America/New_York" }) // 6 (Saturday in New York)
  * @example parseDayOfWeekFromUtc("invalid") // null
  */
-export declare function parseDayOfWeekFromUtc(value: string): number | null;
+export declare function parseDayOfWeekFromUtc(value: string, options?: {
+    timeZone?: string;
+}): number | null;

package/dist/utc/parse/parseDayOfWeekFromUtc.js

@@ -1,27 +1,45 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveReadingTimeZone } from "../../internal/resolveReadingTimeZone.js";
 import { isValidUtc } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the day of week (1-7) from a UTC datetime string.
  *
  * - Monday=1 through Sunday=7.
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns null.
  * - Returns null for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns Day of week (1-7) or null on invalid input
  *
  * @example parseDayOfWeekFromUtc("2024-03-17T14:30:45Z") // 7
  * @example parseDayOfWeekFromUtc("2024-03-18T00:00:00Z") // 1
+ * @example parseDayOfWeekFromUtc("2024-03-17T02:30:45Z", { timeZone: "America/New_York" }) // 6 (Saturday in New York)
  * @example parseDayOfWeekFromUtc("invalid") // null
  */
-export function parseDayOfWeekFromUtc(value) {
-    if (!isValidUtc(value))
-        return null;
+export function parseDayOfWeekFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return dateTime.dayOfWeek;
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        if (!isValidUtc(value))
+            return null;
+        const timeZone = resolveReadingTimeZone(options?.timeZone);
+        if (timeZone === null)
+            return null;
+        try {
+            const dateTime = Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
+            return dateTime.dayOfWeek;
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/utc/parse/parseHourFromUtc.d.ts

@@ -2,12 +2,18 @@
  * Return the hour (0-23) from a UTC datetime string.
  *
  * - Returns zero-padded string for hour.
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns Hour (00-23) or "" on invalid input
  *
  * @example parseHourFromUtc("2024-03-17T14:30:45Z") // "14"
+ * @example parseHourFromUtc("2024-03-17T02:30:45Z", { timeZone: "America/New_York" }) // "22"
  * @example parseHourFromUtc("invalid") // ""
  */
-export declare function parseHourFromUtc(value: string): string;
+export declare function parseHourFromUtc(value: string, options?: {
+    timeZone?: string;
+}): string;

package/dist/utc/parse/parseHourFromUtc.js

@@ -1,26 +1,32 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { isValidUtc } from "../validate/index.js";
+import { utcZonedDateTime } from "../../internal/utcZonedDateTime.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return the hour (0-23) from a UTC datetime string.
  *
  * - Returns zero-padded string for hour.
+ * - Reads the value on the wall clock of `options.timeZone` (an IANA zone, default UTC), as
+ *   `parseTimeFromUtc` does; an invalid zone returns "".
  * - Returns "" for invalid input.
  *
  * @param value ISO UTC datetime string (e.g., "2024-03-17T14:30:45Z")
+ * @param options optional: timeZone (IANA, default "UTC")
  * @returns Hour (00-23) or "" on invalid input
  *
  * @example parseHourFromUtc("2024-03-17T14:30:45Z") // "14"
+ * @example parseHourFromUtc("2024-03-17T02:30:45Z", { timeZone: "America/New_York" }) // "22"
  * @example parseHourFromUtc("invalid") // ""
  */
-export function parseHourFromUtc(value) {
-    if (!isValidUtc(value))
-        return "";
+export function parseHourFromUtc(value, options) {
     try {
-        const instant = Temporal.Instant.from(value);
-        const dateTime = instant.toZonedDateTimeISO("UTC");
-        return dateTime.hour.toString().padStart(2, "0");
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const dateTime = utcZonedDateTime(value, options);
+        return dateTime === null ? "" : dateTime.hour.toString().padStart(2, "0");
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/utc/parse/parseHttp.d.ts

@@ -1,24 +1,49 @@
 /**
- * Parse an RFC 7231 IMF-fixdate string — the fixed grammar HTTP headers like
+ * Parse an RFC 9110 HTTP-date — the fixed grammar HTTP headers like
  * `Last-Modified`/`Date`/`Expires` use — into a UTC ISO 8601 datetime string.
  *
- * - **Decoding, not display.** Accepts English weekday/month abbreviations
- *   only, per the fixed grammar (see `formatHttp`'s JSDoc and roadmap
- *   Decision 1).
- * - **IMF-fixdate only.** RFC 7231 also lists two obsolete forms
- *   (`rfc850-date`, `asctime-date`) that real HTTP servers occasionally
- *   still emit; this is a documented limitation — neither is accepted here.
- * - Day, hour, minute, and second must each be exactly 2 digits and the
- *   trailing zone must be the literal `GMT` — unlike `parseRfc2822`, no
- *   numeric offset or named-zone table is accepted.
- * - The day-of-week is not cross-validated against the computed date, the
- *   same deliberate scope limit `parseDateTimeWithPattern`/J11 uses.
+ * - **Decoding, not display.** Accepts English weekday/month names only, per
+ *   the fixed grammar (see `formatHttp`'s JSDoc and roadmap Decision 1).
+ * - **All three HTTP-date formats**, as RFC 9110 §5.6.7 requires ("A
+ *   recipient that parses a timestamp value in an HTTP field MUST accept all
+ *   three"): IMF-fixdate (`Sun, 06 Nov 1994 08:49:37 GMT`), the obsolete
+ *   rfc850-date (`Sunday, 06-Nov-94 08:49:37 GMT`) and asctime-date
+ *   (`Sun Nov  6 08:49:37 1994`, read as UTC).
+ * - HTTP-date is case-sensitive and fixed-width: exactly the spacing, digit
+ *   counts and the literal `GMT` of the grammar. No numeric offset is
+ *   accepted.
+ * - **rfc850-date years read the clock.** Its two-digit year becomes the
+ *   latest year ending in those digits whose timestamp is not more than 50
+ *   years after now (`Temporal.Now.instant()`), per RFC 9110: "a timestamp
+ *   that appears to be more than 50 years in the future" is "the most recent
+ *   year in the past that had the same last two digits". The same string can
+ *   therefore parse differently decades apart; if the clock cannot be read
+ *   the result is `""`.
+ * - **The day name must match the date, in all three formats.** RFC 9110 gives it
+ *   RFC 5322's semantics: "the day-of-week (if included) MUST be the day implied by
+ *   the date". A mismatch returns `""` — deliberately in asctime-date too, where the
+ *   day name is not separated by a comma and so is easy to overlook. `Mon Nov  6
+ *   08:49:37 1994` is `""`, exactly as `Mon, 06 Nov 1994 08:49:37 GMT` and
+ *   `Monday, 06-Nov-94 08:49:37 GMT` are: 6 November 1994 was a Sunday. A parser that
+ *   accepted the mismatch would have to pick which of the two fields to believe, and
+ *   there is no rule in RFC 9110 that says which.
+ * - An impossible calendar date (`31 Feb`, `29 Feb 2023`) returns `""`: a parser never
+ *   invents a date, so fields are validated with `overflow: "reject"`, not clamped.
+ * - For the IMF-fixdate shape alone, test the exported `httpDate` pattern.
+ * - **Compatibility:** before 1.16.0 a day name that did not match the date was ignored.
+ *   Parse the same fields as an RFC 5322 date-time without the day name, then convert.
  *
- * @param value RFC 7231 IMF-fixdate string (e.g. "Fri, 15 Mar 2024 14:30:00 GMT")
+ * @param value RFC 9110 HTTP-date string (e.g. "Fri, 15 Mar 2024 14:30:00 GMT")
  * @returns UTC ISO 8601 datetime string, or "" on invalid input
  *
  * @example parseHttp("Fri, 15 Mar 2024 14:30:00 GMT") // "2024-03-15T14:30:00Z"
- * @example parseHttp("Fri, 15 Mar 2024 14:30:00 -0400") // "" (not IMF-fixdate)
+ * @example parseHttp("Sunday, 06-Nov-94 08:49:37 GMT") // "1994-11-06T08:49:37Z" (rfc850-date)
+ * @example parseHttp("Sun Nov  6 08:49:37 1994") // "1994-11-06T08:49:37Z" (asctime-date)
+ * @example parseHttp("Fri, 15 Mar 2024 14:30:00 -0400") // "" (not an HTTP-date)
+ * @example parseHttp("Sat, 15 Mar 2024 14:30:00 GMT") // "" (15 Mar 2024 was a Friday)
+ * @example parseHttp("Mon Nov  6 08:49:37 1994") // "" (asctime-date; 6 Nov 1994 was a Sunday)
+ * @example convertZonedToUtc(parseRfc2822("15 Mar 2024 14:30:00 GMT")) // "2024-03-15T14:30:00Z" — the day name removed
+ * @example parseHttp("Sat, 31 Feb 2024 14:30:00 GMT") // "" (impossible date)
  * @example parseHttp("not a date") // ""
  */
 export declare function parseHttp(value: string): string;