# @formatjs/intl-utils

> Smartly determine best unit for relative time format

Latest version **3.8.4** (published 2020-08-17) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @formatjs/intl-utils
pnpm add @formatjs/intl-utils
yarn add @formatjs/intl-utils
bun add @formatjs/intl-utils
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 3.8.4 |
| Published | 2020-08-17 |
| First published | 2019-06-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 123.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 14752 |
| Author | Long Ho |
| Maintainers | longlho, pyrocat, redonkulus |
| Keywords | intl, i18n, relative, moment, format, date |

## Links

- npm: https://www.npmjs.com/package/@formatjs/intl-utils
- Repository: https://github.com/formatjs/formatjs
- Issues: https://github.com/formatjs/formatjs/issues
- npm.io page: https://npm.io/package/@formatjs/intl-utils

## Dependencies (1)

- [emojis-list](https://npm.io/package/emojis-list.md) ^3.0.0

## Alternatives

- [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads
- [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads
- [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads
- [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads
- [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads

## Recent versions

- 3.8.4 (latest) — 2020-08-17
- 3.6.2-alpha.0 (next) — 2020-07-14
- 3.8.3 — 2020-08-14
- 3.8.2 — 2020-07-24
- 3.8.1 — 2020-07-16
- 3.8.0 — 2020-07-14
- 3.7.0 — 2020-07-14
- 3.6.0 — 2020-07-03
- 3.5.0 — 2020-07-01
- 3.4.1 — 2020-06-23
- 3.4.0 — 2020-06-20
- 3.3.1 — 2020-06-04
- 3.3.0 — 2020-06-04
- 3.2.0 — 2020-06-03
- 3.1.0 — 2020-05-25
- … 49 more at https://npm.io/package/@formatjs/intl-utils/versions

## README

# Intl Utils

Provide i18n utilities.

[![npm Version](https://img.shields.io/npm/v/@formatjs/intl-utils.svg?style=flat-square)](https://www.npmjs.org/package/@formatjs/intl-utils)

## API

### selectUnit

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

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

where `thresholds` has the shape of:

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

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

Example:

```ts
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](https://github.com/tc39/proposal-intl-relative-time/issues/47). Therefore, we recommend that you implement your own version of `selectUnit` that matches your editorial expectation. This will be removed in future releases.

---
_Source: https://npm.io/package/@formatjs/intl-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
