The Art of Error

30 Jan 2014 | By Alex Young | Comments | Tags node errors
Error was originally a character in the hit video game, "Zelda".

I like to define a lot of objects that inherit from Error. I find it helps me to track down issues – post-mortem – but also to clearly handle expected errors. Sometimes writing error handling code feels like a chore, but it shouldn’t be an afterthought. Well-designed and well-tested errors will help you maintain projects, but also help users figure out what to do when things go wrong.

When it comes to using Error, I’ve found two bad practices that should be avoided:

  1. new Error is used instead of a subclass.
  2. Error is avoided altogether because “exceptions are bad”.

Let’s look at how to avoid these issues and use errors properly.

Subclassing Error

Subclassing errors is easy with Object.create or util.inherits (in Node). Here’s how you do it in Node:

var assert = require('assert');
var util = require('util');

function NotFound(message) {
  Error.call(this);
  this.message = message;
}

util.inherits(NotFound, Error);

var error = new NotFound('/bitcoin-wallet not found');

assert(error.message);
assert(error instanceof NotFound);
assert(error instanceof Error);
assert.equal(error instanceof RangeError, false);

The assertions check that the expected property was set (message), and error is an instance of NotFound, Error, but not RangeError.

If you were using this with Express, you could set other properties to make the error more useful. This is great when passing errors to next() in routes. When dealing with errors at the HTTP layer, I like to include a status code:

function NotFound(message) {
  Error.call(this);
  this.message = message;
  this.statusCode = 404;
}

Now you could have error handling middleware that handles errors in a more DRY fashion:

app.use(function(err, req, res, next) {
  console.error(err.stack);

  if (!err.statusCode || err.statusCode === 500) {
    emails.error({ err: err, req: req });
  }

  res.send(err.statusCode || 500, err.message);
});

This will send the HTTP status code to the browser, if available. It also only emails errors when the statusCode is 500 or not set. I took this from production code that generates emails when unusual things happen, and I don’t want to get notified about general errors like 401, 403, and 404.

The line that reads console.error(err.stack) won’t actually work as expected. In V8 platforms like Node and Chrome you can use Error.captureStackTrace(this, arguments.callee) in the error’s constructor to get the stack trace.

function NotFound(message) {
  Error.call(this);
  Error.captureStackTrace(this, arguments.callee);
  this.message = message;
  this.statusCode = 404;
}

When I was researching this article I noticed there’s a lot of confusion about inheriting from Error and capturing the stack. It’s hard to do it properly in every browser. If you want to read more, there’s a good Stack Overflow post about it here: What’s a good way to extend Error in JavaScript?.

Throwing and Catching Errors

You might have noticed I’ve been quiet about throw, and that’s because we hardly ever use it anymore. It’s more common to see errors passed as the first argument to a callback, or emitted as an 'error' event’s first argument.

If you’re using an API like this, you’ll probably use something like if (err) return handleError(err) at the top of your callback. You can also use if (err instanceof SpecificError) to add your own context specific error handling code.

Node developers usually avoid raising exceptions, but if you really think it’s necessary you can use throw new Error('I am Error') and then assert.throws in your tests. I find I hardly ever need to use throw.

Designing Error Objects

Once you start subclassing Error and adding your own properties, you can cause new problems by breaking the SOLID principles. To keep your errors clean, ensure an error class only has one responsibility – don’t make Swiss Army knife error objects, or trigger complex behaviours inside their constructors.

You should also create errors in logical places. If you’ve written a database layer, don’t raise the previous NotFound error from something that loads data from the database. In this case it would be better to have a Database.NotFound error object, or maybe just return undefined and then raise NotFound at the view layer.

Following the Liskov substitution principle also helps create maintainable error handling code. If you replace the previous NotFound error with a new class that has more context-specific information, then the existing code should still work. You’d break this rule if you somehow changed what notFound.statusCode did.

Conclusion

I create a lot of Error classes in my projects, but I rarely use throw and catch. You should set useful properties in error objects, but use such properties consistently. And, don’t cross the streams: HTTP errors have no place in your database code. Or for browser developers, Ajax errors have a place in code that talks to the server, but not code that processes Mustache templates.

Node Roundup: Node 0.11.11, Nightwatch.js, Hackify

29 Jan 2014 | By Alex Young | Comments | Tags node modules

Node 0.11.11

