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.

Writing A Daytime Server In Node.js

I’ve previously written about using node.js as a simple UDP listener, now I thought I’d expand on this and give an example of a node.js application that works as both a UDP and TCP server.

A simple service that offers both UDP and TCP connections would be the Daytime Protocol, as defined in RFC 867. It listens to port 13 for both TCP and UDP connections, and returns the current date and time. Your local computer may well have this function enabled, to test the TCP version, you can simply telnet to port 13 and see what is returned.

telnet localhost 13

If you find you don’t have a local Daytime service running, try calling the one at time.ien.it, you should see something like this…

$ telnet time.ien.it 13
Trying 193.204.114.105...
Connected to ntp.ien.it.
Escape character is '^]'.
12 APR 2011 18:51:11 CEST
Connection closed by foreign host.

As you can see it simply returns the date and time before closing the connection.

We could write something like this very easily in node.js. In this case we’ll return the date in JavaScript’s UTC string format instead to keep it simple.

var net = require('net');
var port = 1300;
var now = function() {
  var date = new Date();
  return new Buffer(date.toUTCString() + "rn");
};
var tcpserver = net.createServer(function(c) {
  c.write(now());
  c.end();
});
tcpserver.listen(port);

We can test this by telneting to localhost on port 13

$ telnet localhost 1300
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Tue, 12 Apr 2011 17:17:55 GMT
Connection closed by foreign host.

Let’s take a quick detour into what the code is doing if you’ve not used node.js for any network programming before.

We require('net') so we can use node.js’s network socket support.

The now() function simply returns a Buffer with the current UTC date and time string in. A Buffer in node.js refers to the raw memory used behind the data, in this case our string with the date and time in.

Finally, we create the server, and add a callback function that is called when something connects to the socket. In this case we’re just writing out the contents of the now() function and ending the connection. Last but not least, we tell the socket which port to listen on.

We can see that this code works, but the Daytime protocol also offers a UDP service on the same port that can return the date and time string to a client.

Let’s add in some code to support this. We’ll assume our now() function and port variable are available already.

var dgram = require('dgram');
var udpserver = dgram.createSocket("udp4", function(msg, rinfo) {
  var daytime = now();
  udpserver.send(daytime, 0, daytime.length, rinfo.port, rinfo.address);
});
udpserver.bind(port);

So what is going on here? Well like the TCP code, we have to require('dgram'); to have access to node.js’s UDP support.

Next we create the socket and create a callback function that returns the date and time string back to the IP address and port of the calling computer. Finally we bind this to the port so we start listening for messages.

It’s harder to test a UDP server as we can’t telnet in, we will have to write a simple UDP client to send a blank message to the server and print out any replies to the console.

var dgram = require('dgram');
var message = new Buffer(" ");
var server_ip = '127.0.0.1';
var server_port = 43278;
var client = dgram.createSocket("udp4");
client.on('message', function (msg) {
  console.log(msg.toString());
  client.close();
});
client.send(message, 0, message.length, server_port, server_ip);

When you run this client on the same machine as your server you should get back the current date and time.

Here’s the final code for our Daytime server.

var net = require('net');
var dgram = require('dgram');
var port = 1300;
var now = function() {
  var date = new Date();
  return new Buffer(date.toUTCString() + "rn");
}
var tcpserver = net.createServer(function(c) {
  c.write(now());
  c.end();
});
tcpserver.listen(port);
var udpserver = dgram.createSocket("udp4", function(msg, rinfo) {
  var daytime = now();
  udpserver.send(daytime, 0, daytime.length, rinfo.port, rinfo.address);
});
udpserver.bind(port);

Writing A UDP Server Using Node.js

Previously, I’ve written about using node.js to send a heartbeat to a python server using a UDP datagram.

Of course you may not want to run Python if you using node.js so I thought I’d give you a quick run through on writing a UDP server using node.js.

The earlier heartbeat example sent a small message saying “PyHB” to a server listening on port 43278. This example will listen out for that message and show it on the console to prove it’s working.

The first thing we need to do is to require("dgram") to allow us access to the dgram library.

var dgram = require("dgram");

We now need to create a datagram socket to listen on, as we’re going to listen out for an IP4 datagram we create this of type udp4.

var server = dgram.createSocket("udp4");

Node.js lets us bind to events, and dgram gives us three, message, listening and close.

To listen for an event, we need to use the listening event. As with other JavaScript events, we can pass in a callback function to actually do something when the event is fired. In this case, we’ll just use display the incoming message on the console, along with some details of the server that sent it.

server.on("message", function (msg, rinfo) {
  console.log("server got: " + msg + " from " + rinfo.address + ":" + rinfo.port);
});

It’s also useful to know we’ve actually setup our socket correctly, so we can use the listening event to return a message to console that everything has been setup OK and is working.

server.on("listening", function () {
  var address = server.address();
  console.log("server listening " + address.address + ":" + address.port);
});

Finally we need to actually bind our socket to a port so it can start listening for messages. For this we have to use the bind method.

server.bind(43278);

Putting this all together we have the following code that can listen for UDP datagrams and show them on the console.

var dgram = require("dgram");
var server = dgram.createSocket("udp4");
server.on("message", function (msg, rinfo) {
  console.log("server got: " + msg + " from " + rinfo.address + ":" + rinfo.port);
});
server.on("listening", function () {
  var address = server.address();
  console.log("server listening " + address.address + ":" + address.port);
});
server.bind(43278);

I hope this has been a useful quick introduction to writing a UDP server in node.js.