roundDate

Signature

roundDate(value: string, options: { smallestUnit: SmallestUnit<DateUnit>; roundingIncrement?: number; roundingMode?: RoundingMode; }): string

Round an ISO 8601 date string to the specified date unit.

• Returns "" for invalid inputs.
• All date units use manual start-of-unit rounding. Weeks start on Monday.
• The rounding grid is anchored at the unit containing value, so "halfEven" breaks an exact tie towards that unit’s start (multiple 0, the even one).
• The position within the unit is measured towards the next start, so a date in a unit that began before the first representable date (-271821-04-19) still rounds up to the next start. When it rounds down to that unrepresentable start, the result is "".
• In the last representable year (+275760) a date that rounds down still returns its unit’s start; only rounding up past +275760-09-13 returns "".
• Wraps all Temporal calls in try-catch; returns "" on any error.

Parameters

Parameter	Type	Description
value	string	ISO 8601 date string

Options

options

The unit to round to and how to round

Option	Type	Default	Description
smallestUnit	DateUnit | PluralUnit<DateUnit> (DateUnit)	Required	The unit to round to: "year", "month", "week" or "day", singular or plural, as Temporal’s GetTemporalUnitValuedOption accepts both (§13.17). A time unit such as "hour" returns "".
roundingIncrement?	number	1, Temporal’s default.	How many units make one rounding step, counted from the unit that holds value. Read as Temporal reads it: a non-integer is truncated (1.5 rounds by 1), and a value below 1 or not finite returns "".
roundingMode?	"ceil" | "floor" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven"	"halfExpand", Temporal’s default.	Which way a date between two steps goes: one of Temporal’s nine rounding modes, such as "floor", "ceil" or "halfExpand" (to the nearer step, a tie going up). Any other value returns "".

Returns

Rounded ISO 8601 date string, or "" on invalid input

Related types

• DateUnit

Examples

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

roundDate("2024-06-15", { smallestUnit: "year" }) // "2024-01-01"

value

output

 

Source

plain/calculate/roundDate.ts