Node 0.11.11 was released today, and it’s quite a big update so I think they’re catching up after the holiday slowdown. The main binary dependencies have been updated (v8, HTTP parser, openssl, uv). There’s a huge amount of fixes for the core modules, including crypto, http, tls, and util.

Nightwatch.js

Nightwatch.js

Nightwatch.js (GitHub: beatfactor / nightwatch, License: MIT, npm: nightwatch) is a test framework that uses Selenium WebDriver. Tests are written as modules, so the exported functions are run as test cases. The first parameter is a client object, that has a chainable API for scripting access to webpages.

It includes JUnit XML support, so you can use it with a CI server like TeamCity. Both CSS selectors and XPath can be used.

If you’ve never used Selenium before, then take a look at the Nightwatch guide. It explains how it manages the Selenium server and browser instances.

Hackify

Hackify (GitHub: hackify, License: MIT, npm: hackify), by Michael Dausmann, is a collaborative code editor that features a permission system, and chat. It feels like Google Drive for programming.

The server uses Express, Socket.IO, and Redis. It’s written like a fairly typical Express application, with route separation and ejs templates.

jQuery 1.11 and 2.1, Backbone.global

28 Jan 2014 | By Alex Young | Comments | Tags jquery backbone

jQuery 1.11 and 2.1 Released

jQuery 1.11 and 2.1 have been released:

both the 1.x and 2.x branches of jQuery support all recent modern browsers and have the same API. The 1.x branch, this time 1.11.0, adds support for the older versions of Internet Explorer (IE6, 7, and 8). The 2.x branch, today played by 2.1.0, adds support for non-traditional web environments like node.js and browser plugins for Chrome and Firefox.

Another interesting point from the release notes was this paragraph about source map problems:

This release does not contain the sourcemap comment in the minified file. Sourcemaps have proven to be a very problematic and puzzling thing to developers, spawning hundreds of confused developers on forums like StackOverflow and causing some to think jQuery itself was broken.

I’ve noticed source maps confuse CoffeeScript developers as well, so this isn’t surprising. The tools seem solid – Chrome’s implementation has worked for me in the past, but the concept itself isn’t entirely intuitive.

The Node/browserify support is handy – that particular change was ticket 14677.

Backbone.global

Backbone.global (GitHub: DarrylD / Backbone.global, License: MIT) allows you to listen to global events in a Backbone.js application. It changes Backbone.View.prototype.delegateEvents to emit events on a global event bus, which makes it easier to hook into events for things like testing or logging.

v8js, Angular Foundation

27 Jan 2014 | By Alex Young | Comments | Tags php angular ui

v8js

On Friday I wrote about Uniter, which converts PHP to JavaScript. But what about running JavaScript in PHP? C. Scott Ananian sent in v8js (GitHub: preillyme / v8js, License: MIT), a PHP extension that lets you run JavaScript inside a PHP application.

It has both PHP and JavaScript APIs, so you can do things like var_dump in JavaScript. In the PHP side, you can evaluate JavaScript with $v8->executeString().

This project actually uses V8, and you can restrict JavaScript based on time and memory usage.

Angular Foundation

Angular Foundation

Angular Foundation (GitHub: madmimi / angular-foundation, License: MIT) is a Foundation port of the AngularUI bootstrap project.

We are aiming at providing a set of AngularJS directives based on Foundation’s markup and CSS. The goal is to provide native AngularJS directives without any dependency on jQuery or Foundation’s JavaScript. It is often better to rewrite an existing JavaScript code and create a new, pure AngularJS directive. Most of the time the resulting directive is smaller as compared to the orginal JavaScript code size and better integrated into the AngularJS ecosystem.

The documentation explains what Foundation components are supported, and shows how to use them as AngularJS directives. The authors created it after they noticed people on Stack Overflow asking about AngularJS directives for Foundation, and finding the existing solutions less complete.

Uniter, Chai Webdriver, Gamedev.js Weekly

24 Jan 2014 | By Alex Young | Comments | Tags php testing games

Uniter

When we run our yearly survey, I’ve noticed PHP is popular with our readers. So here’s something that you might either love, or consider arcane blasphemy: Uniter (GitHub: asmblah / uniter, License: MIT), a JavaScript to PHP source-to-source compiler:

Uniter allows you to execute PHP in the browser or in Node.js. As an on-the-fly recompiling interpreter (or transpiler) it results in the closest possible translation from PHP to native JavaScript code.

