addDate

Signature

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

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

• Validates value, units, and amount before performing the add.
• Accepts an RFC 9557 calendar-annotated PlainDate string (as Temporal.PlainDate#toString() and convertDateToCalendar write it, e.g. "2024-02-24[u-ca=hebrew]"), not just a bare ISO string. Calendar-unit arithmetic (“add 1 month”) resolves against that calendar (a Hebrew leap month, a Persian leap year), and the result carries the same calendar annotation. A bare ISO string is the "iso8601" calendar and returns a bare ISO string.
• Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, [u-ca=<id>], canonical calendar ids); see isValidCalendarDate.
• Whether overflow: "reject" returns "" is calendar-dependent: adding 1 year from Hebrew Adar I (a leap-only month) does not (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.
• 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 add

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 Jan 31 + 1 month is Feb 29 or 28; "reject" returns "".

Returns

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

Related types

• DateDurationUnit
• Overflow

Examples

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

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

value

output

 

Source

plain/calculate/addDate.ts