Intl Utils

Provide i18n utilities.

API

selectUnit

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

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

where thresholds has the shape of:

1interface Threshold {
2  second: number;
3  minute: number;
4  hour: number;
5  day: number;
6}

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

Example:

1import {selectUnit} from '@formatjs/intl-utils';
2selectUnit(Date.now() - 1000); // { value: -1, unit: 'second' }
3selectUnit(Date.now() - 44000); // { value: -44, unit: 'second' }
4selectUnit(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.