A tiny JavaScript library that formats precise time differences as a vague/fuzzy time, e.g. '3 months ago', 'just now' or 'in 2 hours'. Supports English, German and French phrases.
- Why would I want that?
- What alternative libraries are there?
- How tiny is it?
- How do I install it?
- How do I use it?
- How do I set up the build environment?
- What license is it released under?
Displaying precise dates and times can give a website a formal and officious feel. Using fuzzy or vague time phrases like 'just now' or '2 days ago' can contribute to a much friendlier interface.
vagueTime.js provides a small, clean API for translating timestamps into those user-friendly phrases, heavily supported by unit tests. Vague time strings can be returned in English, German or French.
If this project isn't quite what you're looking for, you may be interested in vagueTime's big sister, vagueDate.js. Or if you would like to parse vague time strings rather than generate them, you should try Matthew Mueller's date or Tim Wood's moment.
5.4 kb unminified with comments, 1.8 kb minified, 0.8 kb minified + gzipped
Any of the following will do:
npm install vague-time
jam install vague-time
bower install vague-time
component install philbooth/vagueTime.js
git clone git@github.com:philbooth/vagueTime.js.git
f 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:
require.config({
paths: {
vague-time: 'vagueTime.js/src/vagueTime'
}
});
require([ 'vague-time' ], function (vagueTime) {
});
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
.
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 orDate
instance denoting the origin point from which the vague time will be calculated. Defaults toDate.now()
.to
: timestamp orDate
instance denoting the target point to which the vague time will be calculated. Defaults toDate.now()
.units
: string denoting the units that thefrom
andto
timestamps are specified in. May be's'
for seconds or'ms'
for milliseconds. Defaults to'ms'
. This property has no effect whenfrom
andto
areDate
instances rather than timestamps.lang
: string denoting the output language. May be'en'
(English),'de'
(German) or'fr'
(French). Defaults to'en'
.
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.
vagueTime.get({
from: 60,
to: 0,
units: 's'
}); // returns '1 minute ago'
vagueTime.get({
from: 0,
to: 60,
units: 's'
}); // returns 'in 1 minute'
vagueTime.get({
from: 7200,
to: 0,
units: 's'
}); // returns '2 hours ago'
vagueTime.get({
from: 0,
to: 7200,
units: 's',
lang: 'de'
}); // returns 'vor 2 Stunden'
vagueTime.get({
from: new Date(2015, 0, 3),
to: new Date(2014, 11, 31),
lang: 'de'
}); // returns 'in 3 Tagen'
vagueTime.get({
from: 0,
to: 259200,
units: 's',
lang: 'de'
}); // returns 'il y a 3 jours'
vagueTime.get({
from: new Date(2015, 0, 27),
to: new Date(2014, 11, 31),
lang: 'de'
}); // returns 'dans 4 semaines'
The build environment relies on
Node.js,
NPM,
JSHint,
Mocha,
Chai and
UglifyJS.
Assuming that you already have Node/NPM set up,
you just need to run npm install
to install all of the dependencies as listed in package.json
.
The unit tests are in test/vagueTime.js
.
You can run them with the command npm test
.
To run the tests in a web browser,
open test/vagueTime.html
.