JavaScript Date, Time And Node.js

JavaScript Dates and times seem to pose a bit of problem to JavaScript developers. Looking at the access logs to my website, one of the most popular popular pages is about Writing a Daytime Server In Node.js. However, most people are actually searching for how to use a JavaScript Date in Node.js.

I thought I’d put together a few notes for those developers struggling use dates and times in node.js.

The good news is that as node.js is just a server side version of Google’s V8 JavaScript engine, node.js developers have full access to the JavaScript Date object.

A date in JavaScript is represented behind the scenes as the number of milliseconds since midnight on January 1st, 1970 (01-01-1970 00:00:00).

Initializing A JavaScript Date

To create a new Date object in node.js, or JavaScript in general, just call it’s initializer.

var now = new Date();
var now = new Date(milliseconds);
var now = new Date(dateString);
var now = new Date(jsonDate);
var now = new Date(year, month, day);
var now = new Date(year, month, day, hour, minute, second, millisecond);

dateString must be an RFC1123 compliant timestamp, I’ll come to jsonDate in just a minute.

Remember that Date objects can only be instantiated by calling Date or using it as a constructor; unlike other JavaScript object types, Date objects have no literal syntax.

Dates In JSON

Node.js offers great native JSON support, and that extends to encoding and decoding dates. Dates were not part of the original JSON specification, so it’s always been down to developers to decide on the best approach in the past. Things have changes, and now the standard is to use an ISO 8601 formatted date string.

To convert a date to JSON format, we can use the toJSON method of the Date object. This is a fairy new addition to the JavaScript language and is only supported in version 1.8.5 and above. Thankfully node.js supports this out of the box.

var now = new Date();
var jsonDate = now.toJSON();

To convert back, we just pass an ISO 8601 date string back into the JavaScript Date constructor.

var jsonDate = "2011-05-26T07:56:00.123Z";
var then = new Date(jsonDate);

Getting Specific Date Details

The JavaScript object provides various getters to extract information from the Date object. These include getDate to get the day of the month, getMonth to get the month (more on that in a minute), getFullYear to get the year (more on that in a minute as well), getHours, getMinutes, getSeconds, getMillisconds, as well several more.

There are a few gotcha’s here. The one that gets most people firt time, is that getMonth returns the current month, but months according to the Date object run between 0 and 11 instead of 1 to 12 as you are probably used to. The second is that the getYear method only returns a two digit date, you really want to use getFullYear as that returns a four digit date.

Setting Specific Date Details

To compliment the getters, there are mirror setter functions. These include setDate, setMonth, setFullYear, setHours. setMinutes, setSeconds, setMilliseconds as well as several more.

Manipulating Dates

You will probably want to manipulate the Date objects you have.

Let’s see what the time is in 6 hours time.

var myDate = new Date();
myDate.setHours(myDate.getHours() + 6);

But what about the time in 100 hours time? No problem…

var myDate = new Date();
myDate.setHours(myDate.getHours() + 100);

The JavaScript Date object is clever enough to change the date correctly.

I hope this has given you a few pointers on how to use dates and times in node.js.