diffYearMonth

Unreleased

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

Signature

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

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

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

a

b

unityearsmonthsyearmonth

output

 

Source

plain/calculate/diffYearMonth.ts