It includes Mocha unit tests and should run in IE 9 or above. It currently supports most of PHP’s keywords, and even has basic class support. The demo is interactive, so you can try editing the PHP source to see what happens.

Chai Webdriver

Chai Webdriver (GitHub: goodeggs / chai-webdriver, License: MIT, npm: chai-webdriver) by Max Edmands is a Chai plugin for making markup-based assertions when using webdriver. For example:

// Start with a webdriver instance:
var sw = require('selenium-webdriver');
var driver = new sw.Builder()
  .withCapabilities(sw.Capabilities.chrome())
  .build()

// And then...
var chai = require('chai');
var chaiWebdriver = require('chai-webdriver');
chai.use chaiWebdriver(driver);

// And you're good to go!
driver.get('http://github.com');
chai.expect('#site-container h1.heading').dom.to.not.contain.text("I'm a kitty!");

It works with Selenium, chromedriver, PhantomJS, and SauceLabs.

Gamedev.js Weekly

Gamedev.js Weekly is a weekly newsletter of JavaScript game-related news. There’s an archive so you can preview it before signing up.

JellyReader: Dropbox/Google Drive Feed Reader

23 Jan 2014 | By Alex Young | Comments | Tags angularjs jquery apps services

Ray Wang sent in JellyReader (GitHub: NimbusBase / jellyreader, License: MIT), an entirely client-side feed reader that is powered by Google Drive and Dropbox. NimbusBase has been used to unify access to Google Drive and Dropbox, so the data is ultimately stored as flat files.

JellyReader itself is implemented with jQuery and AngularJS. It allows you to add feeds, view entries, toggle the read state, and you can also star your favourite items. I tried it out with my Dropbox account, and Dropbox states that the application only has access to an “app” folder:

Dropbox

I added DailyJS to it:

Jelly add feed

And the stories are rendered as you might expect:

Jelly feed view

After playing around with the web interface for a while, I wondered what the files on Dropbox looked like. Each data collection is serialised in a directory, and there is a file per item. So feeds have a directory, and stories do as well. UUIDs are used to ensure the filenames don’t clash.

Dropbox

Presumably NimbusBase data has the same structure on Google Drive.

The JellyReader source uses lots of third party components, including jFeed which I haven’t seen for a few years. I actually like the flat file approach for personal, self-hosted applications like this, although it would be interesting to see a comparison with a Dropbox Datastore implementation.

Node Roundup: Nodemon 1.0, Prana, termcoin, node-bitwise-xor

22 Jan 2014 | By Alex Young | Comments | Tags node modules bitcoin mongodb

Nodemon 1.0

Nodemon

I noticed Nodemon 1.0 was released this week (GitHub: remy / nodemon, License: MIT, npm: nodemon). This update includes local and global configuration files, execMap for mapping file extensions to programs, and some changes to the overall architecture of the project. You can now require Nodemon, and tests have been added.

Prana

Prana (GitHub: recidive / prana, License: MIT, npm: prana) by Henrique Recidive is a small framework for Node applications. Prana application objects are EventEmitters, and Prana “types” emit events as well.

It combines an ODM system with a plugin system, and currently persists data to memory or MongoDB. The author has included some examples which you can find in prana/examples, and one of them uses Express. The module’s code itself has detailed comments, and the readme is solid too.

termcoin

termcoin (GitHub: chjj / termcoin, License: MIT, npm: termcoin) by Christopher Jeffrey is a terminal Bitcoin client with a command-line interface based on blessed. It requires bitcoind to work, and looks really cool in the screenshots.

node-bitwise-xor

Stanislas Marion sent in node-bitwise-xor (GitHub: czzarr / node-bitwise-xor, License: MIT, npm: bitwise-xor), a module for performing a bitwise XOR on two buffers or strings. It iterates over each element with ^, taking into account the length to ensure each item is changed.

Contra, jquery.onoff, jQuery 1.11.0 RC1 and 2.1.0 RC1

21 Jan 2014 | By Alex Young | Comments | Tags jquery plugins ui flow-control async

Contra

Contra

Contra (GitHub: bevacqua / contra, License: MIT, npm: contra, Bower: contra) by Nicolas Bevacqua is a flow control library, similar to async, but more suited to client-side development.

