roundUtc

Signature

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

Round a UTC datetime string to the specified unit.

• Converts to Instant, rounds, converts back to UTC Instant string.
• Day and larger units (“day”, “week”, “month”, “year”) return "". This is the Temporal spec, not a polyfill limitation: Instant.prototype.round validates smallestUnit as a time unit (ValidateTemporalUnitValue with time), because an instant has no calendar or zone to define a day. Round a zoned value with roundZoned for a day boundary.
• Wraps all Temporal calls in try-catch; returns "" on any error.

Parameters

Parameter	Type	Description
value	string	ISO UTC datetime string

Options

options

What to round to, how, and the precision of the result

Option	Type	Default	Description
smallestUnit	"hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond" | PluralUnit<"hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">	Required	The unit to round to: "hour", "minute", "second", "millisecond", "microsecond" or "nanosecond", singular or plural as Temporal’s GetTemporalUnitValuedOption accepts both.
roundingIncrement?	number	1, Temporal’s default.	The multiple of smallestUnit to round to, such as 15 for quarter hours. It must divide a 24-hour day evenly (Temporal’s Instant.prototype.round); any other value returns "".
roundingMode?	"ceil" | "floor" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven"	"halfExpand", Temporal’s default.	Which multiple a value between two is rounded to. "halfExpand" picks the nearer one and sends a tie to the later instant; "floor" and "trunc" pick the earlier, "ceil" and "expand" the later, and the other "half…" modes differ only in how a tie breaks.
fractionalSecondDigits?	0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | "auto" | 8 | 9 (FractionalDigit)	The digits smallestUnit names: 3 for "millisecond", 6 for "microsecond", 9 for "nanosecond" and 0 for any coarser unit.	The number of fractional-second digits the result is written with, 0 to 9, or "auto" to drop trailing zeros. It overrides the unit’s own count, coarser or finer; an invalid value returns "".

Returns

Rounded ISO UTC Instant string, or "" on invalid input

Related types

• FractionalDigit

Examples

import { roundUtc } from "@northguild/gmt/utc/calculate";

roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hour" }) // "2024-06-15T13:00:00Z"

value

output

 

Source

utc/calculate/roundUtc.ts