cycleDate

Signature

cycleDate(value: string, field: DateCycleField, amount: number, options?: { round?: boolean; overflow?: "reject" | "constrain" | undefined; }): string

Return a PlainDate ISO string with field cycled by amount, wrapping at that field’s own min/max instead of carrying into the next larger field.

• cycleDate is not addDate: cycling December’s month by +1 stays in the same year ("2024-12-15" → "2024-01-15"), where addDate(value, { months: 1 }) would correctly overflow into January of the next year. Reach for addDate when you want calendar arithmetic; reach for cycleDate when a single field (e.g. a datepicker segment) must stay isolated from the others.
• year has no upper/lower wrap — cycling it is plain addition (or a step to a multiple, with round): 2022 by +5 with round: true lands on 2025, the next multiple of 5. month wraps 1–12. day wraps 1–the current month’s day count, so cycling day never changes month.
• Cycling month or year can still shift day via overflow — e.g. cycling month from a 31st into a shorter month clamps under the default "constrain" (or returns "" under "reject") exactly the way setDate’s own .with() call does; this is the same clamping addDate’s Jan 31 + 1 month case produces, not new behavior.
• Returns "" for an invalid value, an invalid field, or an amount that is not a finite number.

Parameters

Parameter	Type	Description
value	string	ISO PlainDate string
field	DateCycleField	the field to cycle: “year” | “month” | “day”
amount	number	signed amount to cycle by

Options

options

How the field is stepped and an out-of-range day is handled

Option	Type	Default	Description
round?	boolean	false	Whether to step to a multiple of amount instead of adding it. true moves to the next multiple in the direction of the sign of amount (the ceiling for a positive amount, the floor for a negative one), not to the nearest one; false adds amount.
overflow?	"reject" | "constrain" (Overflow)	"constrain", Temporal’s default.	What to do when the cycled month or year leaves day past the end of its month. "constrain" clamps day to the last day of that month; "reject" returns "".

Returns

ISO PlainDate string with field cycled, or "" on invalid input

Related types

• DateCycleField
• Overflow

Examples

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

cycleDate("2024-06-15", "month", 1) // "2024-07-15"

valueamount

output

 

Source

plain/calculate/cycleDate.ts