It has three sets of methods: flow control, functional, and uncategorized. The flow control methods are for executing groups of functions, like λ.waterfall(tasks, done). The functional methods are a subset of what you might expect to find in Underscore.js – λ.each and λ.filter for example. I noticed that λ.each can handle both arrays and objects, so it’s different to forEach.

Each method can be exported separately, so you could just pull in a single method if you wanted to. It has Mocha tests, and can be installed with Bower.

jquery.onoff

jquery.onoff (GitHub: timmywil / jquery.onoff, License: MIT) by Timmy Willison is a toggle switch that uses checkboxes. It supports IE 9 and above, and can be loaded with an AMD loader.

Although it’s a relatively simple project, Timmy has included tests, and a Grunt build script.

jQuery 1.11.0 RC1 and 2.1.0 RC1

jQuery 1.11.0 RC1 and 2.1.0 RC1 have been released. These releases are maintenance releases, so there aren’t any API changes.

The announcement notes that these releases should work properly with Browserify, and can be installed using npm.

A Node Interpreter for iOS

20 Jan 2014 | By Alex Young | Comments | Tags node apps iOS
Nodeapp: Node for JavaScriptCore.

Back in December I wrote about Nodelike, which aims to bring Node to iOS 7 and Mac OS X through JavaScriptCore. The iOS app has now been released as Node - JavaScript Interpreter, which you can download from the App Store. You can also view the source at node-app / Interpreter.

The app itself is currently quite simple. You can load most of the core modules, like assert, events, and net, but executing code removes it from the editor. It’s literally an interpreter – a GUI REPL, rather than a way to write Node on the go.

It includes browsable documentation, so you could use it to verify ideas, or more importantly to help you learn Node. It has a lot of potential as a learning tool – combined with an eBook it would be a great way to execute examples on an iOS device, particularly as you could tweak the code to figure it out.

Interpreters in iOS. Now I've seen everything.

This would also let people take back those wasted commuter hours. Rather than playing Candy Crush Saga you could boost your Node skills!

Cerebro, Snowmen War, Cube Game

17 Jan 2014 | By Alex Young | Comments | Tags webgl games google

Cerebro

Cerebro

Cerebro is a WebGL visualisation of Google Analytics data, created by Vetrenko Maxim. You can use the author’s Google Analytics data, or your own – the project isn’t open source, so I decided to use the sample data.

It supports Leap Motion input, and uses three.js, sparks.js, and dancer.js for audio. I couldn’t get it working in Firefox, but it worked in Chrome.

Snowmen War

Snowmen War

Snowmen War (License: CC BY-NC 3.0) by Tanguy Sauvin and Claire Thibault is a WebGL game with some pretty extreme text. When the game starts, you’re warned that “THEY WILL KILL YOU”, and if you’re hit too many times the game over screen simply states “YOU’RE DEAD.” It’s blunt, which is amusing next to the slightly surreal snowmen in outer space visuals.

If you view the project’s source you can see the game engine, which uses Cannon.js, and plenty of Mr.doob’s libraries.

Cube Game

Cube Game

Mark Vasilkov wanted to make something with Goo Engine, so he came up with Cube Game. His advice is to mash the spacebar repeatedly until you win, but I found it was more playable when I realised it’s possible to slide under some of tile-like blocks.

Declarative Graphics

16 Jan 2014 | By Alex Young | Comments | Tags graphics animations reactive svg

Whenever I hear the term ‘reactive’, I immediately think about data-driven forms and widgets. Markup isn’t just used for HTML forms and widgets, however: SVG is a markup language, so why not use reactive programming techniques to generate data-driven graphics?

That’s the goal of Paths.js (GitHub: andreaferretti / paths-js, License: Apache 2.0, bower: paths-js), by Andrea Ferretti. It features a chainable API for generating SVG paths:

var path = Path()
  .moveto(10, 20)
  .lineto(30, 50)
  .lineto(25, 28)
  .qcurveto(27, 30, 32, 27)
  .closepath();

Calling path.print() returns the relevant markup. This can then be used with a templating language like Handlebars or mustache.js: templates/line.html.

This example is from the Paths.js demo (GitHub: andreaferretti / paths-js-demo). The demo uses Ractive.js to bind JSON data to UI controls and charts. It has several graphs with animations, and uses instances of Ractive together with instances of Path to create a clean, interactive data-driven UI.

