@northguild/gmt 1.17.0 → 1.19.0

package/dist/plain/parse/parseDateTimeWithPattern.js

@@ -1,5 +1,6 @@
+// fallow-ignore-file code-duplication -- sibling of parseDateWithPattern; each keeps its own guard, options check and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal/index.js";
+import { DATE_TIME_PATTERN_FIELDS, isOptionsArgument, parseValueWithPattern, } from "../../internal/index.js";
 /**
  * Parse a datetime string against a caller-supplied token pattern (e.g.
  * `"MM/dd/yyyy HH:mm:ss"`, `"dd-MMM-yyyy h:mm a"`) and return it as an
@@ -9,9 +10,8 @@ import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal
  *   producer format — a CSV column, a legacy API field, a partially-typed
  *   form value — not for generating locale-correct output. For display,
  *   use `formatDateTime`/`formatDateToParts`, which order fields per
- *   locale instead of hard-coding a field order (see roadmap Decision 1
- *   — a token *formatter*, the inverse of this function, is deliberately
- *   out of scope for GMT).
+ *   locale instead of hard-coding a field order (a token *formatter*,
+ *   the inverse of this function, is deliberately out of scope for GMT).
  * - Accepts the full combined date + time token set (unlike
  *   `parseDateWithPattern`/`parseTimeWithPattern`, which each reject the
  *   other's tokens).
@@ -20,7 +20,7 @@ import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal
  * | Token | Field | Width | Range | Notes |
  * |---|---|---|---|---|
  * | `yyyy` | year | 4 digits | 0000–9999 | |
- * | `yy` | year | 2 digits | 00–99 | Pivot: 00–68 → 2000–2068, 69–99 → 1969–1999 (fixed rule) |
+ * | `yy` | year | 2 digits | 00–99 | Needs `options.yearWindow`; returns `""` without it |
  * | `MM` | month | 2 digits | 01–12 | |
  * | `M` | month | 1-2 digits | 1–12 | |
  * | `MMMM` | month name (long) | locale | — | `getLocaleMonthNames(locale, "long")` |
@@ -42,10 +42,13 @@ import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal
  * | `GGGG` | era name (long) | locale | — | BCE label ⇒ final year = 1 − parsed year |
  * | `GG` | era name (short) | locale | — | same resolution |
  *
- * - Text in `'single quotes'` is a literal; a doubled `''` inside a
- *   quoted segment is a literal `'`. Any other character (`/ - , space
- *   :`, literal digits, etc.) outside a quote/letter-run is automatically
- *   a literal — no explicit quoting required.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"yyyy''MM"` reads `"2024'03"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`/ - , space :`,
+ *   digits and so on) is a literal with no quoting.
  * - `MMMM`/`MMM`/`EEEE`/`EEE`/`a`/`GGGG`/`GG` are locale-aware. If
  *   `locale` is omitted and the pattern uses any of them, GMT defaults
  *   to `"en-US"` rather than returning `""` for every caller who didn't
@@ -73,25 +76,40 @@ import { DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, } from "../../internal
  * - Fields absent from `pattern` default the way `Temporal.PlainDateTime.from`
  *   defaults an omitted field (time fields default to `0`; `year`/`month`/`day`
  *   are still required for a valid result).
+ * - A `yy` token needs the caller's hundred-year window,
+ *   `options.yearWindow`: no standard says which century a two-digit
+ *   year belongs to, and a cut-off built into a library is right today
+ *   and wrong later. Without a valid window a `yy` pattern returns `""`.
+ *   A pattern with no `yy` never reads the option, so a `"rolling"`
+ *   window reads no clock for it. A two-digit year is a legacy form; a
+ *   four-digit year is the one to ask a data source for.
  *
  * @param value The string to decode (e.g. "03/15/2024 14:30:00")
  * @param pattern The token pattern describing `value`'s shape (e.g. "MM/dd/yyyy HH:mm:ss")
  * @param locale Optional BCP 47 locale tag, or a preference list of tags, for name-based tokens (default "en-US")
+ * @param options The hundred-year window a `yy` token resolves in
  * @returns ISO `PlainDateTime` string, or "" on no match, malformed pattern, or invalid input
  *
  * @example parseDateTimeWithPattern("03/15/2024 14:30:00", "MM/dd/yyyy HH:mm:ss") // "2024-03-15T14:30:00"
  * @example parseDateTimeWithPattern("15-Mar-2024 02:30 PM", "dd-MMM-yyyy hh:mm a") // "2024-03-15T14:30:00"
+ * @example parseDateTimeWithPattern("Mar 15, '24 at 14:30", "MMM d, ''yy 'at' HH:mm", undefined, { yearWindow: 2000 }) // "2024-03-15T14:30:00" ('' is one literal quote)
+ * @example parseDateTimeWithPattern("99-03-15 14:30", "yy-MM-dd HH:mm", undefined, { yearWindow: 1950 }) // "1999-03-15T14:30:00" (1950–2049 window)
+ * @example parseDateTimeWithPattern("24-03-15 14:30", "yy-MM-dd HH:mm", undefined, { yearWindow: "rolling" }) // "2024-03-15T14:30:00" (while the current UTC year is 1975–2074)
+ * @example parseDateTimeWithPattern("24-03-15 14:30", "yy-MM-dd HH:mm") // "" (yy with no window)
+ * @example parseDateTimeWithPattern("03/15/2024 14:30:00", "MM/dd/yyyy HH:mm:ss", undefined, { yearWindow: 2000 }) // "2024-03-15T14:30:00" (yyyy ignores the window)
  * @example parseDateTimeWithPattern("02/31/2024 14:30:00", "MM/dd/yyyy HH:mm:ss") // "" (shape-valid, not a real date)
  * @example parseDateTimeWithPattern("not a date", "MM/dd/yyyy HH:mm:ss") // ""
  * @example parseDateTimeWithPattern("19 mai 2024 10:20", "d MMMM yyyy HH:mm", ["fr-FR", "en-US"]) // "2024-05-19T10:20:00"
  */
