formatRelativeUnix

Signature

formatRelativeUnix(value: string | number, locale?: string, options?: FormatRelativeUnixOptions): string

import { formatRelativeUnix } from "@northguild/gmt/unix/format";

Format the relative time between a unix epoch value and a reference instant.

• Auto-picks the display unit (second through year) based on the distance, unless largestUnit forces one.
• roundingMethod controls how the distance rounds to the display unit.

Parameters

Parameter	Type	Description
value	string | number	unix epoch (string or number, per epochUnit) to format
locale	string	optional: BCP 47 locale tag

Options

options

Option	Type	Default
style?	"long" | "short" | "narrow"	—
numeric?	"always" | "auto"	—
largestUnit?	RelativeUnit	—
roundingMethod?	RelativeRoundingMethod	—
epochUnit?	"seconds" | "milliseconds"	—
reference?	string | number	—
timeZone?	string	—

Returns

the formatted relative-time string, or “” on invalid input

Related types

• FormatRelativeUnixOptions

Examples

formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds" }) // "3 years ago"
formatRelativeUnix(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
formatRelativeUnix("not-a-number") // ""

Source

unix/format/formatRelativeUnix.ts