formatRelativeTime
Signature
Section titled “Signature”formatRelativeTime(value: string, locale?: string | string[], options?: FormatRelativeTimeOptions): stringFormat the relative time between a plain time and a reference time.
- Auto-picks the display unit (second/minute/hour) based on the distance, unless
largestUnitforces one. largestUnitis one of those three units, singular or plural. Any other value returns"".optionsmust be an object or omitted:nullor any other primitive returns"", as Temporal’s GetOptionsObject rejects it.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | string | ISO time string to format |
locale | string | string[] | optional: BCP 47 locale tag, or a preference list of tags (ECMA-402) |
Options
Section titled “Options”options
How the distance is measured, rounded and worded
Options for formatRelativeTime: the reference time, the display unit, the rounding and the wording.
import type { FormatRelativeTimeOptions } from "@northguild/gmt";| Option | Type | Default | Description |
|---|---|---|---|
largestUnit? | "hours" | "minutes" | "seconds" | RelativeTimeUnit (RelativeTimeUnit) | None. The unit is picked from the distance. | The unit the distance is written in, whatever its size: "second", "minute" or "hour", singular or plural. Any other value returns "", a date unit such as "day" included: a time has no date, and Temporal throws RangeError for a unit outside the units of the type. Omitted, the unit is picked from the distance: second under a minute, minute under an hour and hour beyond. |
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”). |
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”. |
reference? | string | The current date and time. | The moment the distance is measured from, as an ISO string in the same form as the value being formatted. |
Returns
Section titled “Returns”the formatted relative-time string, or "" on invalid input
RelativeTimeUnit
Section titled “RelativeTimeUnit”Narrow RelativeUnit for PlainTime-based formatting. Excludes date units (year, month, week, day) because PlainTime has no date component.
import type { RelativeTimeUnit } from "@northguild/gmt";"hour" | "minute" | "second"Related types
Section titled “Related types”Examples
Section titled “Examples”import { formatRelativeTime } from "@northguild/gmt/plain/format";
formatRelativeTime("14:30:00", "en-US", { style: "short", reference: "16:30:00" }) // "2 hr. ago"