Reactive Pokémon stats.

I like the combination of modern templating languages, SVG, and Ractive.js in Andrea’s demo. The Paths.js API makes generating SVG less tedious than it could be, and various charts are included that you can use to get started quickly.

If you like the sound of Ractive.js, then take a look at the Ractive.js demos, which include some SVG examples.

Node Roundup: TJ Fontaine Takes Over, Conductance, Easymongo, Schema-Inspector

15 Jan 2014 | By Alex Young | Comments | Tags node modules frameworks mongodb schema

The Next Phase of Node.js

In The Next Phase of Node.js, Isaac Z. Schlueter has announced that TJ Fontaine is now the Node project lead:

Anyone who’s been close to the core project knows that he’s been effectively leading the project for a while now, so we’re making it official. Effective immediately, TJ Fontaine is the Node.js project lead. I will remain a Node core committer, and expect to continue to contribute to the project in that role. My primary focus, however, will be npm.

Isaac also said he’s founding npm, Inc., to allow him to focus on npm and develop related products:

I’ll be sharing many more details soon about exactly how this is going to work, and what we’ll be offering. For now, suffice it to say that everything currently free will remain free, and everything currently flaky will get less flaky. Pursuing new revenue is how we can keep providing the npm registry service in a long-term sustainable way, and it has to be done very carefully so that we don’t damage what we’ve all built together.

Recently, there was an initiative by Nodejitsu to drive support and funding for npm, resulting in over $300,000 being raised. It’ll be interesting to see how this all ties together over the next year.

Congratulations and good luck to TJ Fontaine!

Conductance

Conductance

Conductance (GitHub: onilabs / conductance, License: GPL, npm: conductance) from Oni Labs is a web application server with a UI toolkit and a module system that’s compatible with client-side code.

It’s built on Stratified JavaScript, by the same company, which adds new language primitives for block lambdas, destructuring data, arrow function syntax, and more.

Conductance already has a detailed tutorial, and there’s an API guide as well.

Easymongo

Easymongo (GitHub: meritt / easymongo, License: MIT, npm: easymongo) by Alexey Simonenko is a wrapper around the native Node MongoDB driver. It has a clean, idiomatic API, and relies on plain old objects instead of models.

It has Mocha tests, and the API is documented in the readme. Basic use looks like this:

var options = {
  dbname: 'test'
};

var mongo = new require('easymongo')(options);
var users = mongo.collection('users');

var data = { name: 'Alexey', surname: 'Simonenko', url: 'http://simonenko.su' };
users.save(data, function(error, results) {
  // Returns a new document (array).
  console.log(results);
});

users.find({ name: 'Alexey' }, { limit: 1 }, function(error, results) {
  // Always return array of documents.
  console.log(results);
});

Schema-Inspector

What do you do when you’re using simple objects without an ORM layer? You use schemas to validate your user input! Schema-Inspector (GitHub: Atinux / schema-inspector, License: MIT, npm: schema-inspector, Bower: schema-inspector) by Sebastien Chopin is a JavaScript object validator that works in browsers and Node.

Given a suitable schema, you can validate objects like this: inspector.validate(schema, candidate). It can also be called asynchronously, which allows you to report issues with this.report inside functions in the schema.

It has tests written with Mocha, and a healthy amount of API documentation in the readme.

The State of jQuery, jQuery.whenLive, jTableScroll

14 Jan 2014 | By Alex Young | Comments | Tags jquery plugins

The State of jQuery 2014

The State of jQuery 2014 was posted to the jQuery blog yesterday by Dave Methvin. It basically covers jQuery’s growth through 2013, and includes a comment about how jQuery shouldn’t just be used for routing around broken DOM APIs:

People should be continuing to use jQuery because it’s a powerful way to implement designs and provides a vibrant ecosystem of useful plugins, not because the native DOM APIs are broken, verbose, or inconsistent. That’s why we participate in the standards process through bodies such as the W3C and ECMA.

jQuery.whenLive

jQuery.whenLive (GitHub: tkambler / whenLive, License: MIT, Bower: tkambler/whenLive) by Tim Ambler allows you to track when elements are inserted into the DOM tree, with a focus on performance:

When supported, $.whenLive leverages the browser’s MutationObserver notification system. In the event that Mutation Observers are unavailable, $.whenLive leverages the relatively new requestAnimationFrame function.

