addDate

Signature

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

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

Return a PlainDate ISO string with amount added according to units.

• Validates value, units, and amount before performing the add.
• Accepts a GMT calendar-annotated PlainDate string (as produced by convertDateToCalendar, e.g. "5784-06-15[u-ca=hebrew]"), not just a bare ISO string — E5 (issue #78). Calendar-unit arithmetic (“add 1 month”) resolves against that calendar (a Hebrew leap month, a Persian leap year), and the result is re-formatted in the same calendar — re-derived from the arithmetic result, never copied from the input tag, since arithmetic can cross a leap-month or era boundary (e.g. Adar I -> Adar). A bare ISO string is unaffected — always treated as, and always returns, "gregorian".
• Returns “” for invalid inputs. overflow (“constrain” (default) | “reject”) controls out-of-range results, e.g. adding 1 month to Jan 31: “constrain” clamps to Feb 29/28, “reject” throws (resulting in “”). Whether reject actually throws is calendar-dependent: adding 1 year from Hebrew Adar I (a leap-only month) does NOT throw even with overflow: "reject" (Temporal remaps to the non-leap year’s Adar instead of rejecting), while adding 1 month from the Ethiopic 30-day 12th month into the 5/6-day Pagumen DOES throw.

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 add

Options

options

Option	Type	Default
overflow?	Overflow	—

Returns

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

Related types

• DurationUnit
• DateDurationUnit
• Overflow

Examples

addDate("2024-03-10", { days: 5 }) // "2024-03-15"
addDate("invalid", { days: 5 }) // ""
addDate("2024-01-31", { months: 1 }, { overflow: "constrain" }) // "2024-02-29"
addDate("2024-01-31", { months: 1 }, { overflow: "reject" }) // ""
addDate("5784-06-15[u-ca=hebrew]", { months: 1 }) // "5784-07-15[u-ca=hebrew]" (Adar I -> Adar, both 30 days)

Source

plain/calculate/addDate.ts