A tiny library that formats precise time differences as a vague/fuzzy time.
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.
3.3 kb unminified with comments, 1.1 kb minified or 0.6 kb minified+gzipped.
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. It is 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.
npm i vague-time
Or if you just want the git repo:
git clone firstname.lastname@example.org:philbooth/vagueTime.js.git
If you are running in
or another CommonJS-style
vagueTime.js like so:
var vagueTime = require'vague-time';
It also the supports the AMD-style format preferred by Require.js.
If you are
with an HTML
or neither of the above environments
the interface will be globally available
vagueTime.js exports a single public function,
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
Dateinstance denoting the origin point from which the vague time will be calculated. Defaults to
to: Timestamp or
Dateinstance denoting the target point to which the vague time will be calculated. Defaults to
units: String denoting the units that the
totimestamps are specified in. May be
's'for seconds or
'ms'for milliseconds. Defaults to
'ms'. This property has no effect when
Dateinstances rather than timestamps.
to is less than
the returned vague time will indicate
some point in the past.
to is greater than
it will indicate
some point in the future.
const vagueTime = require'vague-time';vagueTimegetfrom: 60to: 0units: 's'; // returns 'a minute ago'vagueTimegetfrom: 0to: 3600000units: 'ms'; // returns 'in an hour'vagueTimegetfrom: 2017 0 31to: 2016 10 30; // returns '2 months ago'
Install the dependencies:
Lint the code:
npm run lint
Run the tests:
Or, to run the tests in a web browser,
Support for languages
other than English
was removed in release
If you were relying on that stuff,
You may be interested in
the 1.x branch.