roundZoned

Signature

roundZoned(value: string, options: { smallestUnit: SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">; roundingIncrement?: number; roundingMode?: RoundingMode; }): string

Round an ISO 8601 zoned datetime string to the specified unit.

• Returns "" for invalid inputs.
• Date units (“year”, “month”, “week”) return "". This is the Temporal spec, not a polyfill limitation: ZonedDateTime.prototype.round accepts time units and “day” only (ValidateTemporalUnitValue with time and « day »).
• Wraps Temporal.ZonedDateTime.round() which throws on invalid options.
• Output precision follows smallestUnit: no fractional seconds for “day”, “second” and coarser, 3 digits for “millisecond”, 6 for “microsecond” and 9 for “nanosecond”, so the result never hides the precision the unit asked for.
• Note: Temporal’s ZonedDateTime.prototype.round takes no disambiguation or offset options.
• Follows TC39 ZonedDateTime.round, which rounds the wall clock and re-resolves it in the zone. Across a transition the result can land after the input or on another local date — Pacific/Chatham “2024-09-29T03:50:00+13:45” truncated to the hour gives 04:00+13:45, 15 minutes later. Use floorToZone for a boundary that never exceeds the instant.

Parameters

Parameter	Type	Description
value	string	ISO 8601 zoned datetime string

Options

options

the unit to round to, with an optional increment and rounding mode

Option	Type	Default	Description
smallestUnit	"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond" | PluralUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">	Required	The unit to round to: "day" or a time unit from "hour" to "nanosecond", in its singular or plural form, as Temporal’s GetTemporalUnitValuedOption accepts both. It also sets how many fractional-second digits the result is written with.
roundingIncrement?	number	1, Temporal’s default.	The size of the step, in smallestUnits, that the value is rounded to a multiple of, such as 15 for quarter hours. It must divide evenly into the next larger unit and be smaller than it, and must be 1 for "day"; any other value returns "". A non-integer is truncated first, as Temporal does.
roundingMode?	"ceil" | "floor" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven"	"halfExpand", Temporal’s default.	Which way a value between two multiples goes. "halfExpand" picks the nearest multiple and sends a tie up; "floor" and "trunc" always go down, "ceil" and "expand" always up. The other half modes differ from "halfExpand" only in how a tie breaks.

Returns

Rounded ISO 8601 zoned datetime string, or "" on invalid input

Examples

import { roundZoned } from "@northguild/gmt/zoned/calculate";

roundZoned("2024-06-15T12:34:56-04:00[America/New_York]", { smallestUnit: "hour" }) // "2024-06-15T13:00:00-04:00[America/New_York]"

value

output

 

Source

zoned/calculate/roundZoned.ts