intlRelTime
intlRelTime(value, options?) formats relative values for times like:
0-> now (subject to locale rules)-1-> past1-> future
It supports:
unit: 'auto'(absolute timestamp compared toDate.now())- explicit units (
year,day,minute, etc.)
Native reference: Intl.RelativeTimeFormat
Signature
ts
1function intlRelTime(2 value: number,3 options?: {4 locale?: string5 scope?: IntlRuntime6 unit?: 'auto' | Intl.RelativeTimeFormatUnit7 precision?: number8 numeric?: 'always' | 'auto'9 style?: 'long' | 'short' | 'narrow'10 }11): stringInvalid numbers return ''.
Option map
| Option | Type | Default | Effect |
|---|---|---|---|
locale | string | runtime locale | One-off locale override |
scope | IntlRuntime | getIntl() | Use scoped runtime |
unit | 'auto' | Intl.RelativeTimeFormatUnit | 'auto' | Input interpretation |
precision | number | 0 | Decimal precision for computed deltas |
numeric | 'always' | 'auto' | 'auto' | Numeric vs words like yesterday |
style | 'long' | 'short' | 'narrow' | 'long' | Output compactness |
Examples
Auto timestamps
ts
1intlRelTime(Date.now() + 60_000, { unit: 'auto' }) // "in 1 minute"2intlRelTime(Date.now() - 60_000, { unit: 'auto' }) // "1 minute ago"Explicit unit offsets
ts
1intlRelTime(-2, { unit: 'day' }) // past2intlRelTime(2, { unit: 'day', numeric: 'always' }) // "in 2 days"3intlRelTime(-1, { unit: 'year', locale: 'fr-FR' })Styles and precision
ts
1intlRelTime(-30, { unit: 'minute', style: 'short' })2intlRelTime(1.54 * 60 * 60 * 1000, { unit: 'hour', precision: 1 })3intlRelTime(1.2345, { unit: 'second', precision: 2 })Scoped runtime usage
ts
1import { createIntl, intlRelTime } from '@beforesemicolon/intl'2 3const scoped = createIntl({ locale: 'de-DE', messages: {} })4intlRelTime(Date.now() - 86_400_000, { scope: scoped, unit: 'auto' })Fallback and edge cases
ts
1intlRelTime(Number.NaN) // ''2intlRelTime(1, { unit: 'invalid' as unknown as Intl.RelativeTimeFormatUnit }) // ''