relative-time

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 53)

Formats JavaScript dates to relative time strings (e.g., "3 hours ago")

relative-time Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Relative Time

Formats JavaScript dates to localized **relative time strings** (e.g., "3 hours ago", "yesterday", "in 2 weeks").
It selects a **best‑fit unit** for you (seconds → minutes → hours → days → weeks → months → years) **and** uses the platform’s `Intl.RelativeTimeFormat` for localization.

- **High‑level**: `RelativeTime` → _resolve unit_ → format
- **Low‑level**: `RelativeTimeResolver` → _resolve only_ the `{ value, unit }`

Built on **Temporal** for precise date math and **Intl.RelativeTimeFormat** for i18n. That means you get the **same CLDR data** your runtime ships with—no locale bundles to download.

> **Why not just `Intl.RelativeTimeFormat`?**
> `Intl.RelativeTimeFormat` is intentionally **low level**: you must choose the unit yourself (e.g., day vs week) and then ask it to format the pair `{value, unit}`. This library adds the **unit resolver** layer on top—by design that’s out of scope for the built‑in API. (see more details at [tc39/proposal-intl-relative-time#14](https://github.com/tc39/proposal-intl-relative-time/issues/14))

## Install

```bash
npm install relative-time
```

### Temporal polyfill

This library expects **Temporal**. Use it where Temporal is available, or load the official polyfill:

```bash
npm install @js-temporal/polyfill
```

When using `@js-temporal/polyfill`, **inject** `Temporal` when constructing `RelativeTime`/`RelativeTimeResolver`:

```js
import RelativeTime, { RelativeTimeResolver } from "relative-time";
import { Temporal } from "@js-temporal/polyfill";

const rt = new RelativeTime({ Temporal });
// or:
const resolver = new RelativeTimeResolver({ Temporal });
```

## Quick start

```js
import RelativeTime from "relative-time";
// If needed:
// import { Temporal } from "@js-temporal/polyfill";

const rt = new RelativeTime(); // locale inferred from the runtime

const threeHoursAgo = Temporal.Now.plainDateTimeISO().subtract({ hours: 3 });
rt.format(threeHoursAgo);
// Output: "3 hours ago"

const pt = new RelativeTime("pt");
const oneHourAgo = Temporal.Now.plainDateTimeISO().subtract({ hours: 1 });
pt.format(oneHourAgo);
// Output: "há 1 hora"
```

### Time‑zone aware

```js
const rt = new RelativeTime();

const laDate = Temporal.ZonedDateTime.from(
  "2016-04-09T17:00:00-07:00[America/Los_Angeles]"
);
rt.format(laDate);
// Output: "yesterday"
// Assuming now is "2016-04-10T05:00:00-07:00[America/Los_Angeles]"

const berlinDate = Temporal.ZonedDateTime.from(
  "2016-04-10T02:00:00+02:00[Europe/Berlin]"
);
rt.format(berlinDate, { now: berlinNow });
// Output: "12 hours ago"
// Assuming now is "2016-04-10T14:00:00+02:00[Europe/Berlin]"
```

Use `Temporal.PlainDateTime` when you want to **ignore time‑zone rules** (local calendar math), and `Temporal.ZonedDateTime` when offset and DST **must** be respected.

### Resolver only

Use the resolver when you need just the unit/value.

```js
import { RelativeTimeResolver } from "relative-time";

// You can format this yourself or with Intl.RelativeTimeFormat
new Intl.RelativeTimeFormat(undefined, { numeric: "auto" }).format(value, unit);
// Output: "3 minutes ago"
```

## API

### `class RelativeTime` (default export)

High‑level formatter that **resolves the unit** and **formats** the string.

#### Constructor

```ts
new RelativeTime(
  locales?: string | string[],
  options?: Intl.RelativeTimeFormatOptions
)
```

- `locales` — same semantics as other `Intl` constructors (e.g., `"en"`, `["fr", "en"]`).
- `options` — forwarded to `Intl.RelativeTimeFormat` (e.g., `{ style: "short", numeric: "auto" }`).
  Tip: `numeric: "auto"` yields strings like “yesterday/tomorrow”; `numeric: "always"` gives “1 day ago / in 1 day”.

#### `format(date, options?) => string`

```ts
format(
  date: Temporal.PlainDateTime | Temporal.ZonedDateTime,
  options?: {
    now?: Temporal.PlainDateTime | Temporal.ZonedDateTime,
    unit?: "best-fit" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year"
  }
): string
```

- `date` — the target moment.
- `options.now` — reference moment (defaults to “now”, matched to `date`’s type).
- `options.unit` — force a specific unit or let the library decide with `"best-fit"` (default).

**How “best‑fit” works (conceptually)**

The resolver promotes units using _calendar boundaries_ and _configurable step-up thresholds_ (e.g., sec → min → hr → day → month). If the difference crosses a calendar day, you'll get _"yesterday"_ (instead of "20 hours ago"). But if it crosses midnight _without_ clearing the threshold, it stays in hours, e.g., _"3 hours ago"_ (instead of "yesterday").

---

### `class RelativeTimeResolver` (named export)

Low‑level **unit chooser**. Use it if you want the `{ value, unit }` pair to feed into your own formatter (including `Intl.RelativeTimeFormat` directly).

#### Constructor

```ts
new RelativeTimeResolver();
```

#### `resolve(date, options?) => { value: number, unit: RTFUnit }`

resolve(
  date: Temporal.PlainDateTime | Temporal.ZonedDateTime,
  options?: {
    now?: Temporal.PlainDateTime | Temporal.ZonedDateTime,
    unit?: "best-fit" | RTFUnit  // "best-fit" (default) or force a unit
  }
): { value: number; unit: RTFUnit }
```

**Example**

```js
import { RelativeTimeResolver } from "relative-time";

const r = new RelativeTimeResolver();
const target = Temporal.Now.plainDateTimeISO().add({ days: 6, hours: 5 });

const { value, unit } = r.resolve(target); // e.g., { value: 1, unit: "week" }

new Intl.RelativeTimeFormat("en", { numeric: "auto" }).format(value, unit);
// "next week"
```

## Using `Intl.RelativeTimeFormat` options

You can customize style and numeric behavior at construction:

```js
const rtShort = new RelativeTime("en", { style: "short", numeric: "always" });
rtShort.format(Temporal.Now.plainDateTimeISO().subtract({ day: 1 }));
// "1 day ago"
```

> `RelativeTime` is literally a thin wrapper over `Intl.RelativeTimeFormat` once a `{ value, unit }` has been resolved. You get the same pluralization and grammar your engine provides.

## When to use which

| You need…                         | Use                                | Why                                                           |
| --------------------------------- | ---------------------------------- | ------------------------------------------------------------- |
| “Just give me a localized string” | `RelativeTime`                     | Picks a sensible unit and formats it                          |
| `{ value, unit }` only            | `RelativeTimeResolver`             | Feed another formatter, build custom UIs, analytics, etc.     |
| Full control over unit and i18n   | `Intl.RelativeTimeFormat` directly | Low‑level by design; no unit resolution provided by the spec. |

## Examples

**Force a unit**

```js
const rt = new RelativeTime("en");
rt.format(Temporal.Now.plainDateTimeISO().subtract({ hours: 27 }), {
  unit: "hour",
});
// "27 hours ago"
```

**Different locales**

```js
new RelativeTime(["fr", "en"]).format(
  Temporal.Now.plainDateTimeISO().add({ minutes: 5 })
);
// "dans 5 minutes"
```

## Notes on accuracy

This project uses **Temporal** for differences (calendar‑aware) and **`Intl.RelativeTimeFormat`** for localization. That combination prevents common errors around DST, month lengths, and week boundaries that “approximate threshold” libraries can exhibit.

## Browser / runtime support

- Works wherever **Temporal** is available; otherwise include **`@js-temporal/polyfill`**.
- Uses your runtime’s **`Intl.RelativeTimeFormat`**, which has wide support in modern environments.

## FAQ

**Does this support quarters?**
No—units are: `second`, `minute`, `hour`, `day`, `week`, `month`, `year`.

**Why do I sometimes see “yesterday” instead of “1 day ago”?**
That comes from `numeric: "auto"` in `Intl.RelativeTimeFormat`. Switch to `numeric: "always"` if you prefer numbers only.

**How is this different from the TC39 proposal?**
This library’s resolver is the high‑level part **omitted on purpose** from the `Intl.RelativeTimeFormat` spec; the built‑in API only formats a supplied `{ value, unit }`. See the historical discussion around “best‑fit” in the proposal repo.

## Contributing

PRs and issues welcome!

## Appendix

### Relative time

In this library, we'll define relative time as what makes sense for expressions like "now", "2 days ago", "in 3 months", "last year", "yesterday", and so on. In a more formal definition, _relative time_ is an approximate date distance given a unit. This is, _relative time_ is the date distance of _a_ and _b_ ± error, where error < unit. Please, see the below examples of each unit for clarity.

#### second

```
                8:31:38.000         8:31:39.000         8:31:40.000         8:31:41.000
ms  | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
sec             |   e             d |   c             b |       a     N     |
                8:31:38             8:31:39             8:31:40             8:31:41

N: The assumed now
a: now / 0 seconds ago
b: 1 second ago
c: 1 second ago
d: 2 seconds ago
e: 2 seconds ago
```

#### minute

```
          8:28:00           8:29:00           8:30:00           8:31:00           8:32:00
sec |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
min       |     g        f  |     e        d  |     c        b  |        a  N     |
          8:28              8:29              8:30              8:31              8:32

N: The assumed now
a: 0 minutes ago
b: 1 minute ago
c: 1 minute ago
d: 2 minutes ago
e: 2 minutes ago
f: 3 minutes ago
g: 3 minutes ago
```

#### hour

```
          5:00              6:00              7:00              8:00              9:00
min |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
hr.       |     g        f  |     e        d  |     c        b  |     a  N        |
          5                 6                 7                 8                 9

N: The assumed now
a: 0 hours ago
b: 1 hour ago
c: 1 hour ago
d: 2 hours ago
e: 2 hours ago
f: 3 hours ago
g: 3 hours ago
```

#### day

```
       Mar 21, 00:00           Mar 22, 00:00           Mar 23, 00:00           Mar 24, 00:00
hr.  | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
day    | e                   d | c                   b |     a N               |
       Mar 21                  Mar 22                  Mar 23                  Mar 24

N: The assumed now
a: today / 0 days ago
b: yesterday / 1 day ago
c: yesterday / 1 day ago
d: 2 days ago
e: 2 days ago
```

#### week

N: The assumed now
a: this week
b: last week
c: last week
d: 2 weeks ago
e: 2 weeks ago
```

#### month

```
      Wk. 1       Wk. 5       Wk. 9          Wk. 14
wk.   |  |  |  |  |  |  |  |  |  |  |  |  |  |
mo.   |e         d | c        b|     a   N   |
      Jan          Feb         Mar           Apr

N: The assumed now
a: this month / 0 months ago
b: last month / 1 month ago
c: last month / 1 month ago
d: 2 months ago
e: 2 months ago
```

Note the months distances doesn't match weeks distance or days distance uniformly.

#### year

```
          Jan               Jan               Jan               Jan               Jan
mo. |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
yr.       |g             f  |e             d  |c             b  |a  N             |
          2013              2014              2015              2016              2017

N: The assumed now
a: this year / 0 years ago
b: last year / 1 year ago
c: last year / 1 year ago
d: 2 years ago
e: 2 years ago
f: 3 years ago
g: 3 years ago
```

Note that (although not shown by the above ruler), the years distances doesn't match weeks distance or days distance uniformly.

## License

relative-time

relative-time Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

relative-time

relative-time Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README