#sub

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

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

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

month.sub(1).toString(); // "2024-12"
month.sub(13).toString(); // "2023-12"

Month.sub("2025-01", 13).toString(); // "2023-12"

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

#API Reference

#Signatures

month.sub(months: number): MonthInstance;
Month.sub(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, sub 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 diff for month differences between two values; do not overload sub 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.