This seems like a clever way of deferring behaviour until potentially complex components are ready.

jTableScroll

jTableScroll (GitHub: mike-allison / jTableScroll, License: MIT) by Mike Allison is a plugin for adding scrollbars to tables, and it retains static headers and footers.

It calculates the width and height then wraps parts of the table in divs, applying the necessary overflow styles based on size options: $('#tableToScroll').jTableScroll({ width: 300, height: 300 }).

The header and footer are cloned and moved by looking for the thead and tbody elements, so you’ll need a well-structured table. It can be installed with nuget.

jide.js, Matchmedia-ng

13 Jan 2014 | By Alex Young | Comments | Tags angularjs ui matchMedia

jide.js

jide.js (GitHub: jidesoft / jidejs, License: MIT) from JIDE Software is a toolkit for HTML5 UI controls. The authors have embraced RequireJS, and the API is based around constructor functions that accept objects. Properties and values are observable, so UI components can react to data model changes. Layouts are also supported, which are stackable panes reminiscent of desktop UI toolkits.

There are tutorials for using jide.js with Bower and Yeoman, so if you want to create a quick project you can type npm install -g generator-jidejs and then yo jidejs.

Here’s an example of how to create a button with jide.js:

require([
  'jidejs/ui/control/Button'
], function(Button) {
  new Button({
    // define the text property
    text: 'Click the button',
    // define event listeners
    on: {
      // the 'action' event is fired when the button is clicked
      action: function() {
        alert('Hello jide.js');
      }
    }
  });
});

Matchmedia-ng

Matchmedia-ng (GitHub: AnalogJ / matchmedia-ng, License: MIT) by Jason Kulatunga is a set of AngularJS bindings for window.matchMedia. That means you can easily branch on mobile devices, or for printed content:

matchmedia.on('tv and (min-width: 700px) and (orientation: landscape)', function(mediaQueryList) {
  console.log(mediaQueryList.matches);
});

There’s also a matchMedia polyfill written by Paul Irish.

WebGL Spaceship Tutorial, Voxel Mars, particle-excess-demo

10 Jan 2014 | By Alex Young | Comments | Tags webgl tutorials graphics space science

WebGL Spaceship Tutorial

WebGL Spaceship Tutorial

Jerome Etienne shared Game Workshop: Let’s Do a Fighting Spaceship Minigame Together – a talk about building a little game with three.js and the Web Audio API. It includes slides, a video of the talk, and a demo.

Voxel Mars

Voxel Mars

Voxel Mars (GitHub: rachel-carvalho / voxel-mars, License: MIT) by Rachel Carvalho uses NASA data to generate Martian terrain, allowing you to run around a WebGL version of Mars.

As you move it displays your position on a map, and also shows the longitude and latitude. Therefore, your challenge (should you choose to accept it), is to get to the top of Olympus Mons!

The rendering style makes it look a little bit like Minecraft, and one of the author’s ideas sounds like an amazingly interesting take on that genre:

a science-based (no dragons) survival mode on which you have to generate your oxygen and fuel, extract your water, grow your food, make martian bricks, etc

particle-excess-demo

Particle Excess

Hugh Kennedy sent in particle-excess-demo (GitHub: hughsk / particle-excess-demo, License: MIT):

The particle simulation is running on the GPU to handle 262,144 particles in real time. It’s a pretty standard technique these days, but it could be helpful as a reference for some. No three.js, just modules.

If you look at the source you’ll see how shaders can be used to create interesting particle effects.

Is Koa the Future of Node Frameworks?

09 Jan 2014 | By Alex Young | Comments | Tags node modules es6

Are you tired of callback wrangling for web middleware? Koa (GitHub: koajs / koa, License: MIT, npm: koa) is a new web framework by TJ Holowaychuk, Jonathan Ong, and Julian Gruber that embraces ES6 generators down to the core. Gone is the next parameter in Express, replaced by yield next which can be called in a synchronous style.

With generators we can achieve “true” middleware. Contrasting Connect’s implementation which simply passes control through series of functions until one returns, Koa yields “downstream”, then control flows back “upstream”.

You’ll need Node 0.11.9 or above to use Koa, and the node command must be invoked with the --harmony flag. The use of generators is partly enhanced by TJ’s Co module, so if you’re not intimately familiar with ES6 promises be aware that Co is used.

