@northguild/gmt 1.15.0 → 1.16.0

package/dist/zoned/parse/getZonedOffsetAs.d.ts

@@ -12,7 +12,7 @@
  * import { getZonedOffsetAs } from "@northguild/gmt/zoned";
  * getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "minutes");
  */
-export type ZonedOffsetUnit = "minutes" | "nanoseconds";
+export type ZonedOffsetUnit = "minutes" | "nanoseconds" | "minute" | "nanosecond";
 /**
  * Read a zoned value's UTC offset as a number, in the given unit.
  *
@@ -24,16 +24,18 @@ export type ZonedOffsetUnit = "minutes" | "nanoseconds";
  * - "minutes" divides by 60e9 — every IANA offset is a whole number of
  *   minutes, so this never truncates a fraction.
  * - Negative offsets (west of UTC) return a negative number.
+ * - `unit` accepts the plural or singular name (`"minutes"` or `"minute"`), as Temporal does.
  * - Returns null on invalid `value` or `unit`.
  *
  * @param value zoned ISO 8601 datetime string
- * @param unit "minutes" | "nanoseconds"
+ * @param unit "minutes" | "nanoseconds" (or the singular "minute" | "nanosecond")
  * @returns the offset in the requested unit, or null on invalid input
  *
  * @example getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "minutes") // -240
  * @example getZonedOffsetAs("2024-05-15T12:00:00+05:45[Asia/Kathmandu]", "minutes") // 345
  * @example getZonedOffsetAs("2024-02-29T12:00:00+00:00[UTC]", "nanoseconds") // 0
  * @example getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "nanoseconds") // -14400000000000
+ * @example getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "minute") // -240 (singular unit name)
  * @example getZonedOffsetAs("invalid", "minutes") // null
  * @example getZonedOffsetAs("2024-02-29T12:00:00+00:00[UTC]", "fortnights" as never) // null
  */

package/dist/zoned/parse/getZonedOffsetAs.js

@@ -1,8 +1,11 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 const NANOSECONDS_PER_MINUTE = 60_000_000_000;
 function isValidZonedOffsetUnit(unit) {
-    return unit === "minutes" || unit === "nanoseconds";
+    return (unit === "minutes" ||
+        unit === "nanoseconds" ||
+        unit === "minute" ||
+        unit === "nanosecond");
 }
 /**
  * Read a zoned value's UTC offset as a number, in the given unit.
@@ -15,16 +18,18 @@ function isValidZonedOffsetUnit(unit) {
  * - "minutes" divides by 60e9 — every IANA offset is a whole number of
  *   minutes, so this never truncates a fraction.
  * - Negative offsets (west of UTC) return a negative number.
+ * - `unit` accepts the plural or singular name (`"minutes"` or `"minute"`), as Temporal does.
  * - Returns null on invalid `value` or `unit`.
  *
  * @param value zoned ISO 8601 datetime string
- * @param unit "minutes" | "nanoseconds"
+ * @param unit "minutes" | "nanoseconds" (or the singular "minute" | "nanosecond")
  * @returns the offset in the requested unit, or null on invalid input
  *
  * @example getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "minutes") // -240
  * @example getZonedOffsetAs("2024-05-15T12:00:00+05:45[Asia/Kathmandu]", "minutes") // 345
  * @example getZonedOffsetAs("2024-02-29T12:00:00+00:00[UTC]", "nanoseconds") // 0
  * @example getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "nanoseconds") // -14400000000000
+ * @example getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "minute") // -240 (singular unit name)
  * @example getZonedOffsetAs("invalid", "minutes") // null
  * @example getZonedOffsetAs("2024-02-29T12:00:00+00:00[UTC]", "fortnights" as never) // null
  */
@@ -33,8 +38,8 @@ export function getZonedOffsetAs(value, unit) {
         return null;
     }
     try {
-        const { offsetNanoseconds } = Temporal.ZonedDateTime.from(value);
-        return unit === "nanoseconds"
+        const { offsetNanoseconds } = zonedDateTimeFrom(value);
+        return unit === "nanoseconds" || unit === "nanosecond"
             ? offsetNanoseconds
             : offsetNanoseconds / NANOSECONDS_PER_MINUTE;
     }

