# diffYearMonth

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

## Signature

```ts
diffYearMonth(a: string, b: string, unit: "years" | "months" | "year" | "month"): number | null
```

Return the whole years or months from year-month `a` to year-month `b`.

- `unit` is `"years"`, `"year"`, `"months"` or `"month"`; any other unit returns `null` (Temporal's DifferenceTemporalPlainYearMonth allows years and months only).
- Direction is from `a` to `b`: positive when `b` is later, negative when earlier.
- The result is truncated toward zero, so `2025-11` to `2027-10` is 1 year; never `-0`.
- The lowest year-month (`-271821-04`) can only be compared with itself (`0`); against any other year-month, day 1 is out of range and the result is `null`.
- In `years`, a pair whose next whole year passes `+275760-09` or `-271821-04` returns `null` (Temporal's ComputeNudgeWindow computes the end bound one year further; the call throws).
- Returns `null` for a string that is not a year-month.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `a` | `string` | year-month string for the start |
| `b` | `string` | year-month string for the end |
| `unit` | `"years"` \| `"months"` \| `"year"` \| `"month"` | unit to measure in |

## Returns

the difference in `unit`, or null on invalid input

## Examples

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

diffYearMonth("2025-11", "2026-10", "months") // 11
```

## Source

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