Underscore.date is a javascript date library that helps create, manipulate, and format dates without extending the Date prototype.

Author: Tim Wood

Version: 0.5.2

Note: There are some api changes that will break your code when upgrading from 0.4.1 to 0.5.0. Read about the changes in the changelog at the bottom of the page.

Install with npm

npm install underscore.date

Usage

var _date = require('underscore.date');
console.log(_date('September 9 1999').fromNow());

If underscore exists, underscore.date will mix itself into the underscore namespace, so you can use as you would use an underscore function.

_.date('September 9 1999').fromNow();

Otherwise, you should use _date.

_date('September 9 1999').fromNow();

The library works by creating a _date() wrapper object. To create that wrapper, you can pass any of the following data types in.

_date(1300291340510)

An integer value representing the number of milliseconds since 1 January 1970 00:00:00 UTC.

_date(new Date(2010, 1, 14, 15, 25, 50, 125))

Any valid Date object. For more information on Date objects, see the JavaScript Date documentation at MDN

_date([2010, 1, 14, 15, 25, 50, 125])

An array mirroring the parameters passed into Date.UTC().

[year, month = 0, date = 1, hours = 0, minutes = 0, seconds = 0, milliseconds = 0]

Any value past the year is optional, and will default to the lowest possible number.

_date()

If no value is passed to a 'dateInput' parameter, it will default to the current time using new Date().

_date() === _date(new Date())

_date("Dec 25, 1995")

A string that can be parsed by Date.parse().

_date("12-25-1995", "MM-DD-YYYY")

A string and a format string. The second string will be used as the format to parse the first string.

The format parts are similar to the formats from _date().format()

Important: Parsing a string with a format is by far the slowest method of creating a date. If you have the ability to change the input, it is much faster (~15x) to use Unix timestamps.

underscore.date contains a number of utility functions for manipulating and formatting dates.

_date.add(object)

Adds time per the object passed in.

The object should have key value pairs as shown below.

{
    ms : 200, // milliseconds
    s : 10,   // seconds
    m : 10,   // minutes (note: lowercase)
    h : 2,    // hours
    d : 3,    // days
    M : 2,    // months (note: uppercase)
    y : 3     // years
}

All the parameters are optional. Also, there are no upper limits for the values, so you can overload any of the parameters.

{ ms : 1000000 } // a million milliseconds
{ d : 360 }      // 360 days

If the day of the month on the original date is greater than the number of days in the final month, the day of the month will change to the last day in the final month.

Example:

_date([2010, 0, 31])              // January 31
_date([2010, 0, 31]).add({M : 1}) // February 28

_date.subtract(object)

Functions the same as _date.add(), only using subtraction instead of addition.

Example:

_date([2010, 1, 28])                 // February 28
_date([2010, 1, 28]).subtract({M:1}) // January 28

_date.format(string)

Returns a human readable string based on the format string that was passed in.

var dateToFormat = new Date(2010, 1, 14, 15, 25, 50, 125);
_date(dateToFormat).format("dddd, MMMM Do YYYY, h:mm:ss a"); // "Sunday, February 14th 2010, 3:25:50 pm"
_date(dateToFormat).format("ddd, hA");                       // "Sun, 3PM"

The formats are created by creating a string of replacable characters.

_date.from(date, withoutSuffix:boolean, asMilliseconds:boolean)

Returns a string as relative time ('minutes ago', '5 months ago', etc).

You can pass anything that you would pass to _date() as the first parameter, or a _date() object.

_date([2007, 0, 29]).from(_date([2007, 0, 28])) // "a day ago"

You can pass true as the second parameter to return without the prefixes and suffixes.

_date([2007, 0, 29]).from(_date([2007, 0, 28]), true) // "a day"

You can pass true as the third parameter to return as milliseconds. The number of milliseconds returned will be positive if the date passed in is later than the first date, and negative if the date passed in is earlier.

_date([2007, 0, 29]).from(_date([2007, 0, 28]), true , true) // -86400000);
_date([2007, 0, 27]).from(_date([2007, 0, 28]), true , true) // 86400000);

The base strings for this function can be customized with _date.relativeTime.

The breakdown of which string is displayed when is outlined in the table below.

_date.fromNow(withoutSuffix:boolean, asMilliseconds:boolean)

Retuns the time from now.

A shortcut for _date.from(_date(), withoutSuffix:boolean, asMilliseconds:boolean).

Returns true if the year is a leap year, false if it is not

Examples :

_date([2000]).isLeapYear() // true
_date([2001]).isLeapYear() // false
_date([2100]).isLeapYear() // false

To customize the wording of _date.format() and _date.from(), the strings are exposed through the _date object. You can modify these however you see fit.

Examples :

_date.relativeTime.future = "%s from now";
_date.relativeTime.past = "%s in the past";

Or, put in the beginnin of your project, (the path to this file is inside the project. Point to them.)

require('./underscore.date.languages').portuguese();

Portuguese was the language choose in this example.

_date.relativeTime = {
    future: "in %s",
    past: "%s ago",
    s: "seconds",
    m: "a minute",
    mm: "%d minutes",
    h: "an hour",
    hh: "%d hours",
    d: "a day",
    dd: "%d days",
    M: "a month",
    MM: "%d months",
    y: "a year",
    yy: "%d years"
};

The strings used in _date.from().

future and past are used as the suffixes/prefixes.

For all these values, a single character refers to the singular, and an double character refers to the plural.

_date.weekdays = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];

An array of day names, starting with Sunday.

_date.weekdaysShort = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];

An array of abbreviated day names, starting with Sunday.

_date.months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];

An array of the names of the months, starting with January.

_date.monthsShort = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];

An array of the abbreviated names of the months, starting with January.

_date.ordinal = function (number) {
    var b = number % 10;
    return (~~ (number % 100 / 10) === 1) ? 'th' : 
        (b === 1) ? 'st' : 
        (b === 2) ? 'nd' : 
        (b === 3) ? 'rd' : 'th';
};

A function that returns a string to be appended to the number passed in. More information on ordinal numbers

Underscore.date unit tests

Underscore.date performance tests

The unit tests can also be run in node by running node test.js on the root folder.

Floor vs bitwiseor vs bitwisenor vs parseint

Switch/case vs object of functions lookup

Left zero filling

The folks over at date.js.

Everyone who helped with php.js date.

Ryan McGeary for his work on the jQuery timeago plugin.

Underscore.date is freely distributable under the terms of the MIT license.

Buxfix for issue 8 and issue 9.

Buxfix for issue 5.

Dropped the redundant _date.date() in favor of _date(). Removed _date.now(), as it is a duplicate of _date() with no parameters. Removed _date.isLeapYear(yearNuumber). Use _date([yearNumber]).isLeapYear() instead. Exposed customization options through the _date.relativeTime, _date.weekdays, _date.weekdaysShort, _date.months, _date.monthsShort, and _date.ordinal variables instead of the _date.customize() function.

Added date input formats for input strings.

Added underscore.date to npm. Removed dependancies on underscore.

Added 'z' and 'zz' to _.date().format(). Cleaned up some redundant code to trim off some bytes.

Cleaned up the namespace. Moved all date manipulation and display functions to the _.date() object.

Switched to the Underscore methodology of not mucking with the native objects' prototypes. Made chaining possible.

Changed date names to be a more pseudo standardized 'dddd, MMMM Do YYYY, h:mm:ss a'. Added Date.prototype functions add, subtract, isdst, and isleapyear.

Changed function names to be more concise. Changed date format from php date format to custom format.

Initial release