formatRelativeUnix

Signature

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

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

• Auto-picks the display unit based on the distance, unless largestUnit forces one: second under a minute, minute under an hour, hour under a day, then formatRelativeDate’s thresholds — day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads “3 years ago”.
• Compatibility: before 1.16.0 week, month and year were never auto-picked (“1,096 days ago”). Pass largestUnit: "day" to keep a day count.
• largestUnit is one of the seven units from "second" to "year", singular or plural. Any other value returns "".
• value and a numeric reference are safe integers or strings of optionally negative ASCII digits; largestUnit and epochUnit accept singular or plural names.
• options must be an object or omitted: null returns "", as Temporal’s GetOptionsObject rejects it.
• Limit at an offset with seconds. A month or a year is measured from reference, placed in the offset’s whole-minute zone and moved by its seconds, and the moved instant must be inside Temporal’s range. So when one is measured and reference is 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 "". An offset to the minute has no such limit.

Parameters

Parameter	Type	Description
value	string | number	unix epoch (string or number, per epochUnit) to format
locale	string | string[]	optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)

Options

options

optional: the wording, the unit and rounding of the distance, and what it is measured from

Options for formatRelativeUnix: the wording of the phrase, the unit and rounding of the distance, and the reference instant, epoch unit and time zone the distance is measured with.

import type { FormatRelativeUnixOptions } from "@northguild/gmt";

Option	Type	Default	Description
style?	"long" | "short" | "narrow"	"long"	The length of the unit name, as the style of Intl.RelativeTimeFormat: "long" (“in 3 months”), "short" (“in 3 mo.”) or "narrow" (the locale’s most compact form).
numeric?	"auto" | "always"	"auto"	Whether a distance may be written as a word instead of a number, as the numeric option of Intl.RelativeTimeFormat. "auto" uses the locale’s word where it has one (“yesterday”, “next year”); "always" writes the number every time (“1 day ago”).
largestUnit?	"years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | RelativeUnit (RelativeUnit)	None. The unit is picked from the distance.	The unit the distance is written in, whatever its size: "second", "minute", "hour", "day", "week", "month" or "year", singular or plural. Any other value returns "". Omitted, the unit is picked from the distance: second under a minute, minute under an hour, hour under a day, day under 7 days, week under 28, month under 365 and year beyond.
roundingMethod?	"ceil" | "floor" | "round" (RelativeRoundingMethod)	"round"	The way a fractional distance becomes the whole number displayed: "round" goes to the nearest whole number, "floor" down and "ceil" up. It applies to the signed value, where a past distance is negative, so "floor" turns −1.5 hours into “2 hours ago”.
epochUnit?	"seconds" | "milliseconds" | "second" | "millisecond" (UnixUnit)	"milliseconds"	The unit value and a numeric reference are counted in: "seconds" or "milliseconds", singular or plural. Any other value returns "".
reference?	string | number	The current instant.	The instant the distance is measured from, as a UTC ISO string, or an epoch in epochUnit given as a safe integer or a digit string. Any other value returns "".
timeZone?	string	"UTC"	The time zone that anchors a calendar unit (week, month or year): 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 "" whatever the unit.

Returns

the formatted relative-time string, or "" on invalid input

Related types

• RelativeUnit
• RelativeRoundingMethod
• UnixUnit

Examples

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

formatRelativeUnix(1710685845000, "en-US", { epochUnit: "milliseconds", reference: 1805358645000 }) // "3 years ago"

valuelocale ?

output

 

Source

unix/format/formatRelativeUnix.ts