parseDateWithPattern

Signature

parseDateWithPattern(value: string, pattern: string, locale?: string | string[], options?: TwoDigitYearOptions): string

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 string.

Decoding, not display. This is for consuming a known, fixed 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 (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. ### Token table

Token	Field	Width	Range	Notes
`yyyy`	year	4 digits	0000–9999
`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")`
`MMM`	month name (short)	locale	—	`getLocaleMonthNames(locale, "short")`
`dd`	day	2 digits	01–31
`d`	day	1-2 digits	1–31
`EEEE`	weekday name (long)	locale	—	consumed, NOT cross-validated against the date (see below)
`EEE`	weekday name (short)	locale	—	same
`GGGG`	era name (long)	locale	—	BCE label ⇒ final year = 1 − parsed year
`GG`	era name (short)	locale	—	same resolution

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 have another locale in mind — pass locale explicitly for others.
EEEE/EEE are matched against the locale’s weekday names but the result is not cross-checked against the constructed date — e.g. "Monday, 2024-03-15" parses successfully against "EEEE, yyyy-MM-dd" even though 2024-03-15 is actually a Friday. This is a deliberate scope limit (no second weekday-index-to-ISO- dayOfWeek mapping layer).
Adjacent variable-width numeric tokens with no literal separator (e.g. "Mdyyyy") are inherently ambiguous: each becomes a greedy \d{1,2}/etc. in sequence, so the split between fields depends on regex backtracking, not on any documented rule. Prefer zero-padded tokens (MM, dd) or an explicit separator for reliable parsing.
A shape-valid match does not by itself prove a real date: extracted fields are always handed to Temporal.PlainDate.from(fields, { 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.

Parameters

Parameter	Type	Description
`value`	`string`	The string to decode (e.g. “03/15/2024”)
`pattern`	`string`	The token pattern describing `value`’s shape (e.g. “MM/dd/yyyy”)
`locale`	`string` \| `string[]`	Optional BCP 47 locale tag, or a preference list of tags, for name-based tokens (default “en-US”)

Options

options

The hundred-year window a yy token resolves in

Type: TwoDigitYearOptions.

Option	Type	Default	Description
`yearWindow?`	`number` \| `"rolling"`	None. A value with a two-digit year returns the sentinel: no standard says which century it belongs to, so the caller states it.	The hundred-year window a two-digit year falls in. A number is the first year of a fixed window, an integer from 0 to 9900: `2000` reads `00`–`99` as 2000–2099; `1950` reads `50`–`99` as 1950–1999 and `00`–`49` as 2000–2049. A fixed window gives the same answer in any year, so it is the form for stored data, archives and anything re-processed later. `"rolling"` is the hundred years around today: from 50 years before the current UTC calendar year to 49 years after it (in 2026, 1976–2075). It is the form for live messages and never needs maintenance, but it gives a different answer for the same stored value as years pass. Any other value returns the function’s sentinel.

Returns

ISO PlainDate string, or "" on no match, malformed pattern, or invalid input

TwoDigitYearOptions

Examples

import { parseDateWithPattern } from "@northguild/gmt/plain/parse";

parseDateWithPattern("03/15/2024", "MM/dd/yyyy") // "2024-03-15"

Source

plain/parse/parseDateWithPattern.ts