parseYearMonthWithPattern

Unreleased

Not in @northguild/gmt 1.20.0 on npm yet. It is on main and ships in the next release.

Signature

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

Parse a year-month string against a caller-supplied token pattern (e.g. "MM/yyyy", "MMMM yyyy") and return it as an ISO year-month string, YYYY-MM.

• Decoding, not display. This reads a known, fixed producer format. A pattern with a day, weekday or time token returns "" — use parseDateWithPattern for a full date.

• The pattern needs both a year and a month, otherwise "".

• Digits are ASCII, as in the other pattern parsers. ### Token table

  Token	Field	Width	Range	Notes
  yyyy	year	4 digits	0000–9999
  yy	year	2 digits	—	Read through options.yearWindow; with no window the result is ""
  MM	month	2 digits	01–12
  M	month	1-2 digits	1–12
  MMMM	month name (long)	locale	—	Reads the format-context name (“октября”) or the stand-alone name (“октябрь”); UTS #35 Part 4, Parsing Dates and Times
  MMM	month name (short)	locale	—	Reads either context, as MMMM
  LL	month	2 digits	01–12	Stand-alone context; read as MM
  L	month	1-2 digits	1–12	Stand-alone context; read as M
  LLLL	month name (long)	locale	—	Same names as MMMM
  LLL	month name (short)	locale	—	Same names as MMM
  GG / GGGG	era	locale	—	Qualifies the year: 1 BC is year 0000

• Literal text follows UTS #35: text in 'single quotes' is a literal, '' is one literal quote, and a quote that never closes makes the pattern malformed ("").

• Month names match case-insensitively. A -u-ca- locale extension is overridden to Gregorian.

• Name tokens are locale-aware. If locale is omitted (or an empty list) and the pattern uses one, GMT reads English names in "en". An ill-formed tag returns "".

Parameters

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

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

the YYYY-MM string, or "" on no match, malformed pattern, or invalid input

Related types

• TwoDigitYearOptions

Examples

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

parseYearMonthWithPattern("10/2026", "MM/yyyy") // "2026-10"

value

pattern

locale (optional)

output

 

Source

plain/parse/parseYearMonthWithPattern.ts