The JavaScript blog.


node errors

The Art of Error

Posted on .

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) {  
  this.message = message;

util.inherits(NotFound, Error);

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

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) {  
  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) {  

  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.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.


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.


games mathematics webgl errors

tQuery, Catchall, Geometry.js

Posted on .

tQuery Valentine's Day Card

Jerome Etienne, WebGL experimenter and author of the Learning Three.js blog, recently published a WebGL Valentine's Day card tutorial which demonstrates his new library, tQuery (License: MIT). While development on tQuery is still ongoing, it provides a friendly alternative API for WebGL based around chainable calls:

tQuery.createText('tQuery is fun!').addTo(world);

  .moveTo(0, 0)
  .lineTo(1, 1)
  .lineTo(-1, 1)
  .lineTo(0, 0);

As a JavaScript developer, this API appeals to me and results in some surprisingly concise code. The tutorial also includes a screencast which covers the methods used by the Valentine's Day card example in detail.


Catchall (License: MIT) by Craig Condon is an alternative to window.onerror created to aid development by catching all exceptions. To do this, all functions are wrapped, which is why the author recommends using it during development and testing only.

Connect middleware is also included, which allows arbitrary scripts to be wrapped by the catchall module. The project's API allows strings of code to be wrapped by using catchall.wrap, and catchall.load can be called on a source file URL or file system path:

catchall.load('http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.js', function(err, result) {  
    //do something

catchall.load('/from/fs', function(err, result) {  
    //do something


Geometry.js (License: AOL) by Nijiko Yonskai is a collection of geometry classes used by the author for game development. The following classes are included: Circle, Direction, Rectangle, Vec2d. The vector class in particular seems like something I've found myself writing and rewriting for various WebGL and game-related experiments.

The library includes a rich set of methods, and even aliases mathematical operators:

var v1 = new Vec2d(10, 20)  
  , v2 = new Vec2d(33, 10);

// 43
// 43
// [33, 10]
// [0, 0]


games language parsing errors jison

Mystik Map Editor, Outcome.js, TypedJS

Posted on .

Mystik Map Editor

Mystik Map Editor

So, you want to build the next Ultima in JavaScript? As well as a game engine tools are required. Mystik Map Editor (GitHub: UrbanTwitch / Mystik-Map-Editor) is an open source tile map editor. The client-side code is built with jQuery and jQuery UI. It supports a few drawing operations, like "brush" tile placement and a line tool, and will display if a tile is walkable or not.

Pressing "Create Map" will output a JSON representation of the current map. To see an example of a game built with this tile editor, visit mystikrpg.com. Technically, the tile editor could be forked, hacked, and used for anything, so if you do build the next Ultima with server-side JavaScript, get in touch!


Outcome.js (npm: outcome) by Craig Condon is a flow control library that focuses on error handling. Any functions with the signature .callback(err, result) can be wrapped, allowing error-related code to be grouped together.

It's quite hard to visualise the library without looking at Craig's example in the outcome.js README. Notice that rather than wrapping if statements around the errors returned in callbacks, on.success( is used to control execution.


TypedJS (License: MIT, GitHub: Proxino / TypedJS) by Ethan Fast allows functions to be annotated with type signatures. The library will then output useful logging during execution, allowing any mismatched types to be detected and potentially fixed.

To do this, comments and tests are used. Given a function with a suitable annotation:

MyObj = {  
  //+ MyObj.test_fun :: Number -> Number -> Number
  test_fun:function(num1, num2){
    return num1 + num2;

Then the function can be tested using TypedJS.run_tests(). If TypedJS.run_tests(true) is used, TypedJS will wrap functions to actually check for type violations. This is currently aimed at client-side development and requires jQuery, but the author notes that it's early days for the library, so hopefully it'll be extended to run elsewhere.

Interestingly, this is built using Jison. For those interested in Jison grammars, check out typedjs_parser.jison.