roundUnix

Signature

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

Round a Unix timestamp to the specified unit.

• Converts to ZonedDateTime, rounds, converts back to epoch.
• Supports: “day”, “hour”, “minute”, “second”, “millisecond”, “microsecond”, “nanosecond”.
• Each unit is accepted in its singular or plural form (“hour” or “hours”), as Temporal’s GetTemporalUnitValuedOption accepts both (§13.17).
• Date units (“year”, “month”, “week”, in either form) return null: Temporal’s ZonedDateTime.prototype.round accepts no unit larger than “day”.
• 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 — in Pacific/Chatham, 1727532300000 (03:50+13:45) truncated to the hour gives 1727532900000, 15 minutes later. Use floorToZone for a boundary that never exceeds the instant.
• value is a safe integer or a digit string ("1706661000000"); anything else returns null.
• Returns null for invalid input.
• Limit at an offset with seconds. The instant is placed in the offset’s whole-minute zone, moved by its seconds, and the moved instant must be inside Temporal’s range. So within the offset’s seconds (under a minute) of the last instant Temporal supports (+275760-09-13T00:00:00Z) for an offset east of UTC, or of the first (-271821-04-20T00:00:00Z) for one west, this returns null. An offset to the minute has no such limit.

Parameters

Parameter	Type	Description
value	string | number	Unix epoch: a safe integer, or a string of optionally negative ASCII digits

Options

options

rounding settings: the unit to round to, how to round, and how value is read

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, from "day" down to "nanosecond", singular or plural. A larger unit returns null, as Temporal.ZonedDateTime.prototype.round accepts none above "day".
roundingIncrement?	number	1, Temporal’s default.	The number of smallestUnit steps to round to, such as 15 with "minute" for quarter hours. It must divide the next larger unit evenly and be smaller than it, and must be 1 for "day"; any other value returns null. A non-integer is truncated first, as Temporal does.
roundingMode?	"ceil" | "floor" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven"	"halfExpand", Temporal’s default.	The step a value between two steps is rounded to. "halfExpand" picks the nearer step and sends a tie to the later one; "floor" and "trunc" pick the earlier step, "ceil" and "expand" the later, and the other "half…" modes differ only in how a tie breaks.
epochUnit?	"seconds" | "milliseconds" | "second" | "millisecond" (UnixUnit)	"milliseconds"	The unit the epoch values are counted in: "seconds" or "milliseconds", singular or plural. Any other value returns null. The result is in the same unit.
timeZone?	string	"UTC"	The time zone the wall clock is rounded in: an IANA name, a UTC offset (a time zone identifier such as +05:30, +0530 or -08, or a stored offset ±HH:MM[:SS], what getTimeZoneOffset returns), or "local" for the system time zone. An unknown zone returns null.

Returns

Rounded Unix epoch number, or null on invalid input

Related types

• UnixUnit

Examples

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

roundUnix(1706661000000, { smallestUnit: "hour", timeZone: "UTC" }) // 1706662800000 (00:30 is a tie; halfExpand rounds up)

value

output

 

Source

unix/calculate/roundUnix.ts