Short-time-ago NPM

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

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:

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:

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);

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)`