addYearMonth

Signature

addYearMonth(value: string, units: { years?: number; months?: number; }): string

Return a year-month string moved forward by units.

Takes years and months only: a year-month has no day, so { days: 1 }, { weeks: 1 } and the time units return "". An own days, weeks or time key returns "" whatever its value ({ months: 1, days: 0 }): the misspelt-key guard. An inherited zero is no amount.
The result is a year-month, so no day is clamped: 2024-02 plus a year is 2025-02.
A negative amount moves backward; mixed signs, fractions, a misspelt key, a non-number and no unit at all return "".
The lowest year-month (-271821-04) cannot be moved, even by zero, and a result beyond +275760-09 returns "".
Accepts YYYY-MM and the forms isValidYearMonth accepts; the result is always YYYY-MM (±YYYYYY-MM outside 0000-9999).

Parameter	Type	Description
`value`	`string`	year-month string

units

the amounts to move the year-month by

Option	Type	Default	Description
`years?`	`number`	no years; at least one of `years` and `months` must be given.	Whole years to add.
`months?`	`number`	no months; at least one of `years` and `months` must be given.	Whole months to add.

the year-month string after the addition, or "" on invalid input

import { addYearMonth } from "@northguild/gmt/plain/calculate";

addYearMonth("2026-10", { months: 1 }) // "2026-11"

value

units

output