package/dist/zoned/parse/parseDateFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Extract the plain date portion from an ISO 8601 zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function parseDateFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime?.toPlainDate().toString();
     }
     catch {

package/dist/zoned/parse/parseDateTimeFromZoned.js

@@ -1,6 +1,6 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isLeapSecond } from "../../plain/validate/isLeapSecond.js";
 import { isValidZonedDateTime } from "../validate/isValidZonedDateTime.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Parse a zoned datetime and return the plain local datetime portion as an ISO plain datetime string.
  *
@@ -19,7 +19,7 @@ export const parseDateTimeFromZoned = (value) => {
         return "";
     }
     try {
-        return Temporal.ZonedDateTime.from(value).toPlainDateTime().toString();
+        return zonedDateTimeFrom(value).toPlainDateTime().toString();
     }
     catch {
         return "";

package/dist/zoned/parse/parseDayFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the day (1-31) from a zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function parseDayFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime.day.toString().padStart(2, "0");
     }
     catch {

package/dist/zoned/parse/parseDayOfWeekFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the day of the week (1-7, Monday-Sunday) from a zoned datetime string.
  *
@@ -18,7 +18,7 @@ export function parseDayOfWeekFromZoned(value) {
         return null;
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime.dayOfWeek;
     }
     catch {

package/dist/zoned/parse/parseHourFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the hour (0-23) from a zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function parseHourFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime.hour.toString().padStart(2, "0");
     }
     catch {

package/dist/zoned/parse/parseMicrosecondFromZoned.d.ts

@@ -7,7 +7,8 @@
  * @param value ISO zoned datetime string (e.g., "2024-03-15T14:30:45.123456+00:00[UTC]")
  * @returns Microsecond (000-999) or "" on invalid input
  *
- * @example parseMicrosecondFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "123"
+ * @example parseMicrosecondFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "000"
+ * @example parseMicrosecondFromZoned("2024-03-15T14:30:45.123456+00:00[UTC]") // "456"
  * @example parseMicrosecondFromZoned("invalid") // ""
  */
 export declare function parseMicrosecondFromZoned(value: string): string;

package/dist/zoned/parse/parseMicrosecondFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the microsecond (0-999) from a zoned datetime string.
  *
@@ -9,7 +9,8 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * @param value ISO zoned datetime string (e.g., "2024-03-15T14:30:45.123456+00:00[UTC]")
  * @returns Microsecond (000-999) or "" on invalid input
  *
- * @example parseMicrosecondFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "123"
+ * @example parseMicrosecondFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "000"
+ * @example parseMicrosecondFromZoned("2024-03-15T14:30:45.123456+00:00[UTC]") // "456"
  * @example parseMicrosecondFromZoned("invalid") // ""
  */
 export function parseMicrosecondFromZoned(value) {
@@ -17,7 +18,7 @@ export function parseMicrosecondFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return (zonedDateTime.microsecond ?? 0).toString().padStart(3, "0");
     }
     catch {

package/dist/zoned/parse/parseMillisecondFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the millisecond (0-999) from a zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function parseMillisecondFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime.millisecond.toString().padStart(3, "0");
     }
     catch {

package/dist/zoned/parse/parseMinuteFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the minute (0-59) from a zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function parseMinuteFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime.minute.toString().padStart(2, "0");
     }
     catch {

package/dist/zoned/parse/parseMonthFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the month (1-12) from a zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function parseMonthFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime.month.toString().padStart(2, "0");
     }
     catch {

package/dist/zoned/parse/parseNanosecondFromZoned.d.ts

@@ -7,7 +7,8 @@
  * @param value ISO zoned datetime string (e.g., "2024-03-15T14:30:45.123456789+00:00[UTC]")
  * @returns Nanosecond (000-999) or "" on invalid input
  *
- * @example parseNanosecondFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "123"
+ * @example parseNanosecondFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "000"
+ * @example parseNanosecondFromZoned("2024-03-15T14:30:45.123456789+00:00[UTC]") // "789"
  * @example parseNanosecondFromZoned("invalid") // ""
  */
 export declare function parseNanosecondFromZoned(value: string): string;

package/dist/zoned/parse/parseNanosecondFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the nanosecond (0-999) from a zoned datetime string.
  *
@@ -9,7 +9,8 @@ import { isValidZonedDateTime } from "../validate/index.js";
  * @param value ISO zoned datetime string (e.g., "2024-03-15T14:30:45.123456789+00:00[UTC]")
  * @returns Nanosecond (000-999) or "" on invalid input
  *
- * @example parseNanosecondFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "123"
+ * @example parseNanosecondFromZoned("2024-03-15T14:30:45.123+00:00[UTC]") // "000"
+ * @example parseNanosecondFromZoned("2024-03-15T14:30:45.123456789+00:00[UTC]") // "789"
  * @example parseNanosecondFromZoned("invalid") // ""
  */
 export function parseNanosecondFromZoned(value) {
@@ -17,7 +18,7 @@ export function parseNanosecondFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return (zonedDateTime.nanosecond ?? 0).toString().padStart(3, "0");
     }
     catch {

package/dist/zoned/parse/parseRfc2822.d.ts

@@ -2,25 +2,45 @@
  * Parse an RFC 5322 (RFC 2822) date-time string — the fixed grammar email
  * `Date:` headers use — into a zoned ISO 8601 datetime string.
  *
- * - **Decoding, not display.** Accepts English weekday/month abbreviations
- *   only, per the fixed grammar (see `formatRfc2822`'s JSDoc and roadmap
- *   Decision 1).
- * - Accepts a leading day-of-week (not cross-validated against the computed
- *   date, the same deliberate scope limit `parseDateTimeWithPattern`/J11
- *   uses for its `EEEE`/`EEE` tokens) and an optional `:ss` seconds field.
- * - Accepts a 1- or 2-digit day (the formal grammar's `1*2DIGIT`), unlike
- *   `parseHttp`/`parseSql`, which both require exactly 2 digits.
- * - Accepts a numeric `+HHMM`/`-HHMM` offset or one of RFC 5322's obsolete
- *   named zones (`GMT`, `UT`, and the eight North American zones); any other
- *   obs-zone letter is unrecognized and rejected.
+ * - **Decoding, not display.** Weekday and month names are English, per the
+ *   fixed grammar (see `formatRfc2822`'s JSDoc and roadmap Decision 1); like
+ *   every ABNF literal they match in any case (RFC 5234 §2.3).
+ * - **Reads what a conformant receiver must.** RFC 5322 §3.3 syntax: folding
+ *   white space (spaces, tabs, folded lines), nested comments such as a
+ *   trailing `(EDT)`, a 1- or 2-digit day, a 4-or-more-digit year and optional
+ *   seconds. §4 obsolete syntax, which "MUST be accepted and parsed": comments
+ *   and white space between any tokens, and 2- or 3-digit years (00–49 → 20xx,
+ *   50–99 → 19xx, 3 digits → +1900).
+ * - **Zones.** A numeric `+hhmm`/`-hhmm` (minutes 00–59), or an obsolete
+ *   alphabetic zone: `UT`/`GMT` are `+0000`, and `EST`/`EDT`/`CST`/`CDT`/
+ *   `MST`/`MDT`/`PST`/`PDT` have the offsets §4.3 gives them. Military
+ *   one-letter zones and any other alphabetic zone are read as `-0000`, as
+ *   §4.3 says they SHOULD be; `J` is not a zone and returns `""`.
+ * - **`-0000` and `+0000` both become `+00:00`.** RFC 5322 §3.3 gives `-0000`
+ *   the meaning "no information about the local time zone"; a Temporal offset
+ *   cannot carry that distinction, so it is lost.
+ * - **The day-of-week must match the date.** RFC 5322 §3.3: "the day-of-week
+ *   (if included) MUST be the day implied by the date". A mismatch returns `""`.
  * - The resulting offset becomes the zoned string's time zone identifier
- *   (e.g. `-05:00`), since RFC 2822 carries no IANA zone name to recover.
+ *   (e.g. `-05:00`), since RFC 5322 carries no IANA zone name to recover.
+ *   An offset of 24 hours or more cannot be represented and returns `""`.
+ * - 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 strict current-syntax shape alone, test the exported `rfc2822DateTime` pattern.
+ * - **Compatibility:** before 1.16.0 a day-of-week that did not match the date was ignored.
+ *   Remove the day-of-week to parse such a string: the date alone decides the result.
  *
  * @param value RFC 5322 date-time string (e.g. "Fri, 15 Mar 2024 14:30:00 -0400")
  * @returns zoned ISO 8601 datetime string, or "" on invalid input
  *
  * @example parseRfc2822("Fri, 15 Mar 2024 14:30:00 -0400") // "2024-03-15T14:30:00-04:00[-04:00]"
  * @example parseRfc2822("5 Jan 2024 09:00:00 GMT") // "2024-01-05T09:00:00+00:00[+00:00]"
+ * @example parseRfc2822("fri,15 Mar 24 14:30 -0400 (EDT)") // "2024-03-15T14:30:00-04:00[-04:00]" (obsolete 2-digit year, comment)
+ * @example parseRfc2822("Fri, 15 Mar 2024 14:30:00 CEST") // "2024-03-15T14:30:00+00:00[+00:00]" (unknown zone → -0000)
+ * @example parseRfc2822("Fri, 15 Mar 2024 14:30:00 -0000") // "2024-03-15T14:30:00+00:00[+00:00]"
+ * @example parseRfc2822("Sat, 15 Mar 2024 14:30:00 -0400") // "" (15 Mar 2024 was a Friday)
+ * @example parseRfc2822("15 Mar 2024 14:30:00 -0400") // "2024-03-15T14:30:00-04:00[-04:00]" — the weekday removed
+ * @example parseRfc2822("Sat, 31 Feb 2024 14:30:00 -0400") // "" (impossible date)
  * @example parseRfc2822("not a date") // ""
  */
 export declare function parseRfc2822(value: string): string;

package/dist/zoned/parse/parseRfc2822.js

@@ -1,69 +1,71 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { ENGLISH_MONTH_NAMES } from "../../internal/index.js";
-import { rfc2822DateTime } from "../../regex/index.js";
-// RFC 5322 §4.3 "obsolete date and time" — named zones an email parser must
-// still accept even though `formatRfc2822` never emits them. Any obs-zone
-// single-letter military zone outside this table is unrecognized ("" per
-// the spec's own admission that those are ambiguous) and rejected.
-const NAMED_ZONE_OFFSETS = {
-    UT: "+0000",
-    GMT: "+0000",
-    EST: "-0500",
-    EDT: "-0400",
-    CST: "-0600",
-    CDT: "-0500",
-    MST: "-0700",
-    MDT: "-0600",
-    PST: "-0800",
-    PDT: "-0700",
-};
+import { readRfc5322DateTime } from "../../internal/rfc5322DateTime.js";
 /**
  * Parse an RFC 5322 (RFC 2822) date-time string — the fixed grammar email
  * `Date:` headers use — into a zoned ISO 8601 datetime string.
  *
- * - **Decoding, not display.** Accepts English weekday/month abbreviations
- *   only, per the fixed grammar (see `formatRfc2822`'s JSDoc and roadmap
- *   Decision 1).
- * - Accepts a leading day-of-week (not cross-validated against the computed
- *   date, the same deliberate scope limit `parseDateTimeWithPattern`/J11
- *   uses for its `EEEE`/`EEE` tokens) and an optional `:ss` seconds field.
- * - Accepts a 1- or 2-digit day (the formal grammar's `1*2DIGIT`), unlike
- *   `parseHttp`/`parseSql`, which both require exactly 2 digits.
- * - Accepts a numeric `+HHMM`/`-HHMM` offset or one of RFC 5322's obsolete
- *   named zones (`GMT`, `UT`, and the eight North American zones); any other
- *   obs-zone letter is unrecognized and rejected.
+ * - **Decoding, not display.** Weekday and month names are English, per the
+ *   fixed grammar (see `formatRfc2822`'s JSDoc and roadmap Decision 1); like
+ *   every ABNF literal they match in any case (RFC 5234 §2.3).
+ * - **Reads what a conformant receiver must.** RFC 5322 §3.3 syntax: folding
+ *   white space (spaces, tabs, folded lines), nested comments such as a
+ *   trailing `(EDT)`, a 1- or 2-digit day, a 4-or-more-digit year and optional
+ *   seconds. §4 obsolete syntax, which "MUST be accepted and parsed": comments
+ *   and white space between any tokens, and 2- or 3-digit years (00–49 → 20xx,
+ *   50–99 → 19xx, 3 digits → +1900).
+ * - **Zones.** A numeric `+hhmm`/`-hhmm` (minutes 00–59), or an obsolete
+ *   alphabetic zone: `UT`/`GMT` are `+0000`, and `EST`/`EDT`/`CST`/`CDT`/
+ *   `MST`/`MDT`/`PST`/`PDT` have the offsets §4.3 gives them. Military
+ *   one-letter zones and any other alphabetic zone are read as `-0000`, as
+ *   §4.3 says they SHOULD be; `J` is not a zone and returns `""`.
+ * - **`-0000` and `+0000` both become `+00:00`.** RFC 5322 §3.3 gives `-0000`
+ *   the meaning "no information about the local time zone"; a Temporal offset
+ *   cannot carry that distinction, so it is lost.
+ * - **The day-of-week must match the date.** RFC 5322 §3.3: "the day-of-week
+ *   (if included) MUST be the day implied by the date". A mismatch returns `""`.
  * - The resulting offset becomes the zoned string's time zone identifier
- *   (e.g. `-05:00`), since RFC 2822 carries no IANA zone name to recover.
+ *   (e.g. `-05:00`), since RFC 5322 carries no IANA zone name to recover.
+ *   An offset of 24 hours or more cannot be represented and returns `""`.
+ * - 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 strict current-syntax shape alone, test the exported `rfc2822DateTime` pattern.
+ * - **Compatibility:** before 1.16.0 a day-of-week that did not match the date was ignored.
+ *   Remove the day-of-week to parse such a string: the date alone decides the result.
  *
  * @param value RFC 5322 date-time string (e.g. "Fri, 15 Mar 2024 14:30:00 -0400")
  * @returns zoned ISO 8601 datetime string, or "" on invalid input
  *
  * @example parseRfc2822("Fri, 15 Mar 2024 14:30:00 -0400") // "2024-03-15T14:30:00-04:00[-04:00]"
  * @example parseRfc2822("5 Jan 2024 09:00:00 GMT") // "2024-01-05T09:00:00+00:00[+00:00]"
+ * @example parseRfc2822("fri,15 Mar 24 14:30 -0400 (EDT)") // "2024-03-15T14:30:00-04:00[-04:00]" (obsolete 2-digit year, comment)
+ * @example parseRfc2822("Fri, 15 Mar 2024 14:30:00 CEST") // "2024-03-15T14:30:00+00:00[+00:00]" (unknown zone → -0000)
+ * @example parseRfc2822("Fri, 15 Mar 2024 14:30:00 -0000") // "2024-03-15T14:30:00+00:00[+00:00]"
+ * @example parseRfc2822("Sat, 15 Mar 2024 14:30:00 -0400") // "" (15 Mar 2024 was a Friday)
+ * @example parseRfc2822("15 Mar 2024 14:30:00 -0400") // "2024-03-15T14:30:00-04:00[-04:00]" — the weekday removed
+ * @example parseRfc2822("Sat, 31 Feb 2024 14:30:00 -0400") // "" (impossible date)
  * @example parseRfc2822("not a date") // ""
  */
 export function parseRfc2822(value) {
     if (typeof value !== "string")
         return "";
-    const match = rfc2822DateTime.exec(value);
-    if (match === null)
+    const fields = readRfc5322DateTime(value);
+    if (fields === null)
         return "";
-    const [, , dayStr, monthName, yearStr, hourStr, minuteStr, secondStr, zone] = match;
-    const monthIndex = ENGLISH_MONTH_NAMES.indexOf(monthName);
-    if (monthIndex === -1)
-        return "";
-    const numericOffset = NAMED_ZONE_OFFSETS[zone] ?? zone;
-    const offset = `${numericOffset.slice(0, 3)}:${numericOffset.slice(3)}`;
     try {
         const plainDateTime = Temporal.PlainDateTime.from({
-            year: Number(yearStr),
-            month: monthIndex + 1,
-            day: Number(dayStr),
-            hour: Number(hourStr),
-            minute: Number(minuteStr),
-            second: secondStr === undefined ? 0 : Number(secondStr),
+            year: fields.year,
+            month: fields.month,
+            day: fields.day,
+            hour: fields.hour,
+            minute: fields.minute,
+            second: fields.second,
         }, { overflow: "reject" });
-        return plainDateTime.toZonedDateTime(offset).toString();
+        // "the day-of-week (if included) MUST be the day implied by the date"
+        if (fields.dayOfWeek !== undefined &&
+            fields.dayOfWeek !== plainDateTime.dayOfWeek) {
+            return "";
+        }
+        return plainDateTime.toZonedDateTime(fields.offset).toString();
     }
     catch {
         return "";

package/dist/zoned/parse/parseRfc3339.d.ts

@@ -8,6 +8,11 @@
  * - RFC 3339 carries no IANA zone name, so the parsed offset becomes the
  *   result's time zone identifier too (e.g. `Z` → `+00:00[+00:00]`) — the
  *   same fixed-offset-as-zone convention `parseRfc2822` uses.
+ * - **`Z` and `-00:00` become `+00:00`.** RFC 9557 §2.2 (updating RFC 3339
+ *   §4.3) gives `Z` and the older `-00:00` the meaning "the time in UTC is
+ *   known, but the offset to local time is unknown", unlike `+00:00`. A
+ *   Temporal offset cannot carry that distinction, so it is lost; the instant
+ *   is exact.
  * - Rejects GMT's own bracketed zoned strings (`...+00:00[UTC]`) — that
  *   annotation is not valid RFC 3339 input; use `Temporal.ZonedDateTime.from`
  *   / `isValidZonedDateTime` directly for GMT's native format instead.
@@ -17,6 +22,7 @@
  *
  * @example parseRfc3339("2024-03-15T14:30:00-04:00") // "2024-03-15T14:30:00-04:00[-04:00]"
  * @example parseRfc3339("2024-03-15T14:30:00Z") // "2024-03-15T14:30:00+00:00[+00:00]"
+ * @example parseRfc3339("2024-03-15T14:30:00-00:00") // "2024-03-15T14:30:00+00:00[+00:00]"
  * @example parseRfc3339("2024-03-15T14:30:00+00:00[UTC]") // "" (bracket annotation not valid RFC 3339)
  * @example parseRfc3339("not a date") // ""
  */

package/dist/zoned/parse/parseRfc3339.js

@@ -10,6 +10,11 @@ import { rfc3339DateTime } from "../../regex/index.js";
  * - RFC 3339 carries no IANA zone name, so the parsed offset becomes the
  *   result's time zone identifier too (e.g. `Z` → `+00:00[+00:00]`) — the
  *   same fixed-offset-as-zone convention `parseRfc2822` uses.
+ * - **`Z` and `-00:00` become `+00:00`.** RFC 9557 §2.2 (updating RFC 3339
+ *   §4.3) gives `Z` and the older `-00:00` the meaning "the time in UTC is
+ *   known, but the offset to local time is unknown", unlike `+00:00`. A
+ *   Temporal offset cannot carry that distinction, so it is lost; the instant
+ *   is exact.
  * - Rejects GMT's own bracketed zoned strings (`...+00:00[UTC]`) — that
  *   annotation is not valid RFC 3339 input; use `Temporal.ZonedDateTime.from`
  *   / `isValidZonedDateTime` directly for GMT's native format instead.
@@ -19,6 +24,7 @@ import { rfc3339DateTime } from "../../regex/index.js";
  *
  * @example parseRfc3339("2024-03-15T14:30:00-04:00") // "2024-03-15T14:30:00-04:00[-04:00]"
  * @example parseRfc3339("2024-03-15T14:30:00Z") // "2024-03-15T14:30:00+00:00[+00:00]"
+ * @example parseRfc3339("2024-03-15T14:30:00-00:00") // "2024-03-15T14:30:00+00:00[+00:00]"
  * @example parseRfc3339("2024-03-15T14:30:00+00:00[UTC]") // "" (bracket annotation not valid RFC 3339)
  * @example parseRfc3339("not a date") // ""
  */

package/dist/zoned/parse/parseSecondFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Return the second (0-59) from a zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function parseSecondFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime.second.toString().padStart(2, "0");
     }
     catch {

package/dist/zoned/parse/parseTimeFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Extract the plain time portion from an ISO 8601 zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function parseTimeFromZoned(value) {
         return "";
     }
     try {
-        const zonedDateTime = Temporal.ZonedDateTime.from(value);
+        const zonedDateTime = zonedDateTimeFrom(value);
         return zonedDateTime?.toPlainTime().toString();
     }
     catch {

package/dist/zoned/parse/parseTimeZoneFromZoned.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isValidZonedDateTime } from "../validate/index.js";
+import { zonedDateTimeFrom } from "../../internal/index.js";
 /**
  * Extract the IANA timeZone identifier from an ISO 8601 zoned datetime string.
  *
@@ -17,7 +17,7 @@ export function parseTimeZoneFromZoned(value) {
         return "";
     }
     try {
-        return Temporal.ZonedDateTime.from(value).timeZoneId ?? "";
+        return zonedDateTimeFrom(value).timeZoneId ?? "";
     }
     catch {
         return "";

package/dist/zoned/parse/parseUnitFromZoned.d.ts

@@ -1,6 +1,8 @@
+import type { Temporal } from "@js-temporal/polyfill";
 /**
  * Units supported by `parseUnitFromZoned` when extracting a value from a zoned
- * ISO string. Includes `timeZone` for reading the zone identifier.
+ * ISO string. Includes `timeZone` for reading the zone identifier. Each Temporal unit is also
+ * accepted in its plural form (`"months"`), as Temporal accepts.
  *
  * @remarks Members:
  *
@@ -15,27 +17,34 @@
  * | `minute` | Zero-padded 2. |
  * | `second` | Zero-padded 2. |
  * | `millisecond` | Zero-padded 3. |
- * | `nanosecond` | Zero-padded 3. |
+ * | `microsecond` | Zero-padded 3 (Temporal's 0–999 field). |
+ * | `nanosecond` | Zero-padded 3 (Temporal's 0–999 field). |
  * | `timeZone` | IANA timeZone identifier string. |
  *
  * @example
  * import { ZonedParseUnit } from "@northguild/gmt/zoned";
  * const u: ZonedParseUnit = "month";
  */
-export type ZonedParseUnit = "year" | "month" | "week" | "day" | "dayOfWeek" | "hour" | "minute" | "second" | "millisecond" | "nanosecond" | "timeZone";
+export type ZonedParseUnit = Temporal.SmallestUnit<"year" | "month" | "week" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"> | "dayOfWeek" | "timeZone";
 /**
  * Return the requested unit value from an ISO 8601 zoned datetime string.
  *
- * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "nanosecond", "timeZone".
+ * - Valid units: "year", "month", "week", "day", "dayOfWeek", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", "timeZone".
  * - Uses Temporal.ZonedDateTime.from to parse.
+ * - `unit` accepts the singular or plural name of a Temporal unit (`"hour"` or `"hours"`), as Temporal
+ *   does; `"dayOfWeek"` has no plural.
+ * - `weekStartsOn: "sunday"` numbers weeks by UTS #35 (week 1 holds 1 January, so late-December
+ *   days can be week 1); any value other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid input.
  *
  * @param value zoned ISO 8601 datetime string
  * @param unit unit to extract
- * @param options optional settings (e.g. weekStartsOn for week calculations)
+ * @param optionsArg optional settings (e.g. weekStartsOn for week calculations); a non-object value (such as `null`) is invalid
  * @returns string representation of the requested unit or "" when invalid
  *
  * @example parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "year") // "2024"
+ * @example parseUnitFromZoned("2024-02-29T12:34:56.789+00:00[UTC]", "milliseconds") // "789"
+ * @example parseUnitFromZoned("2024-12-31T12:00:00+00:00[UTC]", "week", { weekStartsOn: "sunday" }) // "1"
  * @example parseUnitFromZoned("invalid", "year") // ""
  */
 export declare function parseUnitFromZoned(value: string, unit: ZonedParseUnit, optionsArg?: {