README

vagueTime.js

A tiny JavaScript library that formats precise time differences as a vague/fuzzy time.

Why would I want that?
How tiny is it?
What doesn't it do?
What alternative libraries are there?
How do I install it?
How do I use it?
How do I set up the dev environment?
What changed between version 1.x and 2.x?
What license is it released under?

Why would I want that?

Displaying precise dates and times can make a website feel stuffy and formal. Using vague or fuzzy time phrases like 'just now' or '3 days ago' can contribute to a friendlier interface.

vagueTime.js provides a small, clean API for converting timestamps into user-friendly phrases, heavily supported by unit tests.

How tiny is it?

4.2 kb unminified with comments, 1.2 kb minified or 738 bytes minified+gzipped.

What doesn't it do?

Older versions of this library used to include translations into languages other than English. That translation process was both imperfect and a source of complexity, whereas the raison d'être of this library was to be small and simple. Localisation is a separate problem, better addressed by a dedicated solution. So, in an effort to do one thing well, the translation code was removed. Instead there is an option, raw, which returns a translation-friendly object containing the raw data. The original translations are still available in the 1.x branch and, of course, you are welcome to fork this repo if you preferred things how they were.

This library only converts in one direction: from dates/timestamps to strings. If you're interested in the opposite transformation, look elsewhere.

What alternative libraries are there?

How do I install it?

Via npm:

npm i vague-time --save

Or if you just want the git repo:

git clone git@gitlab.com:philbooth/vagueTime.js.git

How do I use it?

Loading the library

If you are running in Node.js, Browserify or another CommonJS-style environment, you can require vagueTime.js like so:

var vagueTime = require('vague-time');

It also the supports the AMD-style format preferred by Require.js.

If you are including vagueTime.js with an HTML <script> tag, or neither of the above environments are detected, the interface will be globally available as vagueTime.

Calling the exported functions

vagueTime.js exports a single public function, get, which returns a vague time string based on the argument(s) that you pass it.

The arguments are passed as properties on a single options object:

from: Timestamp or Date instance denoting the origin point from which the vague time will be calculated. Defaults to Date.now().
to: Timestamp or Date instance denoting the target point to which the vague time will be calculated. Defaults to Date.now().
units: String denoting the units that the from and to timestamps are specified in. May be 's' for seconds or 'ms' for milliseconds. Defaults to 'ms'. This property has no effect when from and to are Date instances rather than timestamps.
raw: If this option is truthy, the raw data will be returned as a translation-friendly object in the following format:
```
{
  v: number,
  u: string
}
```
Here, v is a number indicating the value of the vague time and u is a string indicating the units (either 'minute', 'hour', 'day', 'week', 'month' or 'year'). If the vague time is less than a minute, v will be 0 and u will be null.

Essentially, if to is less than from, the returned vague time will indicate some point in the past. If to is greater than from, it will indicate some point in the future.

Examples

const vagueTime = require('vague-time');

// returns 'in a minute'
vagueTime.get({
  to: Date.now() + 60000
});

// returns 'half an hour ago'
vagueTime.get({
  from: 1470001800,
  to: 1470000000,
  units: 's'
});

// returns 'in a couple of months'
vagueTime.get({
  from: new Date(2016, 10, 30),
  to: new Date(2017, 0, 31)
});

// returns { v: 2, u: 'month' }
vagueTime.get({
  from: new Date(2016, 10, 30),
  to: new Date(2017, 0, 31),
  raw: true
});

How do I set up the dev environment?

Install the dependencies:

npm i

Lint the code:

npm run lint

Run the tests:

npm test

Or, to run the tests in a web browser, open test/vagueTime.html.

What changed between version 1.x and 2.x?

Support for languages other than English was removed in release 2.0.0. If you were relying on that stuff, I'm sorry. You may be interested in the raw option or the 1.x branch.

What license is it released under?

MIT

Usage no npm install needed!