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.

View on unpkg.

Install

Using npm:

npm i short-time-ago

Using yarn:

yarn add short-time-ago

CDN

UMD build:

<!-- Add UMD script -->
<script src="https://unpkg.com/short-time-ago"></script>

<!-- Usage -->
<script>
    const timeAgo = window['short-time-ago'].timeAgo;

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

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

Module build:

<script type="module">
    import { timeAgo } from 'https://unpkg.com/short-time-ago?module';

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

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

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

API

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

Explore the API on jsDocs.io.

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