intlDuration
intlDuration(value, options?) converts milliseconds to human-readable duration text. Use it for time spans (API delays, countdowns, file-size elapsed windows, etc.).
It mirrors Intl.DurationFormat behavior and falls back to a package implementation when that API is unavailable.
Input shape
value should be a number in milliseconds.
ts
1import { intlDuration } from '@beforesemicolon/intl'2 3intlDuration(3_661_000)4intlDuration(86_400_000)Signature
ts
1function intlDuration(2 value: number,3 options?: {4 locale?: string5 scope?: IntlRuntime6 fields?: '*' | string | string[]7 style?: 'long' | 'short' | 'narrow' | 'digital'8 }9): stringInvalid values return ''.
Option map
| Option | Type | Default | Effect |
|---|---|---|---|
locale | string | runtime locale | One-off locale override |
scope | IntlRuntime | getIntl() | Use nested runtime state |
fields | string | string[] | '*' | ['hours', 'minutes', 'seconds'] | Units to include |
style | long | short | narrow | digital | long | Output compactness |
Supported units
years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds.
Singular unit names are normalized (hour → hours).
Examples
Field permutations
ts
1intlDuration(90_000, { fields: 'minutes seconds' })2intlDuration(3_600_000, { fields: 'hours' })3intlDuration(86_400_000, { fields: '*' })4intlDuration(3_661_000, { fields: 'hour minute second' }) // normalized to pluralStyle permutations
ts
1intlDuration(3_600_000, { fields: 'hours', style: 'long' })2intlDuration(3_600_000, { fields: 'hours', style: 'short' })3intlDuration(3_600_000, { fields: 'hours', style: 'narrow' })4intlDuration(3_600_000, { fields: 'hours minutes seconds', style: 'digital' })Locale and scope overrides
ts
1import { createIntl, intlDuration } from '@beforesemicolon/intl'2 3const scoped = createIntl({ locale: 'fr-FR', messages: {} })4 5intlDuration(3661_000, { scope: scoped, locale: 'fr-FR' })Empty input edge case
ts
1intlDuration(NaN) // ''