Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
64 lines (47 sloc) 1.49 KB


A small library that provides a few very useful methods for displaying dates, including a formatter and a parser.

build status


$ npm install dateable


var dateable = require('dateable');
var date = new Date(2009, 4, 23);

var str = dateable(date, 'MM/DD-YYYY, hh:mm');
// => 05/23-2012, 22:10

Parse a formatted date and return the original Date object

dateable.parse(str, 'MM/DD-YYYY, hh:mm');
// => Sat May 23 2009 00:00:00 GMT+0000 (CEST)

If you want to include text in the formatting, you need to escape it with either ' or ".

var format = '"I went to the moon a" dddd "in" MMMM, YYYY';

dateable(date, format);
// => I went to the moon a Saturday in May, 2009

You can also get the relative date, and the difference between dates.

dateable.when(new Date(2008, 4, 20));
// => 4 years ago
dateable.when(new Date(2020, 4, 30));
// => in 8 years
dateable.diff(new Date(2015), new Date());
// => 3 years


dateable(date, format)

Return formatted date

.parse(date, format)

Return original date from format

.when(date, [unit])

Returns relative date

.diff(start, end, [unit])

Returns the difference between the two dates


Set language


Based on ISO 8601 with some additions. See tests for examples.