-export function parseDateTimeWithPattern(value, pattern, locale) {
+export function parseDateTimeWithPattern(value, pattern, locale, options) {
     try {
         if (typeof value !== "string")
             return "";
         if (typeof pattern !== "string")
             return "";
-        const fields = parseValueWithPattern(value, pattern, locale, DATE_TIME_PATTERN_FIELDS);
+        if (!isOptionsArgument(options))
+            return "";
+        const fields = parseValueWithPattern(value, pattern, locale, DATE_TIME_PATTERN_FIELDS, options);
         if (fields === null)
             return "";
         try {

package/dist/plain/parse/parseDateWithPattern.d.ts

@@ -1,3 +1,4 @@
+import type { TwoDigitYearOptions } from "../../types/two-digit-year.js";
 /**
  * Parse a date string against a caller-supplied token pattern (e.g.
  * `"MM/dd/yyyy"`, `"dd-MMM-yyyy"`) and return it as an ISO `PlainDate`
@@ -7,9 +8,8 @@
  *   producer format — a CSV column, a legacy API field, a partially-typed
  *   form value — not for generating locale-correct output. For display,
  *   use `formatDate`/`formatDateToParts`, which order fields per locale
- *   instead of hard-coding a field order (see roadmap Decision 1 — a
- *   token *formatter*, the inverse of this function, is deliberately out
- *   of scope for GMT).
+ *   instead of hard-coding a field order (a token *formatter*, the
+ *   inverse of this function, is deliberately out of scope for GMT).
  * - `pattern` accepts only date-shaped tokens. A pattern containing a
  *   time-only token (`H h m s S a`) is malformed for this function and
  *   returns `""` — use `parseDateTimeWithPattern` for combined input.
@@ -18,7 +18,7 @@
  * | Token | Field | Width | Range | Notes |
  * |---|---|---|---|---|
  * | `yyyy` | year | 4 digits | 0000–9999 | |
- * | `yy` | year | 2 digits | 00–99 | Pivot: 00–68 → 2000–2068, 69–99 → 1969–1999 (fixed rule) |
+ * | `yy` | year | 2 digits | 00–99 | Needs `options.yearWindow`; returns `""` without it |
  * | `MM` | month | 2 digits | 01–12 | |
  * | `M` | month | 1-2 digits | 1–12 | |
  * | `MMMM` | month name (long) | locale | — | `getLocaleMonthNames(locale, "long")` |
@@ -30,10 +30,13 @@
  * | `GGGG` | era name (long) | locale | — | BCE label ⇒ final year = 1 − parsed year |
  * | `GG` | era name (short) | locale | — | same resolution |
  *
- * - Text in `'single quotes'` is a literal; a doubled `''` inside a
- *   quoted segment is a literal `'`. Any other character (`/ - , space`,
- *   literal digits, etc.) outside a quote/letter-run is automatically a
- *   literal — no explicit quoting required.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"yyyy''MM"` reads `"2024'03"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`/ - , space`,
+ *   digits and so on) is a literal with no quoting.
  * - `MMMM`/`MMM`/`EEEE`/`EEE`/`GGGG`/`GG` are locale-aware. If `locale`
  *   is omitted and the pattern uses any of them, GMT defaults to
  *   `"en-US"` rather than returning `""` for every caller who didn't
@@ -54,16 +57,30 @@
  *   overflow: "reject" })`, so `"02/31/2024"` against `"MM/dd/yyyy"`
  *   still returns `""` — the regex only proves the shape, Temporal
  *   proves the date is real.
+ * - A `yy` token needs the caller's hundred-year window,
+ *   `options.yearWindow`: no standard says which century a two-digit
+ *   year belongs to, and a cut-off built into a library is right today
+ *   and wrong later. Without a valid window a `yy` pattern returns `""`.
+ *   A pattern with no `yy` never reads the option, so a `"rolling"`
+ *   window reads no clock for it. A two-digit year is a legacy form; a
+ *   four-digit year is the one to ask a data source for.
  *
  * @param value The string to decode (e.g. "03/15/2024")
  * @param pattern The token pattern describing `value`'s shape (e.g. "MM/dd/yyyy")
  * @param locale Optional BCP 47 locale tag, or a preference list of tags, for name-based tokens (default "en-US")
+ * @param options The hundred-year window a `yy` token resolves in
  * @returns ISO `PlainDate` string, or "" on no match, malformed pattern, or invalid input
  *
  * @example parseDateWithPattern("03/15/2024", "MM/dd/yyyy") // "2024-03-15"
  * @example parseDateWithPattern("15-Mar-2024", "dd-MMM-yyyy") // "2024-03-15"
+ * @example parseDateWithPattern("Mar 15, '24", "MMM d, ''yy", undefined, { yearWindow: 2000 }) // "2024-03-15" ('' is one literal quote)
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy", undefined, { yearWindow: 1950 }) // "2024-03-15" (1950–2049 window)
+ * @example parseDateWithPattern("03/15/99", "MM/dd/yy", undefined, { yearWindow: 1950 }) // "1999-03-15"
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy", undefined, { yearWindow: "rolling" }) // "2024-03-15" (while the current UTC year is 1975–2074)
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy") // "" (yy with no window)
+ * @example parseDateWithPattern("03/15/2024", "MM/dd/yyyy", undefined, { yearWindow: 2000 }) // "2024-03-15" (yyyy ignores the window)
  * @example parseDateWithPattern("02/31/2024", "MM/dd/yyyy") // "" (shape-valid, not a real date)
  * @example parseDateWithPattern("14:30", "HH:mm") // "" (time token in a date-only pattern)
  * @example parseDateWithPattern("19 mai 2024", "d MMMM yyyy", ["fr-FR", "en-US"]) // "2024-05-19"
  */
-export declare function parseDateWithPattern(value: string, pattern: string, locale?: string | string[]): string;
+export declare function parseDateWithPattern(value: string, pattern: string, locale?: string | string[], options?: TwoDigitYearOptions): string;

package/dist/plain/parse/parseDateWithPattern.js

@@ -1,5 +1,6 @@
+// fallow-ignore-file code-duplication -- sibling of parseDateTimeWithPattern; each keeps its own guard, options check and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index.js";
+import { DATE_PATTERN_FIELDS, isOptionsArgument, parseValueWithPattern, } from "../../internal/index.js";
 /**
  * Parse a date string against a caller-supplied token pattern (e.g.
  * `"MM/dd/yyyy"`, `"dd-MMM-yyyy"`) and return it as an ISO `PlainDate`
@@ -9,9 +10,8 @@ import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index
  *   producer format — a CSV column, a legacy API field, a partially-typed
  *   form value — not for generating locale-correct output. For display,
  *   use `formatDate`/`formatDateToParts`, which order fields per locale
- *   instead of hard-coding a field order (see roadmap Decision 1 — a
- *   token *formatter*, the inverse of this function, is deliberately out
- *   of scope for GMT).
+ *   instead of hard-coding a field order (a token *formatter*, the
+ *   inverse of this function, is deliberately out of scope for GMT).
  * - `pattern` accepts only date-shaped tokens. A pattern containing a
  *   time-only token (`H h m s S a`) is malformed for this function and
  *   returns `""` — use `parseDateTimeWithPattern` for combined input.
@@ -20,7 +20,7 @@ import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index
  * | Token | Field | Width | Range | Notes |
  * |---|---|---|---|---|
  * | `yyyy` | year | 4 digits | 0000–9999 | |
- * | `yy` | year | 2 digits | 00–99 | Pivot: 00–68 → 2000–2068, 69–99 → 1969–1999 (fixed rule) |
+ * | `yy` | year | 2 digits | 00–99 | Needs `options.yearWindow`; returns `""` without it |
  * | `MM` | month | 2 digits | 01–12 | |
  * | `M` | month | 1-2 digits | 1–12 | |
  * | `MMMM` | month name (long) | locale | — | `getLocaleMonthNames(locale, "long")` |
@@ -32,10 +32,13 @@ import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index
  * | `GGGG` | era name (long) | locale | — | BCE label ⇒ final year = 1 − parsed year |
  * | `GG` | era name (short) | locale | — | same resolution |
  *
- * - Text in `'single quotes'` is a literal; a doubled `''` inside a
- *   quoted segment is a literal `'`. Any other character (`/ - , space`,
- *   literal digits, etc.) outside a quote/letter-run is automatically a
- *   literal — no explicit quoting required.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"yyyy''MM"` reads `"2024'03"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`/ - , space`,
+ *   digits and so on) is a literal with no quoting.
  * - `MMMM`/`MMM`/`EEEE`/`EEE`/`GGGG`/`GG` are locale-aware. If `locale`
  *   is omitted and the pattern uses any of them, GMT defaults to
  *   `"en-US"` rather than returning `""` for every caller who didn't
@@ -56,25 +59,41 @@ import { DATE_PATTERN_FIELDS, parseValueWithPattern } from "../../internal/index
  *   overflow: "reject" })`, so `"02/31/2024"` against `"MM/dd/yyyy"`
  *   still returns `""` — the regex only proves the shape, Temporal
  *   proves the date is real.
+ * - A `yy` token needs the caller's hundred-year window,
+ *   `options.yearWindow`: no standard says which century a two-digit
+ *   year belongs to, and a cut-off built into a library is right today
+ *   and wrong later. Without a valid window a `yy` pattern returns `""`.
+ *   A pattern with no `yy` never reads the option, so a `"rolling"`
+ *   window reads no clock for it. A two-digit year is a legacy form; a
+ *   four-digit year is the one to ask a data source for.
  *
  * @param value The string to decode (e.g. "03/15/2024")
  * @param pattern The token pattern describing `value`'s shape (e.g. "MM/dd/yyyy")
  * @param locale Optional BCP 47 locale tag, or a preference list of tags, for name-based tokens (default "en-US")
+ * @param options The hundred-year window a `yy` token resolves in
  * @returns ISO `PlainDate` string, or "" on no match, malformed pattern, or invalid input
  *
  * @example parseDateWithPattern("03/15/2024", "MM/dd/yyyy") // "2024-03-15"
  * @example parseDateWithPattern("15-Mar-2024", "dd-MMM-yyyy") // "2024-03-15"
+ * @example parseDateWithPattern("Mar 15, '24", "MMM d, ''yy", undefined, { yearWindow: 2000 }) // "2024-03-15" ('' is one literal quote)
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy", undefined, { yearWindow: 1950 }) // "2024-03-15" (1950–2049 window)
+ * @example parseDateWithPattern("03/15/99", "MM/dd/yy", undefined, { yearWindow: 1950 }) // "1999-03-15"
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy", undefined, { yearWindow: "rolling" }) // "2024-03-15" (while the current UTC year is 1975–2074)
+ * @example parseDateWithPattern("03/15/24", "MM/dd/yy") // "" (yy with no window)
+ * @example parseDateWithPattern("03/15/2024", "MM/dd/yyyy", undefined, { yearWindow: 2000 }) // "2024-03-15" (yyyy ignores the window)
  * @example parseDateWithPattern("02/31/2024", "MM/dd/yyyy") // "" (shape-valid, not a real date)
  * @example parseDateWithPattern("14:30", "HH:mm") // "" (time token in a date-only pattern)
  * @example parseDateWithPattern("19 mai 2024", "d MMMM yyyy", ["fr-FR", "en-US"]) // "2024-05-19"
  */
-export function parseDateWithPattern(value, pattern, locale) {
+export function parseDateWithPattern(value, pattern, locale, options) {
     try {
         if (typeof value !== "string")
             return "";
         if (typeof pattern !== "string")
             return "";
-        const fields = parseValueWithPattern(value, pattern, locale, DATE_PATTERN_FIELDS);
+        if (!isOptionsArgument(options))
+            return "";
+        const fields = parseValueWithPattern(value, pattern, locale, DATE_PATTERN_FIELDS, options);
         if (fields === null)
             return "";
         try {

package/dist/plain/parse/{parseSql.d.ts → parseSqlDateTime.d.ts}

@@ -8,7 +8,7 @@
  *   two-digit month, day, hour, minute and second (seconds are required), and an optional `.`
  *   followed by up to 9 fraction digits.
  * - **Plain only.** SQL's offset-carrying `TIMESTAMP WITH TIME ZONE` literal is out of scope; see
- *   `formatSql`'s JSDoc.
+ *   `formatSqlDateTime`'s JSDoc.
  * - The fraction is written as `Temporal.PlainDateTime#toString` writes it: trailing zeros are
  *   dropped (`.500` → `.5`, `.000` → none), and a `.` with no digits is dropped. `Temporal.PlainDateTime.from`
  *   proves the value is a real calendar date and time.
@@ -16,11 +16,11 @@
  * @param value SQL timestamp literal (e.g. "2024-03-15 14:30:00")
  * @returns plain ISO 8601 datetime string, or "" on invalid input
  *
- * @example parseSql("2024-03-15 14:30:00") // "2024-03-15T14:30:00"
- * @example parseSql("2024-03-15 14:30:00.5") // "2024-03-15T14:30:00.5"
- * @example parseSql("2024-03-15 14:30") // "" (seconds are required)
- * @example parseSql("0000-01-01 00:00:00") // "" (year outside 0001–9999)
- * @example parseSql("2024-03-15T14:30:00") // "" (wrong separator)
- * @example parseSql("not a date") // ""
+ * @example parseSqlDateTime("2024-03-15 14:30:00") // "2024-03-15T14:30:00"
+ * @example parseSqlDateTime("2024-03-15 14:30:00.5") // "2024-03-15T14:30:00.5"
+ * @example parseSqlDateTime("2024-03-15 14:30") // "" (seconds are required)
+ * @example parseSqlDateTime("0000-01-01 00:00:00") // "" (year outside 0001–9999)
+ * @example parseSqlDateTime("2024-03-15T14:30:00") // "" (wrong separator)
+ * @example parseSqlDateTime("not a date") // ""
  */
-export declare function parseSql(value: string): string;
+export declare function parseSqlDateTime(value: string): string;

package/dist/plain/parse/{parseSql.js → parseSqlDateTime.js}

@@ -10,7 +10,7 @@ import { sqlDateTime } from "../../regex/index.js";
  *   two-digit month, day, hour, minute and second (seconds are required), and an optional `.`
  *   followed by up to 9 fraction digits.
  * - **Plain only.** SQL's offset-carrying `TIMESTAMP WITH TIME ZONE` literal is out of scope; see
- *   `formatSql`'s JSDoc.
+ *   `formatSqlDateTime`'s JSDoc.
  * - The fraction is written as `Temporal.PlainDateTime#toString` writes it: trailing zeros are
  *   dropped (`.500` → `.5`, `.000` → none), and a `.` with no digits is dropped. `Temporal.PlainDateTime.from`
  *   proves the value is a real calendar date and time.
@@ -18,14 +18,14 @@ import { sqlDateTime } from "../../regex/index.js";
  * @param value SQL timestamp literal (e.g. "2024-03-15 14:30:00")
  * @returns plain ISO 8601 datetime string, or "" on invalid input
  *
- * @example parseSql("2024-03-15 14:30:00") // "2024-03-15T14:30:00"
- * @example parseSql("2024-03-15 14:30:00.5") // "2024-03-15T14:30:00.5"
- * @example parseSql("2024-03-15 14:30") // "" (seconds are required)
- * @example parseSql("0000-01-01 00:00:00") // "" (year outside 0001–9999)
- * @example parseSql("2024-03-15T14:30:00") // "" (wrong separator)
- * @example parseSql("not a date") // ""
+ * @example parseSqlDateTime("2024-03-15 14:30:00") // "2024-03-15T14:30:00"
+ * @example parseSqlDateTime("2024-03-15 14:30:00.5") // "2024-03-15T14:30:00.5"
+ * @example parseSqlDateTime("2024-03-15 14:30") // "" (seconds are required)
+ * @example parseSqlDateTime("0000-01-01 00:00:00") // "" (year outside 0001–9999)
+ * @example parseSqlDateTime("2024-03-15T14:30:00") // "" (wrong separator)
+ * @example parseSqlDateTime("not a date") // ""
  */
-export function parseSql(value) {
+export function parseSqlDateTime(value) {
     if (typeof value !== "string")
         return "";
     if (!sqlDateTime.test(value))

package/dist/plain/parse/parseTimeWithPattern.d.ts

@@ -6,9 +6,8 @@
  *   producer format — a CSV column, a legacy API field, a partially-typed
  *   form value — not for generating locale-correct output. For display,
  *   use `formatTime`/`formatDateToParts`, which order fields per locale
- *   instead of hard-coding a field order (see roadmap Decision 1 — a
- *   token *formatter*, the inverse of this function, is deliberately out
- *   of scope for GMT).
+ *   instead of hard-coding a field order (a token *formatter*, the
+ *   inverse of this function, is deliberately out of scope for GMT).
  * - `pattern` accepts only time-shaped tokens. A pattern containing a
  *   date-only token (`y M d E G`) is malformed for this function and
  *   returns `""` — use `parseDateTimeWithPattern` for combined input.
@@ -27,10 +26,13 @@
  * | `SSS` | millisecond | 3 digits | 000–999 | |
  * | `a` | meridiem | locale | — | `getLocaleMeridiems(locale)` → `[AM-label, PM-label]` |
  *
- * - Text in `'single quotes'` is a literal; a doubled `''` inside a
- *   quoted segment is a literal `'`. Any other character (`: , space`,
- *   literal digits, etc.) outside a quote/letter-run is automatically a
- *   literal — no explicit quoting required.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"HH''mm"` reads `"14'30"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`: , space`,
+ *   digits and so on) is a literal with no quoting.
  * - `a` is locale-aware. If `locale` is omitted and the pattern uses
  *   `a`, GMT defaults to `"en-US"` rather than returning `""` for every
  *   caller who didn't have another locale in mind.
@@ -51,6 +53,7 @@
  *
  * @example parseTimeWithPattern("14:30:45", "HH:mm:ss") // "14:30:45"
  * @example parseTimeWithPattern("02:30:45 PM", "hh:mm:ss a") // "14:30:45"
+ * @example parseTimeWithPattern("2 o'clock PM", "h 'o''clock' a") // "14:00:00" ('' is one literal quote)
  * @example parseTimeWithPattern("25:00", "HH:mm") // "" (shape-valid, not a real time)
  * @example parseTimeWithPattern("2024-03-15", "yyyy-MM-dd") // "" (date token in a time-only pattern)
  * @example parseTimeWithPattern("午後 10:20", "a h:mm", ["ja-JP", "en-US"]) // "22:20:00"

package/dist/plain/parse/parseTimeWithPattern.js

@@ -8,9 +8,8 @@ import { parseValueWithPattern, TIME_PATTERN_FIELDS } from "../../internal/index
  *   producer format — a CSV column, a legacy API field, a partially-typed
  *   form value — not for generating locale-correct output. For display,
  *   use `formatTime`/`formatDateToParts`, which order fields per locale
- *   instead of hard-coding a field order (see roadmap Decision 1 — a
- *   token *formatter*, the inverse of this function, is deliberately out
- *   of scope for GMT).
+ *   instead of hard-coding a field order (a token *formatter*, the
+ *   inverse of this function, is deliberately out of scope for GMT).
  * - `pattern` accepts only time-shaped tokens. A pattern containing a
  *   date-only token (`y M d E G`) is malformed for this function and
  *   returns `""` — use `parseDateTimeWithPattern` for combined input.
@@ -29,10 +28,13 @@ import { parseValueWithPattern, TIME_PATTERN_FIELDS } from "../../internal/index
  * | `SSS` | millisecond | 3 digits | 000–999 | |
  * | `a` | meridiem | locale | — | `getLocaleMeridiems(locale)` → `[AM-label, PM-label]` |
  *
- * - Text in `'single quotes'` is a literal; a doubled `''` inside a
- *   quoted segment is a literal `'`. Any other character (`: , space`,
- *   literal digits, etc.) outside a quote/letter-run is automatically a
- *   literal — no explicit quoting required.
+ * - Literal text follows the Unicode UTS #35 date format pattern rules.
+ *   Text in `'single quotes'` is a literal, letters included. Two
+ *   adjacent quotes `''` are one literal `'`, inside or outside quoted
+ *   text: `"HH''mm"` reads `"14'30"`, and `"'o''clock'"` reads
+ *   `"o'clock"`. A quote that never closes makes the pattern malformed
+ *   (`""`). Any other character that is not a letter (`: , space`,
+ *   digits and so on) is a literal with no quoting.
  * - `a` is locale-aware. If `locale` is omitted and the pattern uses
  *   `a`, GMT defaults to `"en-US"` rather than returning `""` for every
  *   caller who didn't have another locale in mind.
@@ -53,6 +55,7 @@ import { parseValueWithPattern, TIME_PATTERN_FIELDS } from "../../internal/index
  *
  * @example parseTimeWithPattern("14:30:45", "HH:mm:ss") // "14:30:45"
  * @example parseTimeWithPattern("02:30:45 PM", "hh:mm:ss a") // "14:30:45"
+ * @example parseTimeWithPattern("2 o'clock PM", "h 'o''clock' a") // "14:00:00" ('' is one literal quote)
  * @example parseTimeWithPattern("25:00", "HH:mm") // "" (shape-valid, not a real time)
  * @example parseTimeWithPattern("2024-03-15", "yyyy-MM-dd") // "" (date token in a time-only pattern)
  * @example parseTimeWithPattern("午後 10:20", "a h:mm", ["ja-JP", "en-US"]) // "22:20:00"
@@ -63,6 +66,7 @@ export function parseTimeWithPattern(value, pattern, locale) {
             return "";
         if (typeof pattern !== "string")
             return "";
+        // A time pattern has no year token, so no two-digit-year window applies.
         const fields = parseValueWithPattern(value, pattern, locale, TIME_PATTERN_FIELDS);
         if (fields === null)
             return "";

package/dist/plain/parse/parseUnitFromDate.d.ts

@@ -6,16 +6,19 @@ import { Temporal } from "@js-temporal/polyfill";
  * - Returns zero-padded string for month and day.
  * - `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 "".
+ * - `optionsArg` must be an object or omitted: `null` or any other primitive returns "", as
+ *   Temporal's GetOptionsObject rejects it.
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value ISO PlainDate string
  * @param unit unit to extract from the date
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations; a non-object value (such as `null`) is invalid
+ * @param optionsArg How weeks are numbered
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDate("2024-03-15", "year") // "2024"
+ * @example parseUnitFromDate("0005-06-01", "year") // "0005"
  * @example parseUnitFromDate("2024-03-15", "month") // "03"
  * @example parseUnitFromDate("2024-03-15", "day") // "15"
  * @example parseUnitFromDate("2024-03-15", "week") // "11"
@@ -26,5 +29,13 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example parseUnitFromDate("2024-01-01", "week", { weekStartsOn: "sunday" }) // "1"
  */
 export declare function parseUnitFromDate(value: string, unit: Temporal.SmallestUnit<"year" | "month" | "day" | "week"> | "dayOfWeek", optionsArg?: {
+    /**
+     * The first day of the week, which sets how the `"week"` unit is numbered. `"monday"` gives the
+     * ISO 8601 week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS
+     * #35 week number with a Sunday first day and one minimal day, where week 1 holds 1 January.
+     * Any other value returns `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/plain/parse/parseUnitFromDate.js

@@ -4,6 +4,7 @@ import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../calculate/getWeekNumber.js";
 import { isValidDate } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Return a specific date unit extracted from a PlainDate string.
  *
@@ -11,16 +12,19 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Returns zero-padded string for month and day.
  * - `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 "".
+ * - `optionsArg` must be an object or omitted: `null` or any other primitive returns "", as
+ *   Temporal's GetOptionsObject rejects it.
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value ISO PlainDate string
  * @param unit unit to extract from the date
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations; a non-object value (such as `null`) is invalid
+ * @param optionsArg How weeks are numbered
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDate("2024-03-15", "year") // "2024"
+ * @example parseUnitFromDate("0005-06-01", "year") // "0005"
  * @example parseUnitFromDate("2024-03-15", "month") // "03"
  * @example parseUnitFromDate("2024-03-15", "day") // "15"
  * @example parseUnitFromDate("2024-03-15", "week") // "11"
@@ -44,7 +48,7 @@ export function parseUnitFromDate(value, unit, optionsArg) {
             const date = Temporal.PlainDate.from(value);
             switch (resolveDateTimeUnit(unit)) {
                 case "year":
-                    return date.year.toString();
+                    return isoYearString(date.year);
                 case "month":
                     return date.month.toString().padStart(2, "0");
                 case "day":

package/dist/plain/parse/parseUnitFromDateTime.d.ts

@@ -8,16 +8,19 @@ import { Temporal } from "@js-temporal/polyfill";
  * - Returns zero-padded string for most units.
  * - `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 "".
+ * - `optionsArg` must be an object or omitted: `null` or any other primitive returns "", as
+ *   Temporal's GetOptionsObject rejects it.
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value ISO PlainDateTime string
  * @param unit unit to extract from the datetime
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations; a non-object value (such as `null`) is invalid
+ * @param optionsArg How weeks are numbered
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "year") // "2024"
+ * @example parseUnitFromDateTime("0005-06-01T12:30:00", "year") // "0005"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "week") // "11"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "hour") // "14"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "millisecond") // "123"
@@ -26,5 +29,13 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example parseUnitFromDateTime("2024-01-01T00:00:00", "week", { weekStartsOn: "sunday" }) // "1"
  */
 export declare function parseUnitFromDateTime(value: string, unit: Temporal.SmallestUnit<"year" | "month" | "day" | "week" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"> | "dayOfWeek", optionsArg?: {
+    /**
+     * The first day of the week, which sets how the `"week"` unit is numbered. `"monday"` gives the
+     * ISO 8601 week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS
+     * #35 week number with a Sunday first day and one minimal day, where week 1 holds 1 January.
+     * Any other value returns `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/plain/parse/parseUnitFromDateTime.js

@@ -5,6 +5,7 @@ import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { getWeekNumber } from "../calculate/getWeekNumber.js";
 import { isValidDateTime } from "../validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { isoYearString } from "../../internal/isoYearString.js";
 /**
  * Return a specific unit extracted from a PlainDateTime string.
  *
@@ -14,16 +15,19 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Returns zero-padded string for most units.
  * - `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 "".
+ * - `optionsArg` must be an object or omitted: `null` or any other primitive returns "", as
+ *   Temporal's GetOptionsObject rejects it.
  * - Returns "" for invalid input.
+ * - The `"year"` unit is written as Temporal writes a year: four digits (`"2024"`, `"0005"`), or a
+ *   sign and six digits outside 0000–9999 (`"+010000"`, `"-000005"`).
  *
  * @param value ISO PlainDateTime string
  * @param unit unit to extract from the datetime
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations; a non-object value (such as `null`) is invalid
+ * @param optionsArg How weeks are numbered
  * @returns string representation of the requested unit or "" on invalid input
  *
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "year") // "2024"
+ * @example parseUnitFromDateTime("0005-06-01T12:30:00", "year") // "0005"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "week") // "11"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "hour") // "14"
  * @example parseUnitFromDateTime("2024-03-15T14:30:45.123", "millisecond") // "123"
@@ -45,7 +49,7 @@ export function parseUnitFromDateTime(value, unit, optionsArg) {
             const dateTime = Temporal.PlainDateTime.from(value);
             switch (resolveDateTimeUnit(unit)) {
                 case "year":
-                    return dateTime.year.toString();
+                    return isoYearString(dateTime.year);
                 case "month":
                     return dateTime.month.toString().padStart(2, "0");
                 case "day":

package/dist/plain/parse/parseWeekFromDate.d.ts

@@ -1,15 +1,11 @@
 /**
  * Return the week number for a given ISO 8601 date string.
  *
- * - By default uses ISO weeks (Monday-based).
- * - `weekStartsOn: "sunday"` is the UTS #35 week of the week-year with a Sunday first day and
- *   minimal days 1 (week 1 holds 1 January, so late-December days can be week 1), while `"monday"`
- *   is the ISO 8601 week of the week-year; both are 1–53 — see `getWeekNumber`.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
+ * - The week is the week of the week-year, 1–53, under either numbering — see `getWeekNumber`.
  * - Returns null for invalid input.
  *
  * @param value ISO date string
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday") for week calculations
+ * @param optionsArg How weeks are numbered
  * @returns Week number (1-53) or null on invalid input
  *
  * @example parseWeekFromDate("2024-01-01") // 1
@@ -20,5 +16,13 @@
  * @example parseWeekFromDate("2024-12-31", { weekStartsOn: "sunday" }) // 1 (its Sunday-first week holds 1 January 2025)
  */
 export declare function parseWeekFromDate(value: string, optionsArg?: {
+    /**
+     * The first day of the week, which sets how the week is numbered. `"monday"` gives the ISO 8601
+     * week number, where week 1 holds the year's first Thursday; `"sunday"` gives the UTS #35 week
+     * number with a Sunday first day and one minimal day, where week 1 holds 1 January. Any other
+     * value returns `null`.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): number | null;