Design Primitives in Javascript: Example with Node.js

So here, as an example to bring this together, I'm going to implement a simple service over TCP/IP that returns the current date and time or a (pseudo) random number between 1 and 10.  To demonstrate the service, we'll telnet to the port on which the server runs and submit commands to the service via telnet.

To begin with, I'll cover the architecture and design of the service.  Then, I'll cover the components and how they're implemented, finally followed by how the service itself uses those components to implement the server.

Let's discuss the architecture of the service first.  From a requirements perspective, we're going to return the current date/time when requested, return a random number if requested, and handle unknown values without problems.  That gives us this command protocol:

date:             Retrieves a date
random:       Returns a randomly generated number

These commands are also case sensitive.  We'll also need to handle the case where we're delivered garbage.  The major components include:

Client:                             The client we'll use
Server:                            The server that'll generate the return values
Path:                               The communication path between client/server
Client Host:                    The host upon which the client will run
Server Host:                   The server host node

From a technology perspective, we've chosen:

Comm Protocol:  TCP/IP
Host:                     Localhost, running MacOS X

Other technology specific requirements include Node.js, for communication support, and telnet, to support the local client implementation.

This gives us an integrated technical system stack of a telnet client, running on localhost, attaching to a server instance built atop Node.js, again on the localhost, over TCP/IP.  Commands will be issued in ASCII from the client, where date returns the current date and time, random returns a random number, and all other commands return an unknown command indicator.

Design-wise, we'll put the server using these components:

server.js (script): This is the script that runs the server.  This will import the correct Node.js classes and bootstrap the server using functions from other modules and classes.  This script will depend on the main module and the net module from Node.js.
main.js (module): This is the module that contains all the entry point functions used by the server.js script.  It will also handle command parsing for the service.  This module expects server generator classes to implement the Generator interface.  It will depend on the date, random, and version modules.
date.js (module): This module will implement a class adhering to the Generator interface that returns the current date and time.
random.js(module): This module implements a generator class returning a random number between 1 and 10.
version.js(module): This module contains version information based on the Version interface.

The Generator and Version interfaces are:

interface Generator :
  generate(void) : string


interface Version :
  <<property>> major : int
  <<property>> minor : int
  <<property>> patch : int
  <<property>> status : string

Operationally, requests will be routed through the server script, into functions defined in main, which uses generator classes in date and random.  The server will be started from the command line (i.e. with the command node server.js) as will the client (i.g. from the commandline, telnet localhost 1337).

Node.js and Chrome read-eval-print-loops

Lately in putting together my module/namespace example in JavaScript, I've started using Node.js and its module system.  While working with it, I've started to use it's read-eval-print loop (REPL), it's been very handy.  I thought it'd be useful if I compared Node.js's REPL with the REPL I've used in Chrome (I believe that the one on Chrome is based on a similar loop in Firefox's Firebug).

So first, Chrome's REPL is packaged with it's developer tools.  Those tools are web-centric, as you'd expect, and to use them for JavaScript development you need to have an HTML file that pulls together all your JavaScript files.  It integrates well with JavaScript testing frameworks like Jasmine, and has a fabulous graphical JavaScript debugger.  Overall, the only downside of the Chrome REPL is that you need to use it via web-ish interfaces (e.g. you can load the HTML file from a filesystem, but you still need to have an HTML file in place, and your JavaScript files can't reference CommonJS or Node.js environmental artifacts like require(.)).

Node.js's REPL is handy because you can run JavaScript code directly from the command line, no browser required.  Shortcomings I'm running into currently include the lack of a unit testing environment for explicit command line use (Jasmine does claim to integrate with Node.js and other command line tools though) and a rougher debugger.  Node.js does have a command-line debugger that works just fine, but it's just not as slick as Chrome's graphical debugger.

I've currently transitioned to using Node.js's REPL, and in the future I'll experiment with Jasmine to see how well it integrates with Node.js's command line environment.

Node.js and Modules

One of the nifty things about JavaScript is that it's finally starting to get traction as a more general-purpose programming language.  Java, for instance, uses JavaScript as it's default scripting implementation language when you're using JSR 223 scripting in Java 6.  I suppose this is payback for Java's existence butchering JavaScript's name in the first place.  We also have serverside and general application frameworks beginning to pop up like Node.js and CommonJS (these are also just beginning to emerge, so if you're looking for some interesting open source project to work with, you should check them out).

In my namespacing example, I'm going to use node.js to put together a simple server offering some services via a simple homegrown protocol.  Before I do that, I'd like to touch on how you can use the require(.) facilities node.js provides.

So node.js uses the V8 JavaScript engine to provide event-based networking services.  It also provides a require(.) function that allows you to include other JavaScript files.  It's a bit more sophisticated than a simple include though.  It requires you do develop via a specified module standard CommonJS has put together.  Personally, I would have preferred a simple include type function, but hey, this works and it's what node.js uses, so it's good enough for me.

