ViziCities, Flappy Bird in HTML5

21 Feb 2014 | By Alex Young | Comments | Tags webgl maps games html5

ViziCities

ViziCities

ViziCities (Demo, GitHub: robhawkes / vizicities, License: MIT) by Robin Hawkes and Peter Smart is a WebGL 3D city and data visualisation platform. It uses OpenStreetMap, and aims to overlay animated data views with 3D city layouts.

The developers have created some visualisations of social data, traffic simulation, and public transport.

It uses Three.js, D3, Grunt, and some stalwarts like Moment.js and Underscore.js.

Flappy Bird in HTML5 with Phaser

Thomas Palef, who has been making one HTML5 game per-week, has created a tutorial for making Flappy Bird in HTML5 and Phaser. The cool thing about the tutorial is he reduces Flappy Bird to its basic parts – collision detection, scoring, and the player controls. Instead of worrying about whether or not the graphics are stolen from Mario, you can just follow along and learn how a game like this works.

JavaScript Promises ... In Wicked Detail

20 Feb 2014 | By Matt Greer | Comments | Tags promises tutorial
This post is by Matt Greer. You can find the original here: mattgreer.org/articles/promises-in-wicked-detail/

I’ve been using Promises in my JavaScript code for a while now. They can be a little brain bending at first. I now use them pretty effectively, but when it came down to it, I didn’t fully understand how they work. This article is my resolution to that. If you stick around until the end, you should understand Promises well too.

We will be incrementally creating a Promise implementation that by the end will mostly meet the Promise/A+ spec, and understand how promises meet the needs of asynchronous programming along the way. This article assumes you already have some familiarity with Promises. If you don’t, promisejs.org is a good site to check out.

Why?

Why bother to understand Promises to this level of detail? Really understanding how something works can increase your ability to take advantage of it, and debug it more successfully when things go wrong. I was inspired to write this article when a coworker and I got stumped on a tricky Promise scenario. Had I known then what I know now, we wouldn’t have gotten stumped.

The Simplest Use Case

Let’s begin our Promise implementation as simple as can be. We want to go from this

doSomething(function(value) {
  console.log('Got a value:' value);
});

to this

doSomething().then(function(value) {
  console.log('Got a value:' value);
});

To do this, we just need to change doSomething() from this

function doSomething(callback) {
  var value = 42;
  callback(value);
}

to this “Promise” based solution

function doSomething() {
  return {
    then: function(callback) {
      var value = 42;
      callback(value);
    }
  };
}
fiddle

This is just a little sugar for the callback pattern. It’s pretty pointless sugar so far. But it’s a start and yet we’ve already hit upon a core idea behind Promises

Promises capture the notion of an eventual value into an object

This is the main reason Promises are so interesting. Once the concept of eventuality is captured like this, we can begin to do some very powerful things. We’ll explore this more later on.

Defining the Promise type

This simple object literal isn’t going to hold up. Let’s define an actual Promise type that we’ll be able to expand upon

function Promise(fn) {
  var callback = null;
  this.then = function(cb) {
    callback = cb;
  };

  function resolve(value) {
    callback(value);
  }

  fn(resolve);
}

and reimplement doSomething() to use it

function doSomething() {
  return new Promise(function(resolve) {
    var value = 42;
    resolve(value);
  });
}

There is a problem here. If you trace through the execution, you’ll see that resolve() gets called before then(), which means callback will be null. Let’s hide this problem in a little hack involving setTimeout

function Promise(fn) {
  var callback = null;
  this.then = function(cb) {
    callback = cb;
  };

  function resolve(value) {
    // force callback to be called in the next
    // iteration of the event loop, giving
    // callback a chance to be set by then()
    setTimeout(function() {
      callback(value);
    }, 1);
  }

  fn(resolve);
}
fiddle

With the hack in place, this code now works … sort of.

This Code is Brittle and Bad

Our naive, poor Promise implementation must use asynchronicity to work. It’s easy to make it fail again, just call then() asynchronously and we are right back to the callback being null again. Why am I setting you up for failure so soon? Because the above implementation has the advantage of being pretty easy to wrap your head around. then() and resolve() won’t go away. They are key concepts in Promises.

Promises have State

Our brittle code above revealed something unexpectedly. Promises have state. We need to know what state they are in before proceeding, and make sure we move through the states correctly. Doing so gets rid of the brittleness.

  • A Promise can be pending waiting for a value, or resolved with a value.
  • Once a Promise resolves to a value, it will always remain at that value and never resolve again.

(A Promise can also be rejected, but we’ll get to error handling later)

Let’s explicitly track the state inside of our implementation, which will allow us to do away with our hack

function Promise(fn) {
  var state = 'pending';
  var value;
  var deferred;

  function resolve(newValue) {
    value = newValue;
    state = 'resolved';

    if(deferred) {
      handle(deferred);
    }
  }

  function handle(onResolved) {
    if(state === 'pending') {
      deferred = onResolved;
      return;
    }

    onResolved(value);
  }

  this.then = function(onResolved) {
    handle(onResolved);
  };

  fn(resolve);
}
fiddle