Here’s an example: the app.callback method returns a handler that is compatible with Node’s http.createServer method, and uses co:

app.callback = function(){
  var mw = [respond].concat(this.middleware);
  var gen = compose(mw);
  var fn = co(gen);
  var self = this;

  return function(req, res){
    var ctx = self.createContext(req, res);
    onSocketError(ctx, ctx.onerror);
    fn.call(ctx, ctx.onerror);
  }
};

This example is from Koa’s source, and allows the following to work:

var koa = require('koa');
var app = koa();
app.listen(3000);

// Equivalent: http.createServer(app.callback()).listen(3000);

The Request Response Pattern

The key to making solid Node web applications is to realise and exploit the fact Node speaks HTTP. Contrast this to PHP or ASP, where “pages” execute and generate output. Those req and res objects are there for a reason: Express and similar frameworks are built on Node’s http core module, and the http module’s API is based around these request and response objects.

I like thinking in terms of HTTP requests and responses – it gives me the sense that I’m dealing with HTTP “functions” that take input and transform somehow. That makes it easier for me to test my web apps, and I’ve been comfortable working this way since I discovered Express.

In Koa things are slightly different:

A Koa Context encapsulates node’s request and response objects into a single object which provides many helpful methods for writing web applications and APIs.

While it’s true that Express decorates the request and response objects, Koa goes further by abstracting them. You can still get at the request and response, and there’s also a Koa request and response as well:

app.use(function *(){
  this; // is the Context
  this.request; // is a koa Request
  this.response; // is a koa Response
  this.req; // Node's request
  this.res; // Node's response
});

Notice that this is significant – you may have seen something similar in jQuery callbacks. I think it was clever of Koa’s authors to execute middleware from within a “context”, because it makes sense semantically. The current context has aliases to commonly accessed request and response properties, so the average Koa middleware has less indirection and looks lean and clean.

Understanding Yield

I realise that the advantages of generators in middleware might not be obvious at first. The best example I can think of from Koa’s documentation is measuring response time. This example yields early, allowing the response time to be measured:

// x-response-time

app.use(function *(next){
  var start = new Date;
  yield next;
  var ms = new Date - start;
  this.set('X-Response-Time', ms + 'ms');
});

The start time is recorded, then execution is deferred to the next item of middleware in the stack with yield next. This all “unwinds” at the end of the request, so as long as the x-response-time was the first item, execution will continue after yield next. That means var ms = new Date - start; will correctly measure the elapsed time.

I think many of us have struggled to stack middleware in meaningful ways, and this could make our code more readable. Think about it like this: a single function can encapsulate the entire intent of the middleware.

Future

It might be that the dependence on Node 0.11 and our investment in existing frameworks will hold back Koa’s adoption. However, remember that you can mount entire applications as middleware in Connect, so what’s to stop you from mounting a Koa app inside your existing Express apps, once generators are standard in your production version of Node?

Even if you don’t switch to Koa, you should start thinking about how to use generators, and I think middleware is a sensible place to explore their implications.

Node Roundup: Faucet, Node Compiler, Tumblr

08 Jan 2014 | By Alex Young | Comments | Tags node modules testing tap

Faucet

Faucet (GitHub: substack / faucet, License: MIT, npm: faucet) by Substack is a human-readable TAP summariser. You can pipe TAP text into the faucet command-line script, and it’ll generate prettier yet concise output.

If you type faucet, JavaScript files in test/ will be executed using tape and then automatically piped through faucet.

Substack has created some nice animated gifs that show what the results look like under various conditions. One of them even shows Mocha using tap through the -R tap command-line option.

Node Compiler

Node Compiler

Sonny Lazuardi sent in Node Compiler (GitHub: sonnylazuardi / node-compiler, License: MIT), a web-based tool for building C++. It uses g++ with execSync, wrapped up with an Express-based API.

The web interface uses the Ace editor, which supports traditional editor features like syntax highlighting. I think it’s quite an audacious idea, but it might be a little dangerous to leave on public servers.

Tumblr

node-tumblr (GitHub: meritt / node-tumblr, npm: tumblr) by Alexey Simonenko is a Tumblr API wrapper for Node. It supports OAuth, and allows you to query posts, links, answers, and the other resources Tumblr provides.

Gulp, bLazy, grunt-bowercopy

07 Jan 2014 | By Alex Young | Comments | Tags bower grunt build images node modules

