cycleDateTime

Signature

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

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

• cycleDateTime is not addDateTime: cycling December’s month by +1 stays in the same year, and cycling hour 23 by +1 stays on the same day. Reach for addDateTime for calendar/clock arithmetic; reach for cycleDateTime when a single field (e.g. a datepicker segment) must stay isolated from the others.
• Date fields (year/month/day) wrap the same way cycleDate does — year is unbounded, month wraps 1–12, day wraps 1–the current month’s day count. Time fields (hour/minute/second/millisecond/microsecond/nanosecond) wrap the same way cycleTime does — hour always 0–23 (no hourCycle: 12 option; see cycleTime’s doc for why).
• Cycling month or year can still shift day via overflow, exactly as setDateTime’s .with() call does.
• Returns "" for an invalid value, an invalid field, or an amount that is not a finite number.

Parameters

Parameter	Type	Description
value	string	ISO PlainDateTime string
field	DateTimeCycleField	the field to cycle: “year” | “month” | “day” | “hour” | “minute” | “second” | “millisecond” | “microsecond” | “nanosecond”
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 PlainDateTime string with field cycled, or "" on invalid input

Related types

• DateTimeCycleField
• DateCycleField
• TimeCycleField
• Overflow

Examples

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

cycleDateTime("2024-06-15T09:30:00", "hour", 1) // "2024-06-15T10:30:00"

valueamount

output

 

Source

plain/calculate/cycleDateTime.ts