A small, no dependencies, Typescript utility to describe time differences in a human readable format (for example, '1 minute ago')
npm install 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"_).
- 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
- Only en_US locale support.
``typescript`
timeAgo: (date: Date, now?: Date) => string;
- Explore the API on jsDocs.io
- View package contents on unpkg
- View repository on GitHub
Using npm:
``
npm i short-time-ago
Using yarn:
``
yarn add short-time-ago
Using pnpm:
``
pnpm add short-time-ago
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);
The following table describes timeAgo's output.
| Time elapsed | Past output | Future output |
| --------------------- | ----------------- | ---------------- |
| < 1 second | just now | just now |N second(s) ago
| < 1 minute | | in N second(s) |N minute(s) ago
| < 1 hour | | in N minute(s) |N hour(s) ago
| < 1 day | | in N hour(s) |N day(s) ago
| < 1 month (30.5 days) | | in N day(s) |N month(s) ago
| < 1 year (365 days) | | in N month(s) |N year(s) ago
| > 1 year | | in N year(s) |
```
MIT
MIT License. See LICENSE file.
Copyright (c) 2025 Edoardo Scibona.