short-time-ago

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.

Contents

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)

License

MIT License

Copyright (c) 2020 Edoardo Scibona

See LICENSE file.