@vintl/how-ago

Relative time with @formatjs/intl made easy.

Summary

Intl.RelativeTimeFormat offers a way to localize relative time, like ‘1 day ago‘ or ‘in 1 year’. Unfortunately, it's very bare bones and does not perform any calculations, so you have to manually choose the unit of time and then amount of that unit.

This module provides an easy binding for @formatjs/intl to automatically calculate the most suitable unit based on formatting options and a time range, and then format the range with that unit.

Example

import { createIntl } from '@formatjs/intl'
import { createFormatter } from '@vintl/how-ago'

const intl = createIntl({ locale: 'en-US' })

const ago = createFormatter(intl)

const oneDay = 86400000 // ms

console.log(ago(Date.now() - oneDay))
// => "yesterday"

console.log(ago(Date.now() + oneDay * 2))
// => "in 2 days"

API

`createFormatter`

A function that creates a function to format relative time using the provided IntlShape.

Parameters:

intl (IntlShape) — IntlShape, which methods to format relative time or date will be used.

Returns: Formatter — Formatter function.

Formatter

A function that, given a specific time range or just a start date, calculates the time span between the two (if only the start date is provided, then the end date is assumed to be the time of the call). It then chooses the most suitable unit to display the span and returns a formatted string (e.g. ‘5 seconds ago’, ‘10 seconds ago’).

It uses Intl.RelativeTimeFormat under the hood, with the option numeric set to 'auto' by default. This means the span, such as +1 day, is formatted as ‘tomorrow’ and -1 day as ‘yesterday’. This default can be overridden through the provided options to match the original behaviour of Intl.RelativeTimeFormat, which is using 'always' as the default for numeric.

Parameters:

range (DateTimeRange) — Range for which time span is calculated.
options (FormatOptions) — Options for relative time formatter.

Returns: string — Formatted relative time or date used the most suitable unit or date formatting according to the provided options.

`DateTimeRange`

Describes a time range type which can be a value which is used as from, an array of values (from (1st element) and to (2nd element)) or an object with properties from and to which are also time range values.

If to is not omitted, then it is assumed to be the current time at the moment of interpretation.

`DateTimeRangeValue`

Describes a value within the time range that can be used as or converted to a timestamp. It must be either a string which can be used to instantiate a new Date object, a number containing UNIX time in milliseconds, or a Date object.

`FormatOptions`

Extends: Intl.RelativeTimeFormatOptions (omitted: localeMatcher) & { format?: string }.

Properties:

maximumUnit? (Intl.RelativeTimeFormatUnit or 'none')

Maximum unit after which formatting to relative time should be abandoned and instead end date must be formatted using dateTimeOptions.

If set to 'none', any time difference that does not exceed minimumUnit will be formatted in relative time.

Default: 'none'.
minimumUnit? (Intl.RelativeTimeFormatUnit or 'none')

Minimum unit before which formatting to relative time should be abandoned and instead end date must be formatted using dateTimeOptions.

If set to 'none', any time difference that does not exceed maximumUnit will be formatted in relative time.

Default: 'none'.
dateTimeOptions? (Intl.DateTimeFormatOptions (omitted: localeMatcher) & { format?: string })

Options for datetime formatting when it reaches the cut-off unit.

Default: { dateStyle: 'long', timeStyle: 'short' }
excludedUnits? (Array of [Intl.RelativeTimeFormatUnit][intl_relTimeUnit])

Units to never use for relative time formatting.

Default: ['quarter']

Acknowledgements

This implementation is based on the implementation from Modrinth's Omorphia project.

brawaru / how-ago