roundUtc

Signature

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

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

Round a UTC datetime string to the specified unit.

• Converts to Instant, rounds, converts back to UTC Instant string.
• Supports: “hour”, “minute”, “second”, “millisecond”, “microsecond”, “nanosecond”.
• Date units (“year”, “month”, “week”, “day”) are not supported by the Temporal polyfill’s Instant.round() — they return “”.
• Wraps all Temporal calls in try-catch; returns “” on any error.

Parameters

Parameter	Type	Description
value	string	ISO UTC datetime string

Options

options

Option	Type	Default
smallestUnit	Temporal.SmallestUnit<"hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">	—
roundingIncrement?	number	—
roundingMode?	Temporal.RoundingMode	—
fractionalSecondDigits?	FractionalDigit	—

Returns

Rounded ISO UTC Instant string, or “” on invalid input

Related types

• FractionalDigit

Examples

roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "hour" }) // "2024-06-15T13:00:00Z"
roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "minute", roundingIncrement: 15 }) // "2024-06-15T12:45:00Z"
roundUtc("2024-06-15T12:34:56Z", { smallestUnit: "second", roundingMode: "floor" }) // "2024-06-15T12:34:56Z"
roundUtc("invalid", { smallestUnit: "hour" }) // ""
roundUtc("", { smallestUnit: "hour" }) // ""

Source

utc/calculate/roundUtc.ts