subtractDate

Signature

subtractDate(value: string, units: Partial<Record<DateDurationUnit, number>>, options?: { overflow?: Overflow; }): string

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

Return a PlainDate ISO string with units subtracted from value.

• Validates value, units, and amount before performing the subtract.
• Accepts a GMT calendar-annotated PlainDate string (as produced by convertDateToCalendar), not just a bare ISO string — E5 (issue #78). See addDate’s JSDoc for the full calendar-unit arithmetic rationale (leap months/years, era transitions, the overflow asymmetry); this function is the mirror image (.subtract instead of .add).
• Returns “” for invalid inputs. overflow (“constrain” (default) | “reject”) controls out-of-range results, e.g. subtracting 1 month from Mar 31: “constrain” clamps to Feb 29/28, “reject” throws (resulting in “”).

Parameters

Parameter	Type	Description
value	string	ISO PlainDate string, optionally calendar-annotated
units	Partial&lt;Record&lt;DateDurationUnit, number&gt;&gt;	Partial<Record<DateDurationUnit, number>> object specifying units to subtract

Options

options

Option	Type	Default
overflow?	Overflow	—

Returns

ISO PlainDate string after subtraction, or “” on invalid input

Related types

• DurationUnit
• DateDurationUnit
• Overflow

Examples

subtractDate("2024-03-15", { day: 5 }) // "2024-03-10"
subtractDate("invalid", { day: 5 }) // ""
subtractDate("2024-03-31", { months: 1 }, { overflow: "reject" }) // ""
subtractDate("5784-07-15[u-ca=hebrew]", { months: 1 }) // "5784-06-15[u-ca=hebrew]" (Adar -> Adar I)

Source

plain/calculate/subtractDate.ts