Gulp

Gulp

Last night I was reading a post about Gulp by Martin Genev. Martin traces the appearance of Gulp into the JavaScript community, through GitHub comments and Tweets.

Apparently Gulp is a new build system made by Fractal, a Node consultancy with several popular Node modules under their collective belts.

Gulp is built around streams, so it feels more like idiomatic Node. You can pipe files through processors, so if you had a set of LESS files you could convert them into CSS with something like gulp.src('less/*.less').pipe(less()).pipe(minify()).pipe(gulp.dest('styles/screen.css')). It supports tasks as a unit of work, and tasks can have names and dependencies.

The project has 13 contributors already – most of the work is by Eric Schoffstall who you’ll see all over Fractal’s other projects. It has tests written with Mocha, and some decent documentation already.

bLazy

bLazy (GitHub: dinbror / blazy) by Bjoern Klinggaard is a lazy loading image script. It doesn’t have any dependencies, and supports callbacks for loading failures:

var bLazy = new Blazy({
  success: function(ele) {
  },
  error: function(ele, msg) {
    if (msg === 'missing') {
      // Data-src is missing
    } else if (msg === 'invalid') {
      // Data-src is invalid
    }
  }
});

There’s a blog post about bLazy that documents the full API.

grunt-bowercopy

I seem to waste a lot of time detangling Bower dependencies to make my client-side builds more efficient. Timmy Willison may have solved this with grunt-bowercopy (GitHub: timmywil / grunt-bowercopy, License: MIT). It allows you to specify where dependencies should go, and can reduce the amount of duplication when creating builds.

It looks like it works the way I expect Bower dependency management to work in Grunt, so I’m going to go back and look at my Grunt/Bower projects to see if I can clean then up with this.

Lukis, Backbone.Controller, lrDragNDrop

06 Jan 2014 | By Alex Young | Comments | Tags node modules testing types

Lukis

Lukis (GitHub: keripix / lukis, License: MIT) by Keripix is an experimental image editor, built with Twitter’s Flight and Fabric.js.

It’s event driven, so each main drawing component is nicely decoupled. This is based on Flight’s API, where behavior is mapped to DOM nodes.

Backbone.Controller

Backbone.Controller (GitHub: artyomtrityak / backbone.controller, License: MIT) by Artyom Trityak is a Backbone controller that supports declarative routes. It makes Backbone feel more like traditional MVC, which may appeal to you if you’re brainwashed by other MVC frameworks.

Artyom has included some documentation showing how to bind routes using Backbone.Controller.extend, and there’s also a RequireJS AMD snippet so you can get started quickly.

lrDragNDrop

lrDragNDrop (GitHub: lorenzofox3 / lrDragNDrop, License: MIT) by Laurent Renard is an AngularJS module for managing collections of items using drag and drop.

You can use it as a directive, and load it with angular.module('myApp',['lrDragNdrop']). Items can be dragged from one collection to another, copied, and sorted.

Orbit Viewer, Earhorn

03 Jan 2014 | By Alex Young | Comments | Tags webgl space instrumentation debugging

Orbit Viewer

Orbit Viewer

Orbit Viewer is a Chrome Experiment by Kevin Gill that helps visualise the orbits of comets and satellites. You can watch the famous comet Shoemaker–Levy 9, or see the current position of the International Space Station. It should work with most WebGL capable browsers.

A sort of “Where are they now” for spacecraft and comets: Check out realtime positions, along with historical and projected flight paths of our solar system’s trailblazing spacecraft and comets. All in a zoomable/rotatable 3D interface. Using historical and real-time trajectory information for NASA’s JPL Horizons system, and in-browser WebGL and Three.js rendering.

Earhorn

Earhorn (GitHub: omphalos / earhorn, License: MIT) by “omphalos” is a library for instrumenting JavaScript. You pass earhorn$ a label and a function, and then you can view the function as the values change.

The mouse example shows how this works: the source for a jQuery mousemove listener is displayed, and whenever you move the mouse the integer values for the current coordinates will be reflected in real time.

An iframe is used that loads the earhorn/index.html page which knows how to display an instrumented version of the function. Internally, Earhorn uses Esprima to generate an abstract syntax tree that is manipulated to allow the code to be observed.

It reminds me a little bit of the Watches feature in Light Table, and some of the recent improvements to WebKit Inspector.