Basically, I'm going to create side-by-side modules for the server example.  You can do this too in your work if you're using JavaScript serverside for anything.   Anyway, say we have  a simple script file defining version information; we name this version.js:

exports.version = {

major: '1',

minor: '0',

patch: '1',

status: 'gold'

}

Note the exports object.  We're using an object literal in this case, something I covered in a previous post.  We add a property to that object that contains what we're exporting. Here, I've include that information in a property named version.  Then, in the primary script file:

version = require('./version').version;

var msg = 'version is: ' 

+ version.major + '.' 

+ version.minor + '.' 

+ version.patch + ' : ' 

+ version.status;

console.log(msg);

We use the require(.) function to import the library file.  In this example, this file is console.js and it's located right next to the version.js file.  Note that we use a relative path in the module import.  I also use the convention of specifically importing a property with the same name as the file.  This isn't a requirement.

Now require(.) does allow you some namespacing functionality, but in the example I'm going over I'm going to continue to use the module pattern within my library script files.  This isn't the only way to do this, nor would I claim it's the best, but it's what I like to do.

Next, I'll begin to go into the node.js server example.

Design Primitives in Javascript: Namespaces and Classes

We've defined a couple of different ways in which you can create namespaces in JavaScript.  So far though, we've been defining functions in those namespaces.  It's completely appropriate to do that - and frankly, being able to mix functions with classes in a namespace is a powerful facility most other mainstream object-oriented languages don't have.  Usually, this kind of functionality is emulated via static classes (i.e. classes with nothing but static methods).

So first, let's review how we define classes in JavaScript:

var MyClass = function(tag) {
  var tag_to_print = tag + ' - printed';
  this.print_tag = function() {
    console.log(tag_to_print);
  }
}


var cls = new MyClass('tag');
cls.print_tag();

This will print the string 'tag - printed' to the console.  Notice in this example we've created a private variable tag_to_print which we output via the print_tag() method (I'll refer to functions on a class or object as methods and standalone functions as functions from here on).

To include this class in a namespace, we'd define it like this:

var App = function() {
  var MyClass = function(tag) {
    var tag_to_print = tag + ' - printed';
    this.print_tag = function() {
      console.log(tag_to_print);
    }
  }
  return {
    Tagger: MyClass
  }
}();

You'd then create and use an instance of this class like so:

var cls = new App.Tagger('tag');
cls.print_tag();

You could also do something like this, if you don't like using full class names:

var Tagger = App.Tagger;
var cls = new Tagger('tag');
cls.print_tag();

You can also do this for namespaced functions, not just class definitions.  Furthermore, here, we've shown a class defined inside of the namespace. You can also assign previously defined classes from other files in a similar way where, for example, MyClass is defined in a previously read file, and the App namespace function becomes a simple object literal factory.

So at this point, we've covered how you can namespace both classes and functions, and how you can alias classes into a shorter form.  Next, I'll pull all this together into an example illustrating how you could use this in a real system.

Design Primitives in Javascript: Namespaces with Modules

So first, let's define this so-called module pattern I've referred to a couple of times.  You can google it too if you'd like, not a bad idea, but I'll try to give you some quick insight into how it works.

So functions have closures, I've mentioned this a few times so far.  Closures are essentially the ability of a function to remember what was going on when it was executed.  The other nice thing that closures allow is scoping for declared variables.  So how do we use this with a namespace then? Well, you still basically return a function literal, but you execute a function to do it, like this:

var Utils = function() {
  var date = new Date();
  return {
    print_date: function() { 
      console.log(date);
    }
  }
}()

Note the parenthesis at the end of the statement.  Basically, what you're doing is defining a function, and then immediately executing it, with a return value that's an object literal.  The cool thing about this particular implementation is that the date value you initialized when you executed the function is returned each and every time you call Util.print_date()! That's the voodoo of function closures in action.

We've also basically created a namespace in the above example as well a Utils namespace.  Here's another slightly more complicated example (here, Application is a pre-existing object):

Application.Logger = function() {
    
    if (!window.console) console = {};
    
    console.log = console.log || function(x){};
    console.warn = console.warn || function(x){};
    console.info = console.info || function(x) {};
    console.error = console.error || function(x) {};
    
    return {
        log:    function(msg) { console.log(msg) },
        warn:   function(msg) { console.warn(msg) },
        info:   function(msg) { console.info(msg) },
        error:  function(msg) { console.error(msg) }
    }
}()

Here, we've created a Logger namespace with associated functions for logging information, errors, and the like (thanks to Delan Azabani for the above logging abstraction approach).  Here, we're basically executing a constructor on the namespace we create that allows us to initialize the console object, and then we provide various wrapper functions on that object.

