Intl Utils

Provide i18n utilities.

API

selectUnit

This function determines the best fit unit based on a specific set of customizable thresholds.

function selectUnit(
  from: Date | number,
  to: Date | number = Date.now(),
  thresholds = DEFAULT_THRESHOLDS
): {value: number; unit: Unit};

where thresholds has the shape of:

interface Threshold {
  second: number;
  minute: number;
  hour: number;
  day: number;
}

month & year are based on calendar, thus not customizable.

Example:

import {selectUnit} from '@formatjs/intl-utils';
selectUnit(Date.now() - 1000); // { value: -1, unit: 'second' }
selectUnit(Date.now() - 44000); // { value: -44, unit: 'second' }
selectUnit(Date.now() - 50000); // { value: 1, unit: 'minute' }

Caveats

selectUnit is meant to be a stepping stone from the old IntlRelativeFormat to the officially spec-ed Intl.RelativeTimeFormat. Therefore we don't recommend using this for an extended period of time because of ambiguous editorial issues such as:

From 2019/01/01 -> 2018/11/01 can technically be last year, 2 months ago or a quarter ago.
From 2019/01/02 6am to 2019/01/01 11pm can also be 7 hours ago or yesterday. Timezone further complicates the issue.

The examples above have not even tackled the differences in non-Gregorian calendars. There is an issue opened upstream in the spec that potentially introduces a best fit algorithm. Therefore, we recommend that you implement your own version of selectUnit that matches your editorial expectation. This will be removed in future releases.

Current Tags

3.8.4 ... latest (4 years ago)
3.6.2-alpha.0 ... next (4 years ago)

Intl Utils

API

selectUnit

Caveats

Current Tags

64 Versions