@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)

  Units to never use for relative time formatting.

  Default: ['quarter']

• roundingMode? (RoundingMode)

  Rounding mode to use when the resulting duration is not an integer (e.g., 4.7 seconds).

  It is roughly equivalent to the roundingMode option for the Intl.NumberFormat API and accepts the following options:

  • ceil — round towards positive infinity.
  • floor — round towards negative infinity.
  • expand — round away from 0.
  • trunc — round towards 0.
  • halfCeil — round values below or at half-increment towards positive infinity, and values above away from 0.
  • halfFloor — round values below or at half-increment towards negative infinity, and values above away from 0.
  • halfExpand — round values above or at half-increment away from 0, and values below towards 0.
  • halfTrunc — round values below or at half-increment towards 0, and values above away from 0.
  • halfEven — round values at half-increment towards the nearest even value, values above it away from 0, and values below it towards 0.

  Default: 'trunc'.

• unitRounding? (boolean)

  Whether to round to the nearest unit if the rounded duration goes above the threshold for the current unit.

  For example, if 59.7 minutes round to 60 minutes, and this option is enabled, the duration will be rounded to use hour units, thus returning "1 hour". Otherwise, the result of 60 minutes will be returned as is — "60 minutes".

  Default: true.

RoundingMode

String literal for one of the supported rounding modes.

Possible values: "ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc", "halfEven".

Acknowledgements

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

Credits

Made with 💜 by Brawaru. Released under MIT Licence.