# parseYearMonthWithPattern

:::caution[Unreleased]
Not in `@northguild/gmt` 1.20.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
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`](/gmt/reference/types/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`](/gmt/reference/types/TwoDigitYearOptions)

## Examples

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

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

## Source

[plain/parse/parseYearMonthWithPattern.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/plain/parse/parseYearMonthWithPattern.ts)