subtractDate

Signature

subtractDate(value: string, units: Partial<Record<"years" | "months" | "weeks" | "days", number>>, options?: { overflow?: "reject" | "constrain" | undefined; }): string

Return a PlainDate ISO string with units subtracted from value.

• Validates value, units, and amount before performing the subtract.
• Accepts an RFC 9557 calendar-annotated PlainDate string (as convertDateToCalendar writes it), not just a bare ISO string. See addDate’s JSDoc for the calendar-unit arithmetic (leap months and years, the overflow asymmetry); this function is the mirror image.
• Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, [u-ca=<id>], canonical calendar ids); see isValidCalendarDate.
• Returns "" for invalid inputs.

Parameters

Parameter	Type	Description
value	string	ISO PlainDate string, optionally calendar-annotated
units	Partial<Record<"years" | "months" | "weeks" | "days", number>>	Partial<Record<DateDurationUnit, number>> object specifying units to subtract

Options

options

How an out-of-range result is handled

Option	Type	Default	Description
overflow?	"reject" | "constrain" (Overflow)	"constrain", Temporal’s default.	What to do when the result is not a real date. "constrain" clamps it to the last valid day, so Mar 31 - 1 month is Feb 29 or 28; "reject" returns "".

Returns

ISO PlainDate string after subtraction, or "" on invalid input

Related types

• DateDurationUnit
• Overflow

Examples

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

subtractDate("2024-03-15", { days: 5 }) // "2024-03-10"

value

output

 

Source

plain/calculate/subtractDate.ts