#add

Adds an integer month offset and returns a new Month value. A negative offset moves backward, so add(-1) is equivalent to sub(1).

import { Month } from "@teakit/month";

const month = Month.from("2025-01");

month.add(1).toString(); // "2025-02"
month.add(12).toString(); // "2026-01"
month.add(-1).toString(); // "2024-12"

Month.add("2025-01", 3).toString(); // "2025-04"

Month.from("2025-01-31").add(1).toString(); // "2025-02"
Month.from("2025-01-31").add(1).toString({ precision: "day" }); // "2025-02-28"
Month.from("2024-01-31").add(1).toString({ precision: "day" }); // "2024-02-29"

#API Reference

#Signatures

month.add(months: number): MonthInstance;
Month.add(value: MonthValue, months: number): MonthInstance;

#Parameters

#Returns

Returns a new immutable MonthInstance.

If the source value has a day anchor from a date-like string or native Date, add preserves that anchor for explicit day-precision output. Month calculation still uses only the month index.

#Throws

Throws when months is not a safe integer.

#Agent Contract

#Agent Notes

• Use a negative offset (add(-1)) or sub to move backward.
• Use diff for month differences between two values; do not overload add with another month value.
• Do not use Date#setMonth, because @teakit/month is month-only and timezone-free.
• Use toString({ precision: "day" }) only for output that needs the preserved day anchor; default toString() remains YYYY-MM.