It’s getting more complicated, but the caller can invoke then() whenever they want, and the callee can invoke resolve() whenever they want. It fully works with synchronous or asynchronous code.

This is because of the state flag. Both then() and resolve() hand off to the new method handle(), which will do one of two things depending on the situation:

  • The caller has called then() before the callee calls resolve(), that means there is no value ready to hand back. In this case the state will be pending, and so we hold onto the caller’s callback to use later. Later when resolve() gets called, we can then invoke the callback and send the value on its way.
  • The callee calls resolve() before the caller calls then(): In this case we hold onto the resulting value. Once then() gets called, we are ready to hand back the value.

Notice setTimeout went away? That’s temporary, it will be coming back. But one thing at a time.

With Promises, the order in which we work with them doesn't matter. We are free to call then() and resolve() whenever they suit our purposes. This is one of the powerful advantages of capturing the notion of eventual results into an object

We still have quite a few more things in the spec to implement, but our Promises are already pretty powerful. This system allows us to call then() as many times as we want, we will always get the same value back

var promise = doSomething();

promise.then(function(value) {
  console.log('Got a value:', value);
});

promise.then(function(value) {
  console.log('Got the same value again:', value);
});

This is not completely true for the Promise implementation in this article. If the opposite happens, ie the caller calls then() multiple times before resolve() is called, only the last call to then() will be honored. The fix for this is to keep a running list of deferreds inside of the Promise instead of just one. I decided to not do that in the interest of keeping the article more simple, it's long enough as it is :)

Chaining Promises

Since Promises capture the notion of asynchronicity in an object, we can chain them, map them, have them run in parallel or sequential, all kinds of useful things. Code like the following is very common with Promises

getSomeData()
.then(filterTheData)
.then(processTheData)
.then(displayTheData);

getSomeData is returning a Promise, as evidenced by the call to then(), but the result of that first then must also be a Promise, as we call then() again (and yet again!) That’s exactly what happens, if we can convince then() to return a Promise, things get more interesting.

then() always returns a Promise

Here is our Promise type with chaining added in

function Promise(fn) {
  var state = 'pending';
  var value;
  var deferred = null;

  function resolve(newValue) {
    value = newValue;
    state = 'resolved';

    if(deferred) {
      handle(deferred);
    }
  }

  function handle(handler) {
    if(state === 'pending') {
      deferred = handler;
      return;
    }

    if(!handler.onResolved) {
      handler.resolve(value);
      return;
    }

    var ret = handler.onResolved(value);
    handler.resolve(ret);
  }

  this.then = function(onResolved) {
    return new Promise(function(resolve) {
      handle({
        onResolved: onResolved,
        resolve: resolve
      });
    });
  };

  fn(resolve);
}
fiddle

Hoo, it’s getting a little squirrelly. Aren’t you glad we’re building this up slowly? The real key here is that then() is returning a new Promise.

Since then() always returns a new Promise object, there will always be at least one Promise object that gets created, resolved and then ignored. Which can be seen as wasteful. The callback approach does not have this problem. Another ding against Promises. You can start to appreciate why some in the JavaScript community have shunned them.

What value does the second Promise resolve to? It receives the return value of the first promise. This is happening at the bottom of handle(), The handler object carries around both an onResolved callback as well as a reference to resolve(). There is more than one copy of resolve() floating around, each Promise gets their own copy of this function, and a closure for it to run within. This is the bridge from the first Promise to the second. We are concluding the first Promise at this line:

var ret = handler.onResolved(value);

In the examples I’ve been using here, handler.onResolved is

function(value) {
  console.log("Got a value:", value);
}

in other words, it’s what was passed into the first call to then(). The return value of that first handler is used to resolve the second Promise. Thus chaining is accomplished

doSomething().then(function(result) {
  console.log('first result', result);
  return 88;
}).then(function(secondResult) {
  console.log('second result', secondResult);
});

// the output is
//
// first result 42
// second result 88


doSomething().then(function(result) {
  console.log('first result', result);
  // not explicitly returning anything
}).then(function(secondResult) {
  console.log('second result', secondResult);
});

// now the output is
//
// first result 42
// second result undefined

Since then() always returns a new Promise, this chaining can go as deep as we like

doSomething().then(function(result) {
  console.log('first result', result);
  return 88;
}).then(function(secondResult) {
  console.log('second result', secondResult);
  return 99;
}).then(function(thirdResult) {
  console.log('third result', thirdResult);
  return 200;
}).then(function(fourthResult) {
  // on and on...
});

What if in the above example, we wanted all the results in the end? With chaining, we would need to manually build up the result ourself

