roundUnix

Signature

roundUnix(value: number, options: { smallestUnit: Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">; roundingIncrement?: number; roundingMode?: Temporal.RoundingMode; epochUnit?: "seconds" | "milliseconds"; timeZone?: string; }): number

import { roundUnix } from "@northguild/gmt/unix/calculate";

Round a Unix timestamp to the specified unit.

• Converts to ZonedDateTime, rounds, converts back to epoch.
• Supports: “day”, “hour”, “minute”, “second”, “millisecond”, “microsecond”, “nanosecond”.
• Date units (“year”, “month”, “week”) are not supported by the Temporal polyfill’s ZonedDateTime.round() — they return null.
• Returns null for invalid input.

Parameters

Parameter	Type	Description
value	number	Unix timestamp (number)

Options

options

Option	Type	Default
smallestUnit	Temporal.SmallestUnit<"day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond">	—
roundingIncrement?	number	—
roundingMode?	Temporal.RoundingMode	—
epochUnit?	"seconds" | "milliseconds"	—
timeZone?	string	—

Returns

Rounded Unix epoch number, or null on invalid input

Examples

roundUnix(1706659200000, { smallestUnit: "hour" }) // 1706662800000 (rounded up to next hour)
roundUnix(1706659200000, { smallestUnit: "day", epochUnit: "seconds" }) // 1706640000 (start of day in seconds)
roundUnix(1706659200000, { smallestUnit: "hour", roundingIncrement: 2 }) // 1706662800000 (rounded to nearest 2-hour mark)
roundUnix(-86400000, { smallestUnit: "day" }) // -86400000 (start of day for negative timestamp)
roundUnix("invalid", { smallestUnit: "hour" }) // null
roundUnix(NaN, { smallestUnit: "hour" }) // null

Source

unix/calculate/roundUnix.ts