short-time-ago

!Language

This package exports a single function, timeAgo,
which describes the time elapsed between a given date and the current date
in a human readable format (for example, _"10 minutes ago"_, _"in 3 seconds"_).

Pros

- Simple API and usage
- Small size (< 1KB)
- No dependencies
- Works in the browser
- Written in Typescript
- Well tested and documented
- Accepts a custom date for the now anchor time

Cons

- Only en_US locale support.

API & Package Info

``typescript
timeAgo: (date: Date, now?: Date) => string;
`

- Explore the API on jsDocs.io
- View package contents on unpkg
- View repository on GitHub

Install

Using npm:

`
npm i short-time-ago
`

Using yarn:

`
yarn add short-time-ago
`

Using pnpm:

`
pnpm add short-time-ago
`

Usage

Basic usage:

`typescript
import { timeAgo } from "short-time-ago";

const myDate = new Date();
const description = timeAgo(myDate);

// Output: just now.
console.log(description);
`

Specifying a custom current date with the now parameter:

`typescript
import { timeAgo } from "short-time-ago";

const myDate = new Date("2019-01-01T00:00:00.000Z");
const now = new Date("2019-01-01T00:01:00.000Z");
const description = timeAgo(myDate, now);

// Output: 1 minute ago.
console.log(description);
`

`typescript
import { timeAgo } from "short-time-ago";

const myDate = new Date("2019-01-02T00:00:00.000Z");
const now = new Date("2019-01-01T00:00:00.000Z");
const description = timeAgo(myDate, now);

// Output: in 1 day.
console.log(description);
`

Output

The following table describes timeAgo's output.

| Time elapsed | Past output | Future output |
| --------------------- | ----------------- | ---------------- |
| < 1 second | just now | just now |
| < 1 minute | N second(s) ago | in N second(s) |
| < 1 hour | N minute(s) ago | in N minute(s) |
| < 1 day | N hour(s) ago | in N hour(s) |
| < 1 month (30.5 days) | N day(s) ago | in N day(s) |
| < 1 year (365 days) | N month(s) ago | in N month(s) |
| > 1 year | N year(s) ago | in N year(s) |

License

`
MIT
``

MIT License. See LICENSE file.

Copyright (c) 2025 Edoardo Scibona.