# addYearMonth

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

## Signature

```ts
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).

## Parameters

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

## Options

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

## Returns

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

## Examples

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

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

## Source

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