In some ways, these namespaces we're creating are similar to nested classes.  While certainly true, the key point to note is that while these may in fact be objects we're using to provide namespaces, they still provide the namespacing functionality we need by creating specific areas in which we can define unique entity names.

Design Primitives in Javascript: Namespaces with Object Literals

So most programming languages in common use today have some concept of namespaces.  Whether they're called packages, namespaces, or something else, they're ubiquitous as a design element.  JavaScript is no exception, it also has namespace features, based on either function closure (no surprise) via what's known as the module pattern, or object literals.  We'll start with the object literal approach; it's important that you understand this method first, as it's used obliquely with the module pattern, which we'll cover a bit later.

In the below examples, I'm using Google Chrome and the browser's integrated development tools.  Very similar to Firebug in Firefox.  This way, I can use the integrated JavaScript console to both execute arbitrary JavaScript and examine the current interpreter state.  I also have access to various output functions via the console object.

Object literals area a way to create object without a preexisting class definition.  The basic format consists of key/value pairs surrounded by braces and set to some variable:

var anon_obj = { 
  key1: value1,
  key2: value2, 
  ... , 
  keyN: valueN 
}

Now, there's some other interesting things about objects and object literals that I should mention before I proceed just to muddy my message a bit.  They can also be used associative arrays.  For example, I can initialize an anonymous object like this:

var my_hash = { 
  one: 1,
  two: 2, 
  three: 3
}

Now, if I run the following code sometime after defining my_hash, like so:

console.log(my_hash['one']);
var key ='one';
console.log(my_hash[key]);

I see the value 1 output twice in the console.  I can also add key/value pairs to my_hash like this:

my_hash['four'] = 4;

Now, you don't want to use general objects as keys.  It seems like you can do this:

var obj_key = new Object();
my_hash[obj_key] = 'arbitrary string';

but if you later do this:

var obj_new_key = new Object();
my_hash[obj_new_key] = 'macaroni';

you'll find that my_hash[obj_key] will also be set to 'macaroni'.  Just to make things more interesting, my_hash[2] and my_hash['2'] can be mapped to the same value as well!

Now back to using literals as namespacing constructs.  First, we're going to provide a namespace for a group of functions, like so:

var Functions = {
  print_name: function() { 
    console.log('Functions');
  },
print_time: function() { 
    console.log(new Date().getTime());
  },
print_date: function() {
    console.log(new Date());
  }
}

You'd invoke these functions using a syntax like Functions.print_name().  You could also pass this namespace into a function call as an argument like this:

function printer(ns) {
ns.print_name();
ns.print_date();
ns.print_time();
}
printer(Functions);

Remember, the function printer(ns) syntax I used above is in fact a shorthand for var printer = function(ns).  Personally, I'm usually on the fence as to which one to use; I like the latter because it makes clear that printer is in fact just a variable name that can receive different assignments after declaration, but the former is shorter and generally more clear, as most folks aren't going to reassign the printer variable to something else.

Object literals are pretty powerful, but they don't really allow us to do much besides assignment. Using the module pattern, we can use function closure to give us the ability to assemble our namespaces and provide namespace constructors as well as private variables - I'll cover this next.

Design Primitives in Javascript

So recently, I've been working on a project building a rich internet client using ExtJS.  I've enjoyed it, it's really given me an appreciation for JavaScript.  Now, first, JavaScript as a language is horribly named.  It's really a quite elegant, powerful language.  It has a limited syntax, which I find a plus honestly after getting used to it.  Furthermore, it has a distinctly functional nature.  Nothing like Erlang, say, or Clojure - in that it doesn't really pattern match function calls the same way, or have much use for recursion.  But it does treat functions as first class objects in the language, and it handles closure well.  It was named JavaScript to piggyback on Java at the time from what I understand, and they needed to add the 'script' because, well, Java was already taken after all.

One of the problems I initially had with JavaScript was learning how to organize my code.  I mentioned JavaScript had certain functional aspects, and though I had some experience using JavaScript in an object-oriented way, my understanding of the kinds of things you could really do with the language was pretty primitive.  I needed to bone up on how you could really create namespaces and class objects and so on in JavaScript.  I wanted to be able to organize the code I was slinging with what I saw in other libraries out there.

This is what I was able to pull together from searching the web, experimenting, and working through my own examples.

In the first sections, I'm going to cover how you create namespaces using either object literals or using the module pattern (you'll see this all the time if you look through various commercial or popular open source libraries).  I'll go over how they work and what they allow you to do.

Then I'll go over how you can define classes within namespaces, and how you can separate your files so that you have only a class or two per file.  Keep in mind, this makes the code easier to manage, but you'll need to do some post processing to appropriately concatenate the files into a single minimized file to make it as efficient as possible.

Finally, I'll pull it all together into a single somewhat contrived example that'll hopefully illustrate all the concepts in a meaningful way.