doSomething().then(function(result) {
  var results = [result];
  results.push(88);
  return results;
}).then(function(results) {
  results.push(99);
  return results;
}).then(function(results) {
  console.log(results.join(', ');
});

// the output is
//
// 42, 88, 99
Promises always resolve to one value. If you need to pass more than one value along, you need to create a multi-value in some fashion (an array, an object, concatting strings, etc)

A potentially better way is to use a Promise library’s all() method or any number of other utility methods that increase the usefulness of Promises, which I’ll leave to you to go and discover.

The Callback is Optional

The callback to then() is not strictly required. If you leave it off, the Promise resolves to the same value as the previous Promise

doSomething().then().then(function(result) {
  console.log('got a result', result);
});

// the output is
//
// got a result 42

You can see this inside of handle(), where if there is no callback, it simply resolves the Promise and exits. value is still the value of the previous Promise.

if(!handler.onResolved) {
  handler.resolve(value);
  return;
}

Returning Promises Inside the Chain

Our chaining implementation is a bit naive. It’s blindly passing the resolved values down the line. What if one of the resolved values is a Promise? For example

doSomething().then(result) {
  // doSomethingElse returns a Promise
  return doSomethingElse(result)
}.then(function(finalResult) {
  console.log("the final result is", finalResult);
});

As it stands now, the above won’t do what we want. finalResult won’t actually be a fully resolved value, it will instead be a Promise. To get the intended result, we’d need to do

doSomething().then(result) {
  // doSomethingElse returns a Promise
  return doSomethingElse(result)
}.then(function(anotherPromise) {
  anotherPromise.then(function(finalResult) {
    console.log("the final result is", finalResult);
  });
});

Who wants that crud in their code? Let’s have the Promise implementation seamlessly handle this for us. This is simple to do, inside of resolve() just add a special case if the resolved value is a Promise

function resolve(newValue) {
  if(newValue && typeof newValue.then === 'function') {
    newValue.then(resolve);
    return;
  }
  state = 'resolved';
  value = newValue;

  if(deferred) {
    handle(deferred);
  }
}
fiddle

We’ll keep calling resolve() recursively as long as we get a Promise back. Once it’s no longer a Promise, then proceed as before.

It is possible for this to be an infinite loop. The Promise/A+ spec recommends implementations detect infinite loops, but it's not required.
Also worth pointing out, this implementation does not meet the spec. Nor will we fully meet the spec in this regard in the article. For the more curious, I recommend reading the Promise resolution procedure.

Notice how loose the check is to see if newValue is a Promise? We are only looking for a then() method. This duck typing is intentional, it allows different Promise implementations to interopt with each other. It’s actually quite common for Promise libraries to intermingle, as different third party libraries you use can each use different Promise implementations.

Different Promise implementations can interopt with each other, as long as they all are following the spec properly.

With chaining in place, our implementation is pretty complete. But we’ve completely ignored error handling.

Rejecting Promises

When something goes wrong during the course of a Promise, it needs to be rejected with a reason. How does the caller know when this happens? They can find out by passing in a second callback to then()

doSomething().then(function(value) {
  console.log('Success!', value);
}, function(error) {
  console.log('Uh oh', error);
});

As mentioned earlier, the Promise will transition from pending to either resolved or rejected, never both. In other words, only one of the above callbacks ever gets called.

Promises enable rejection by means of reject(), the evil twin of resolve(). Here is doSomething() with error handling support added

function doSomething() {
  return new Promise(function(resolve, reject) {
    var result = somehowGetTheValue(); 
    if(result.error) {
      reject(result.error);
    } else {
      resolve(result.value);
    }
  });
}

Inside the Promise implementation, we need to account for rejection. As soon as a Promise is rejected, all downstream Promises from it also need to be rejected.

Let’s see the full Promise implementation again, this time with rejection support added

function Promise(fn) {
  var state = 'pending';
  var value;
  var deferred = null;

  function resolve(newValue) {
    if(newValue && typeof newValue.then === 'function') {
      newValue.then(resolve, reject);
      return;
    }
    state = 'resolved';
    value = newValue;

    if(deferred) {
      handle(deferred);
    }
  }

  function reject(reason) {
    state = 'rejected';
    value = reason;

    if(deferred) {
      handle(deferred);
    }
  }

  function handle(handler) {
    if(state === 'pending') {
      deferred = handler;
      return;
    }

    var handlerCallback;

    if(state === 'resolved') {
      handlerCallback = handler.onResolved;
    } else {
      handlerCallback = handler.onRejected;
    }

    if(!handlerCallback) {
      if(state === 'resolved') {
        handler.resolve(value);
      } else {
        handler.reject(value);
      }

      return;
    }

    var ret = handlerCallback(value);
    handler.resolve(ret);
  }

  this.then = function(onResolved, onRejected) {
    return new Promise(function(resolve, reject) {
      handle({
        onResolved: onResolved,
        onRejected: onRejected,
        resolve: resolve,
        reject: reject
      });
    });
  };

  fn(resolve, reject);
}
fiddle

Other than the addition of reject() itself, handle() also has to be aware of rejection. Within handle(), either the rejection path or resolve path will be taken depending on the value of state. This value of state gets pushed into the next Promise, because calling the next Promises’ resolve() or reject() sets its state value accordingly.

When using Promises, it's very easy to omit the error callback. But if you do, you'll never get any indication something went wrong. At the very least, the final Promise in your chain should have an error callback. See the section further down about swallowed errors for more info.

Unexpected Errors Should Also Lead to Rejection

So far our error handling only accounts for known errors. It’s possible an unhandled exception will happen, completely ruining everything. It’s essential that the Promise implementation catch these exceptions and reject accordingly.

This means that resolve() should get wrapped in a try/catch block

function resolve(newValue) {
  try {
    // ... as before
  } catch(e) {
    reject(e);
  }
}

It’s also important to make sure the callbacks given to us by the caller don’t throw unhandled exceptions. These callbacks are called in handle(), so we end up with

function handle(deferred) {
  // ... as before

  var ret;
  try {
    ret = handlerCallback(value);
  } catch(e) {
    handler.reject(e);
    return;
  }

  handler.resolve(ret);
}

Promises can Swallow Errors!

It's possible for a misunderstanding of Promises to lead to completely swallowed errors! This trips people up a lot

Consider this example

function getSomeJson() {
  return new Promise(function(resolve, reject) {
    var badJson = "<div>uh oh, this is not JSON at all!</div>";
    resolve(badJson);
  });
}

getSomeJson().then(function(json) {
  var obj = JSON.parse(json);
  console.log(obj);
}, function(error) {
  console.log('uh oh', error);
});
fiddle

What is going to happen here? Our callback inside then() is expecting some valid JSON. So it naively tries to parse it, which leads to an exception. But we have an error callback, so we’re good, right?

Nope. That error callback will not be invoked! If you run this example via the above fiddle, you will get no output at all. No errors, no nothing. Pure chilling silence.

Why is this? Since the unhandled exception took place in our callback to then(), it is being caught inside of handle(). This causes handle() to reject the Promise that then() returned, not the Promise we are already responding to, as that Promise has already properly resolved.

Always remember, inside of then()'s callback, the Promise you are responding to has already resolved. The result of your callback will have no influence on this Promise

If you want to capture the above error, you need an error callback further downstream

getSomeJson().then(function(json) {
  var obj = JSON.parse(json);
  console.log(obj);
}).then(null, function(error) {
  console.log("an error occured: ", error);
});

Now we will properly log the error.

In my experience, this is the biggest pitfall of Promises. Read onto the next section for a potentially better solution

done() to the Rescue

Most (but not all) Promise libraries have a done() method. It’s very similar to then(), except it avoids the above pitfalls of then().

done() can be called whenever then() can. The key differences are it does not return a Promise, and any unhandled exception inside of done() is not captured by the Promise implementation. In other words, done() represents when the entire Promise chain has fully resolved. Our getSomeJson() example can be more robust using done()

getSomeJson().done(function(json) {
  // when this throws, it won't be swallowed
  var obj = JSON.parse(json);
  console.log(obj);
});

done() also takes an error callback, done(callback, errback), just like then() does, and since the entire Promise resolution is, well, done, you are assured of being informed of any errors that erupted.

done() is not part of the Promise/A+ spec (at least not yet), so your Promise library of choice might not have it.

Promise Resolution Needs to be Async

Early in the article we cheated a bit by using setTimeout. Once we fixed that hack, we’ve not used setTimeout since. But the truth is the Promise/A+ spec requires that Promise resolution happen asynchronously. Meeting this requirement is simple, we simply need to wrap most of handle()’s implementation inside of a setTimeout call

function handle(handler) {
  if(state === 'pending') {
    deferred = handler;
    return;
  }
  setTimeout(function() {
    // ... as before
  }, 1);
}

This is all that is needed. In truth, real Promise libraries don’t tend to use setTimeout. If the library is NodeJS oriented it will possibly use process.nextTick, for browsers it might use the new setImmediate or a setImmediate shim (so far only IE supports setImmediate), or perhaps an asynchronous library such as Kris Kowal’s asap (Kris Kowal also wrote Q, a popular Promise library)

Why Is This Async Requirement in the Spec?

It allows for consistency and reliable execution flow. Consider this contrived example

var promise = doAnOperation();
invokeSomething();
promise.then(wrapItAllUp);
invokeSomethingElse();

What is the call flow here? Based on the naming you’d probably guess it is invokeSomething() -> invokeSomethingElse() -> wrapItAllUp(). But this all depends on if the promise resolves synchronously or asynchronously in our current implementation. If doAnOperation() works asynchronously, then that is the call flow. But if it works synchronously, then the call flow is actually invokeSomething() -> wrapItAllUp() -> invokeSomethingElse(), which is probably bad.

To get around this, Promises always resolve asynchronously, even if they don’t have to. It reduces surprise and allows people to use Promises without having to take into consideration asynchronicity when reasoning about their code.

Promises always require at least one more iteration of the event loop to resolve. This is not necessarily true of the standard callback approach.

Before We Wrap Up … then/promise

There are many, full featured, Promise libraries out there. The then organization’s promise library takes a simpler approach. It is meant to be a simple implementation that meets the spec and nothing more. If you take a look at their implementation, you should see it looks quite familiar. then/promise was the basis of the code for this article, we’ve almost built up the same Promise implementation. Thanks to Nathan Zadoks and Forbes Lindsay for their great library and work on JavaScript Promises. Forbes Lindsay is also the guy behind the promisejs.org site mentioned at the start.

There are some differences in the real implementation and what is here in this article. That is because there are more details in the Promise/A+ spec that I have not addressed. I recommend reading the spec, it is short and pretty straightforward.

Conclusion

If you made it this far, then thanks for reading! We’ve covered the core of Promises, which is the only thing the spec addresses. Most implementations offer much more functionality, such as all(), spread(), race(), denodeify() and much more. I recommend browsing the API docs for Bluebird to see what all is possible with Promises.

Once I came to understand how Promises worked and their caveats, I came to really like them. They have led to very clean and elegant code in my projects. There’s so much more to talk about too, this article is just the beginning!

If you enjoyed this, you should follow me on Twitter to find out when I write another guide like this.

Further Reading

More great articles on Promises

Found a mistake? if I made an error and you want to let me know, please email me or file an issue. Thanks!

Node Roundup: 0.10.26, DozerJS, Keybase

19 Feb 2014 | By Alex Young | Comments | Tags node modules

Node 0.10.26

Node 0.10.26 is out. It includes updates for V8, npm, and uv, and fixes for several core modules, including crypto, fs, and net.

DozerJS

DozerJS

DozerJS (GitHub: DozerJS / dozerjs, License: MIT, npm: dozerjs) is an Express-based project that aims to make it easier to develop MVC-style REST-based applications.

It looks like the focus is on simplifying the server-side implementation so you can focus on the UI. The conventions used for the server-side structure seem to follow the popular wisdom: route separation, simple models with validation, and HTTP verbs for CRUD operations.

Keybase

Keybase

Keybase (GitHub: keybase / node-installer) is a public key sharing tool that you can install with npm: npm install -g keybase-installer. It allows you to associate several keys with a single identity:

In one command, Keybase has acquired maria’s public key, her keybase username, and her public identities, and confirmed they’re all her, using GnuPG to review a signed tweet and gist she posted.

I think it’s an extremely interesting project – the website is clear, and I like the idea of being able to confirm identities for collaborating with people online. Using npm to distribute the client seems like a smart approach.

AngularJS Infinite Scroll, Bindable.js

18 Feb 2014 | By Alex Young | Comments | Tags dom angularjs data-binding

AngularJS Infinite Scroll

This project made me wonder if AngularJS modules are the new jQuery plugins: lrInfiniteScroll (GitHub: lorenzofox3 / lrInfiniteScroll, License: MIT), by Laurent Renard. It’s a small and highly reusable library that is specifically tailored to work well with Angular’s API.

It attaches an event handler to an element that fires when the element has been scrolled to the bottom. You can use it to automatically load items on demand, Angular style:

<ul lr-infinite-scroll="myEventHandler" scroll-threshold="200" time-threshold="600">
  <li ng-repeat="item in myCollection">
</ul>

Bindable.js

Data binding libraries are often coupled to view objects. Bindable.js (GitHub: classdojo / bindable.js, License: MIT) from ClassDojo (and Craig Condon) is a more generic bidirectional data binding library. Bindable objects are constructed, and then properties can be bound to callbacks:

var person = new bindable.Object({
  name: 'craig',
  last: 'condon',
  location: {
    city: 'San Francisco'
  }
});

person.bind('location.zip', function(value) {
  // 94102
}).now();

// Triggers the binding
person.set('location.zip', '94102'); 

Bindable objects emit other events (change, watching, dispose), and there are methods for introspection (bindable.has), context (bindable.context), and triggering callbacks after they’re defined (.now).

Backbone.React.Component, backbone-dom-view

17 Feb 2014 | By Alex Young | Comments | Tags backbone dom views react

Backbone.React.Component

If you like Facebook’s React library and Backbone.js, then take a look at José Magalhães’ Backbone.React.Component (GitHub: magalhas / backbone-react-component, License: MIT, Bower: backbone-react-component). It acts as a bridge so you can bind models, collections, and components on both the client and server.

The author has made a blog example that you can run locally. The server uses Express, and keeps collections updated with data both on the server and in the browser.

backbone-dom-view

backbone-dom-view (GitHub: redexp / backbone-dom-view, License: MIT, Bower: backbone-dom-view) by Sergii Kliuchnyk is a view class for Backbone that allows selectors to be bound to helper methods using a shorthand notation that supports binding model fields, view events, and calculations.

Sergii’s example is a to-do model:

View = Backbone.DOMView.extend
  template:
    '.title':
      html: '@title'
    '.state':
      class:
        'done': '@is_done'

It has RequireJS support, tests, and documentation in the readme.

JS-Git Progress, jide.js, Val

14 Feb 2014 | By Alex Young | Comments | Tags git browser ui

JS-Git Progress

Khalid Khan sent in an email to say that Tim Caswell JS-Git project is seeing a lot of activity recently. It seems like this new branch has changed a lot compared to the old branch.

I’d file this under “Captain’s Log: Supplemental”, but let’s see what happens over the next few weeks. If you’re interested in this project, it might be a good time to start following Tim on Twitter.

jide.js

Patrick Gotthardt recently wrote two articles about jide.js. One includes jide.js benchmarks:

Since the next release of jide.js is supposed to introduce massive performance improvements, I thought it might be a good idea to see how it holds up against this benchmark. I used a modified version from vue.js which seems to include a few more nice frameworks.

There’s also a nicely presented introduction to jide.js:

jide.js is a new toolkit for creating modern web applications. It consists of a collection of useful controls and all the tools you need to create your own, application specific, components. jide.js fully embraces AMD (require.js) to allow you to pick only those parts of it that you truly need. Starting with version 1.0.0-beta3, you’ll also be able to use it with Browserify.

At its core, jide.js is built around observable values, event emitters, and data binding. It utilizes the features of modern browsers (IE9+) to create a solid cross platform experience and to leverage the features of the current JavaScript language instead of clinging to the past.

Val

Mark Steve Samson has created a Valentine card generator (GitHub: marksteve / val, License: MIT). If you’ve been desperately searching for a tweenHeart function, then you’re in luck!

Pageres: Responsive Screenshots

13 Feb 2014 | By Alex Young | Comments | Tags node apps design

Pageres

Sindre Sorhus sent in pageres (GitHub: sindresorhus / pageres, License: MIT, npm: pageres), a command-line tool for generating screenshots of websites.

You can install it with npm install --global pageres, and then run it with a URL and a size:

pageres http://dailyjs.com/2014/02/12/node-roundup/ --sizes 800x600

It’s based on webshot, which is another small module that wraps around PhantomJS. There are other modules like pageres, but what I like about it is the focus on sizes: you could script it to generate screenshots of responsive websites. The command-line options allow you to specify many dimensions at once, so it’s easy to generate results for a responsive site.

This will work well if you’ve got marketing materials that include screenshots, or if your designers want to see useful outputs from a CI server.

Another cool feature is the Node API:

var pageres = require('pageres');

pageres(['todomvc.com'], ['1366x768', '1600x900'], function () {
  console.log('done');
});

I’ve made a few lightweight wrappers around PhantomJS before – there’s a HTML to PDF invoice generator in production that I made last year that’s been ticking over nicely. However, I like the focus on dimensions in pageres, and the command-line interface is very friendly.

Node Roundup: Multiple Node Instances, to-locals, pipes-and-filters

12 Feb 2014 | By Alex Young | Comments | Tags node modules apps

Running Multiple Instances in a Single Process

StrongLoop has a useful blog with lots of posts about Node. Yesterday Ben Noordhuis posted Running Multiple Instances in a Single Process:

Imagine a node-webkit application where each window runs its own Node instance that is isolated from all other windows. Or Node embedded in a phone or network switch where it is performing routing logic for multiple connections, but in a single process.

It’s a pretty tall order because Node started out as – and still is – a single-threaded application, built around the concept of a single event loop, with hundreds of global variables that store various bits of state.

The post goes on to show how add-on authors can use contexts, with NODE_MODULE_CONTEXT_AWARE.

to-locals

eyy sent in to-locals (GitHub: eyy / to-locals, License: MIT, npm: to-locals), a module that transforms callback functions into Connect middleware that automatically sets res.local for use in views. This example shows how easy it is to expose Mongoose models:

var users = toLocals(mongoose.model('users'), 'find', 'users');
app.get('users', users, function(req, res, next) {
  // res.locals now has the loaded users
});

It’s a small project, but even so Mocha tests have been included, and the documentation highlights the main features.

Pipes and Filters

Pipes and Filters (GitHub: slashdotdash / node-pipes-and-filters, License: MIT, npm: pipes-and-filters) by Ben Smith is a module for composing sets of asynchronous operations:

Pipeline.create('order processing')
  .use(decrypt)
  .use(authenticate)
  .use(deDuplicate)
  .breakIf(function(input) { return input.exists; })
  .execute(message, function completed(err, result) {
    // error or success handler
  });

Ben wrote a blog post that introduces the module with detailed examples: Pipes and Filters to cure Node.js async woes.

How can we perform complex processing on an input data structure, while maintaining independence and flexibility?

The Pipes and Filters pattern provides one possible solution. Described in the Enterprise Integration Patterns book as a method to “divide a larger processing task into a sequence of smaller, independent processing steps (Filters) that are connected by channels (Pipes).”

jQuery UI 1.10.4, jqModal, floatThead

11 Feb 2014 | By Alex Young | Comments | Tags jquery plugins ui

jQuery UI 1.10.4

jQuery UI 1.10.4 is out:

The fourth maintenance release for jQuery UI 1.10 is out. This update brings bug fixes for Widget Factory, Position, Droppable, Resizable, Accordion, Autocomplete, Button, Datepicker, Dialog, Menu, Slider, Spinner, Tabs, and the CSS Framework. For the full list of changes, see the changelog.

jQuery UI 1.10.3 was released last May, so it’s been quite a while since the last release!

jqModal

jqModal (GitHub: briceburg / jqModal, License: MIT, GPL) by Brice Burgess is a plugin for showing modals, popups, and notices. To use it, you just need a suitable container element with dialog content and then to call $('#dialog').jqm();.

It can load content using Ajax, and allows dialogs to be nested. External content can also be loaded using iframes.

jquery.floatThead

jquery.floatThead (GitHub: mkoryak / floatThead, License: CC BY-SA 4.0) by Misha Koryak is a plugin for floating table headers. Headers can be floated inside elements with overflow scrolling, and also for the entire window.

Overflow scrolling requires that the “scroll container” is specified:

var $table = $('table.demo');
$table.floatThead({
  scrollContainer: function($table){
  return $table.closest('.wrapper');
}});

Kettle.js, Backbone.SuperModel, Mem.js

10 Feb 2014 | By Alex Young | Comments | Tags mvvm mvc backbone

Kettle.js

Kettle.js (GitHub: smelnikov / kettle, License: MIT) by Sergey Melnikov is an alternative approach to Backbone views that uses a declarative syntax to define elements, their bindings, and their associated events.

It supports two-way data binding, sub views, and can be extended to support custom Kettle elements.

Mem.js

Mem.js (GitHub: artyomtrityak / mem.js, License: MIT) by Artyom Trityak is a memory management library for Backbone. It allows you to save, retrieve, and destroy instances of Backbone classes:

var View = Backbone.View({});

// On set returns new stored function instance or object
var headerViewIns = Mem.set('headerView', View, { el: 'body' });

It can remove and recreate instances with Mem.reset, and remove outdated objects with Mem.manage.

Backbone.SuperModel

Backbone.SuperModel (GitHub: laoshanlung/backbone.supermodel, License: MIT, npm: backbone.supermodel) by Tan Nguyen is model class that offers support for nested collections. It supports dot notation for getters and setters, and an updated toJSON that reflects the nested structure. Relationships can be defined between models as well.

var wallet = {
  money: {
    amount: 4000,
    currency: 'euro'
  },
  name: 'Tan Nguyen'
};

var myStuff = new Backbone.Model();
myStuff.set('wallet', wallet);
myStuff.get('wallet').money.amount; // 4000

The project includes tests and benchmarks, and examples can be found in the readme.

HTML5 Game Per Week, Oboe.js

07 Feb 2014 | By Alex Young | Comments | Tags node modules games json

One HTML5 Game Per Week

Princess Quest

Thomas Palef sent in his project to create one HTML5 game a week. He’s created seven games so far, including Princess Quest, a vertical jumping game that uses Phaser.

He’s also posting short blog posts about how he makes the games.

Oboe.js

Oboe.js (GitHub: jimhigson / oboe.js, License: BSD, Bower: oboe, npm: oboe) is a library for handling JSON HTTP responses before the request has finished:

It glues a transport that sits somewhere between streaming and downloading to a JSON parser that sits somewhere between SAX and DOM. It is small enough to be a micro-library, doesn’t have any external dependencies and doesn’t care which other libraries you need it to speak to.

The website has a video and more documentation that explains how it works.

Nordic.js, Octocard

06 Feb 2014 | By Alex Young | Comments | Tags conferences events node modules

Nordic.js

Nordic.js

Nordic.js is a two day conference that takes place in Stockholm in September. They’re accepting proposals for talks, so you might want to bookmark that link if you’re interested in speaking.

Tickets aren’t yet available, but apparently a related meetup in Stockholm is extremely popular, so it’ll sell out quickly.

Octocard

Octocard (GitHub: zmmbreeze / octocard, License: MIT) is a GitHub widget, with a nice, compact design and a cool graph.

It’s used by including a <script> element with data attributes, and you can theme it fairly easily.

There’s also a Node project called octocard-server that can serve data from MongoDB. It uses GitHub authentication, and the octonode GitHub API wrapper.

Node Roundup: bitcoinaddress.js, atry, Node Web Modules

05 Feb 2014 | By Alex Young | Comments | Tags node modules apps bitcoin

bitcoinaddress.js

If you need to take Bitcoin payments on your site, then bitcoinaddress.js (GitHub: miohtama / bitcoinaddress.js, License: MIT, npm: bitcoinaddress) by Mikko Ohtamaa might help. It’s a module for handling Bitcoin payments. It can be run as a client-side script, or as a Node module. It allows Bitcoins to be sent, or specific currency amounts based on “fiat” amounts.

It’s based around bitcoin: URIs, and allows you to display “Pay from wallet” links on your pages. It also displays QR codes so people can easily make payments using mobile Bitcoin apps.

atry

atry (GitHub: CodeCharmLtd / atry, License: MIT, npm: atry) from Code Charm (Damian Kaczmarek) is an alternative to Node’s domain module. The basic idea is to allow exceptions to be caught using an asynchronous API:

atry(function() {
  setTimeout(function() {
    throw new Error('I am Error');
  }, 10);
}).catch(function(err) {
  console.log('Error:', err);
});

It has an intercept method that returns an “exception safe” callback that you can pass as a callback to asynchronous APIs like fs.readFile.

Node Web Modules

Node Web Modules (GitHub: caio-ribeiro-pereira / node-web-modules, License: MIT) by Caio Ribeiro Pereira is a Node web application that shows a list of popular web frameworks for Node. If you select one of the modules it shows a screenshot and some statistics.

The project is powered by Express and Redis, and it uses the GitHub API. The module list it displays on http://nodewebmodules.com/ is useful for beginners, but you might also like to take a look at the source to see how it works.

Spectra, GizmoJS, EdisonJS

04 Feb 2014 | By Alex Young | Comments | Tags jquery design

Spectra

Spectra (GitHub: aakpat6 / spectra, License: MIT, npm: spectra) by Aakash Patel is a library for working with colours. It’s a function that accepts various colour formats: RGB, HSL, hex, and CSS colour names.

It can also convert formats, so calling colour.hex() will return a hex value. Colours can even be compared with the .equals method. There are additional methods for processing colours, including harmony, which can generate harmonies for analogous, triad, complementary, square, and rectangle colours.

The Spectra API documentation has examples for each method, and the author has included unit tests.

EdisonJS

EdisonJS (GitHub: tkambler / edison.js, License: MIT) by Tim Ambler is a router for single page applications based on hierarchical relationships. The idea is to define sections and routes. Sections contain routes, and routes map to URLs. That means visiting a URL will cause a section’s callback to fire.

The API is based around instances of sections that you define with edison.createSection. There’s also a edison.extendCleanup method that fires when people navigate away from routes.

GizmoJS

Tim Ambler also sent in GizmoJS (GitHub: tkambler / gizmo, License: MIT, Bower: gizmo). GizmoJS is a component library, similar to jQuery UI’s widget factory. It doesn’t depend on jQuery, but does need RequireJS, because the components are based on AMD. It has an event API and inheritance helper.

Vue.js, beautify-with-words

03 Feb 2014 | By Alex Young | Comments | Tags node modules mvvm mvc

Vue.js

Vue.js

Vue.js (GitHub: yyx990803 / vue, License: MIT) by Evan You is a MVVM library. It’s based around instances of the Vue constructor, essentially view model objects, that provide bindings between DOM objects and data models.

It has an event-based API with key/value observing, HTML directives (like AngularJS), and text filters. There’s a TodoMVC example that showcases some of the features. Most of the code is passed in as options to the Vue constructor, so it feels a little bit like Backbone.js views in that respect.

Vue.js is an interesting combination of features from Backbone.js, KnockoutJS, and AngularJS. Evan seems confident about its performance and features, but I think it’ll be hard to convince people to seriously try it out given how popular Backbone and AngularJS have become.

beautify-with-words

beautify-with-words (GitHub: zertosh / beautify-with-words, License: MIT, npm: beautify-with-words) by Andres Suarez is a module based on UglifyJS that replaces variable names with words.

You can pass -b to beautify the output, which essentially means you can turn minified, obfuscated code into something not quite readable, but much easier to search and grep for patterns.

Conference: mloc.js, Bootstrap 3.1

31 Jan 2014 | By Alex Young | Comments | Tags conferences events bootstrap

Conference: mloc.js

mloc.js

mloc.js is a conference in Budapest, taking place on February 13th. Tickets start at $260, but there are only 24 left!

With projects like asm.js and Emscripten, Mozilla is beginning to see JavaScript as a virtual machine and compiler target. Will it change how we think about and how we use JavaScript? How compiling C++ code to really fast JavaScript code will transform the web? At mloc.js we are bringing together representatives of major browser vendors, industrial users with large web projects, and authors of compile-to-JS projects with the goal of moving the web forward. Together we will discuss what will be possible with the web platform in the next 10 years.

There are some great speakers from PayPal, Google, Mozilla, Intel, and more.

Bootstrap 3.1

It looks like Bootstrap 3.1 is out. There’s an inconsequential and pointless discussion about it on Hacker News, so it’s probably best to ignore that and read the changelog for yourself.

One of the nice things about this release is it includes some new templates: Blog, Cover, and Dashboard. Even though I like to code these by hand, it’s great for people who want to get started quickly. The blog template doesn’t use the article element, but they do target IE 8 so that might be why.

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.