ECMAScript 6 on dwmkerr.com

Getting Started with React & ES6

Mon, 07 Sep 2015 19:44:54 +0000

Feeling like having a go with Facebook’s hugely popular React framework but not sure where to start?

In this post I’m going to build a simple React application from scratch - using ECMAScript 6.

We’ll put together the bare minimum skeleton of a site and keep the folder structure free of noise and clutter so that you can focus on the app code and not the tooling!

The simple app we’ll build is at github.com/dwmkerr/react-es6-starter, or see it live.

Building the Code

Our goal will be to have a single index.html file which includes our Javascript files. We’re aiming for something like this:

But browsers don’t handle ES6 yet. So our loose files, which reference each other, are going to have to be transpiled into ES5 and bundled into a single file. We need a build process:

Webpack can handle all of this for us. Given an entrypoint file, webpack will traverse all of the require and import statements and build a single bundle file. It also allows us to configure ’loaders’, which let us pass these files through other tools:

We’ll need the following libraries:

Webpack - the tool that handles the build process.
Babel - an excellent ES6/ES7/JSX to ES5 transpiler.
Babel Loader - the component which integrates Babel into our Webpack build.
Html Webpack Plugin - a simple Webpack plugin which will copy our index file to our build folder and add a link to our Webpack bundle.

Let’s install these modules:

npm install --save webpack babel babel-loader html-webpack-plugin

We’ll also need a webpack config file. By default webpack expects a file named webpack.config.js to be in the root of the project. But every tool under the sun wants to stick its config file in the root of our project, and most of the time they’re just in the way.

So let’s put everything to do with our tooling in a tooling folder instead. Create the file webpack.config.js in a tooling folder in the root of the project:

var path = require('path');

module.exports = {

 // Defines the entrypoint of our application.
 entry: path.resolve(__dirname, '../src/app.js'),

 // Bundle to a ./build/public/bundle.js file.
 output: {
 path: path.resolve(__dirname, '../build/public'),
 filename: 'bundle.js'
 },

 // Use babel for anything that is *.js or *.jsx.
 module: {
 loaders: [
 {
 test: /\.jsx?$/,
 loader: 'babel-loader',
 include: path.resolve(__dirname, '../src')
 }
 ]
 }
};

First we define our entry point - the first file which will actually be run if we run the final bundled script. This is the app.js file we’ll create shortly. If app.js includes other modules, Webpack will pick them up, if those modules include other modules, they will be picked up and so on.

Next we specify that everything should be bundled into a ./build/public/bundle.js file (we’re going to use the convention that everything we can produce with our tools goes into ./build).

Finally, we specify that every file in src which matches the \.jsx?$ regex will go through the babel loader.

Using ES6!

We’ve actually got enough now to use ES6. Create a file in src called index.html:

<!DOCTYPE html>
<html>
<body>
</body>
</html>

Then create a src/app.js file:

const PI = 3.14;
let vals = [1, 2, 3].map(x => x*2);
document.body.innerText = "Pi is " + 3.14 + " and vals is " + vals;

Run the command ./node_modules/.bin/webpack --config ./tooling/webpack.config.js and our code is built, transpiled an moved to the build folder.

Now we could serve this folder using any basic webserver. We are already using webpack, so the webpack dev server will do the trick. It uses exactly the same config file as the webpack tool:

npm install --save-dev webpack-dev-server
./node_modules/.bin/webpack-dev-server --config ./tooling/webpack.config --inline

The inline reloads the page when the source changes. We don’t need to tell the server where the files are, it knows that from the webpack config.

Let’s stick these commands in our package.json for convenience:

{
 ...
"scripts": {
 "start": "webpack-dev-server --config ./tooling/webpack.config.js --inline --quiet",
 "webpack": "webpack --config tooling/webpack.config.js"
 ...
}

Now we can manually build with npm run webpack and start our dev server with npm start.

Adding some React

Let’s add a React component. Create a folder under app called home and add a home.js file:

import React from 'react';

export default class Home extends React.Component {
 render () {
 return <div>
 <h1>React ES6 Starter</h1>
 <p>Welcome to the React ES6 Starter home page!</p>
 </div>;
 }
}

This is our first react component, which does nothing more than render some basic markup. We’ll use this as the starting point for our application.

We can now take our app.js file and render our Home component into the div. Here’s app.js:

import React from 'react/addons';
import Home from './home/home';

React.render(<Home />, document.body);

That’s all there is to it! We’ve got a clean and simple starting point to begin playing with React. Before we look into things like state management and routing, let’s look into testing what we have so far.

Testing

Even the most simple app would be incomplete without looking into how we will deal with the testing.

Many will recommend the Jest framework to test React applications. However, it’s a bit more to learn and has some problems with NodeJS v0.12, so until we get Node v4 I’m going to keep things simple.

First, we’ll install Karma as a test runner. We’ll use Jasmine as as framework to write test cases and PhantomJS as a headless browser in which our tests will run. This means we’ll need to add some more dev dependencies:

npm install --save-dev karma jasmine karma-webpack karma-jasmine karma-phantomjs-launcher

We can now create a karma.config.js file in our tooling folder:

var path = require('path');

module.exports = function(config) {
 config.set({
 browsers: ['PhantomJS'],
 files: [
 // We need to polyfill as PhantomJS doesn't support 'bind'.
 '../node_modules/babel-core/browser-polyfill.js',
 '../**/*.spec.js'
 ],
 frameworks: ['jasmine'],
 preprocessors: {
 '../**/*.spec.js': ['webpack'],
 },
 reporters: ['progress'],
 singleRun: true,
 webpack: {
 module: {
 loaders: [
 {
 test: /\.jsx?$/,
 loader: 'babel-loader',
 include: path.resolve(__dirname, '../src')
 }
 ],
 }
 },
 webpackServer: {
 noInfo: true
 }
 });
};

So here we are:

Loading a polyfill from babel core (sorry guys, one more npm install --save-dev babel-core) which gives PhantomJS the bind function (along with some others). This is needed as some of the testing code in the browser needs these features.
Specifying that anything that ends in .spec.js should be loaded.
Running anything that ends in .spec.js through webpack.
Telling webpack to use babel.

Quite a bit of config, but we’re re-using the same webpack tooling as before. We run the code through webpack, which sends it through babel and builds ES5 we can test in the browser.

With this in place, we can write a spec. Add home.spec.js to the home folder:

import React from 'react';
import $ from 'jquery';
import Home from './home.js';

describe('Home', () => {

 it('should render to the DOM', function() {

 // Create the <Home /> react component.
 var component = React.render(<Home />, document.body);

 // Find the DOM element for the created component.
 var node = React.findDOMNode(component);

 // Check the DOM looks how we'd expect it to.
 expect($(node).children('h1').text()).toEqual("React Redux Starter");

 });

});

What’s going on here? We just ask React to render our Home component directly into the DOM. We get a component back from this call. We can then ask React to give us the DOM associatefd with the component and use familiar tools (jQuery!) to test the shape of the generated DOM.

All that’s missing is the last of the dev dependencies we’ve missed:

npm install --save-dev jquery phantomjs

We can run tests directly on a Mac or Unix with:

./node_modules/.bin/karma start ./tooling/karma.config.js

For Windows use:

node_modules\.bin\karma start tooling\karma.config.js

In fact, we’ll update our package.json scripts so that this is the test command:

"scripts": {
 "test": "./node_modules/.bin/karma start ./tooling/karma.config.js",
 ...

Done! This means we can run tests on any platform with NodeJS¹ using the same command - npm test.

We now have a very simple setup which allows us to run tests. You can build on this - perhaps adding Jest later or a more sophisticated or React specific set of tools.

Adding Code Coverage

You might want to add some code coverage information to your project. This can be a little tricky when using ES6, as we need to make sure we report coverage of the original ES6 code, rather than the actual transpiled code which is instrumented.

Fortunately, with the clean and simple setup we have built, adding code coverage is a snap.

Our test runner, Karma, is built to quickly integrate with the code coverage tool Istanbul, we just need to use the Karma Coverage plugin. Let’s install the two modules:

npm install --save-dev istanbul karma-coverage

Now with a small addition to our karma.config.js file we will get a nice HTML coverage report. We need to update our reporters config to include coverage and specify coverage options in the coverageReporter config.

 reporters: ['progress', 'coverage'],
 coverageReporter: {
 dir: '../build/coverage/',
 type: 'html'
 }

If you run npm test now, you’ll get an HTML coverage report generated. The only problem is that it is for the transpiled code, which makes it almost useless. A customer instrumenter called isparta will help us here. We use isparta to get a report of the coverage of the original ES6 code. Two more modules:

npm install --save-dev isparta isparta-instrumenter-loader

Then in our karma config we pass the orignal code through the insrtrumenter, before babel transpiles it:

webpack: {
 module: {
 preLoaders: [
 {
 test: /\.jsx?$/,
 exclude: [/node_modules/, /\.spec\.js/],
 loader: 'isparta-instrumenter-loader'
 },
 ],
 // everything else stays the same...

Anything that is not a spec or from node_modules gets instrumented. Now we have a ES6 code coverage report:

With this in place, you can go even further and integrate with other CI or publish to code quality systems (for example this repo integrates to coveralls.io). This is often used to show badges for repos:

Another use case is to gate checkins unless they maintain a certain code coverage threshhold.

Wrapping Up

This provides a very lean starting point for learning React. There’s no moving parts at the moment - no state management. We’ll get into that in later articles but right now you have a playground.

You can set up CI in a flash, just sign up for a Travis account and use a travis.yml like this:

language: node_js
node_js:
 - "0.12"

This repo is all ready to push to Heroku, no Procfile is needed. Check out react-es6-starter.herokuapp.com to see the code in action.

I hope you’ve found this article useful! Next time we’ll be getting into the details of managing state in React.

Please fork the repo and have a play, let me know of any suggestions or improvements!

github.com/dwmkerr/react-es6-starter

Glossary of Conventions

There are a few conventions that I personally use in most Javascript projects. The conventions used in this article which I think are valuable to consider using in many projects are:

Always support install/test/start

Everyone should always be able to checkout, install, test and run the code with the following commands:

npm install # installs everything needed
npm test # lets the user know the code works right on their system!
npm start # starts the code, lets the user know what to do next

Install should setup everything, and if code needs to be built to be testable, this should be a post-install hook.

Test should be run next, as a user should be able to verify that the code works as expected on their system.

Finally, when the user runs start, a dev server (as convention dictates we are in a dev mode by default (and production mode is set with a flag or environment variable) the server should start and a console message should show the user where to browse to.

Footnotes

IBM Mainframes anyone? ↩︎

The Best Module System for AngularJS Applications

Wed, 18 Mar 2015 14:47:10 +0000

I was working on a small and simple application built with AngularJS the other day. As with most applications like this, I start with a single JavaScript file caled app.js and no module system.

In the past I’ve used RequireJS with AngularJS. It’s an awful mistake. It leads to a big jump in complexity with no benefts. Angular apps don’t work well with AMDs, so really your are using RequireJS to combine files into one big file.

I’m sure there’s a good analogy with hammers and nails. Something like:

It’s like banging nails into your face with a hammer.

Maybe a bit extreme. But those who’ve used the two together may well be nodding sagely.

I’ve also used Browserify. I prefer this approach, the syntax is cleaner. But it’s still a pain.

Ideally, I’d like to use ECMA6 modules. So another approach is to just use ECMA6 module syntax and then compile your code with something like Traceur. But that requires quite a bit of tooling, slows down your pipeline and you’re still not really using modules.

I think the best approach is this one from Jeff Dicky on his post Best Practices for Building Angular.js Apps. Just forget all of the module stuff and concatenate only.

Start with this:

myproject
- app/
- css/
- vendor/
- index.html

Or whatever your preferred structure is. Then stick your main file in app/:

myproject
- app/
- app.js
- css/
- vendor/
- index.html

Your app.js file should define your main Angular module:

angular.module('app', []);

Now just go ahead and concatenate everything in your app/ folder. Structure it however you want:

myproject
- app/
- components/
- home/
- profile/
- app.js
- css/
- vendor/
- index.html

Concat will put everything in the top level folder (i.e. app.js) first. As long as you don’t put anything else in your top level folder (that comes before ‘a’ alphabetically) then it doesn’t matter where you put your other files, as long as you define them without referencing any globals. So define your components like this:

angular.module('app').controller('SomeController', function() {
 // something
});

No fuss no muss. No requires, no exports.

If you need a new service, write it and save it. Same for directives or controllers or filters. Add the source file and it’s included, no messing around.

Keep it simple, don’t force another module system on top of angular’s, you don’t get much benenfit. And wait patiently until ECMA6 moves more into the mainstream and we can start using native modules. There’s less and less point in investing in some super-sophisticated complex fancy module system for a framework which in vNext will throw it all away and for a language which will finally get native modules.

Words for Gulpers

If you are a gulp user, here’s how a pipeline might look to concat your JavaScript:

var gulp = require('gulp');
var jshint = require('gulp-jshint');
var stylish = require('jshint-stylish');
var uglify = require('gulp-uglify');
var rename = require('gulp-rename');
var sourcemaps = require('gulp-sourcemaps');
var concat = require('gulp-concat');
var ngAnnotate = require('gulp-ng-annotate');

// Hints and builds all JavaScript.
gulp.task('js', function() {

 return gulp.src(['./client/app/**/*.js'])
 .pipe(jshint())
 .pipe(jshint.reporter(stylish))
 .pipe(jshint.reporter('fail'))
 .pipe(sourcemaps.init({loadMaps: true}))
 .pipe(concat('app.js'))
 .pipe(gulp.dest('./client/dist'))
 .pipe(ngAnnotate())
 .pipe(uglify())
 .pipe(rename({suffix: '.min'}))
 .pipe(sourcemaps.write('./'))
 .pipe(gulp.dest('./client/dist/'));

});

Watch your app javascript folder and when it changes, you’ll hint everything, concat into a single distribution folder, annotate and uglify, as well as building full sourcemaps.

What about other stuff?

For vendor code (jQuery, Bootstrap, whatever), don’t bother trying to be smart and require or import it. Just include it in your app with script tags. I wouldn’t go to the effort at trying to force some kind of smart module system on a language that doesn’t really support it - uf you can get away with avoiding it, do so.

This is not an encouragement to be sloppy, this is just the easiest way to deal with the issue. The number of hours I’ve wasted tracking down ‘bugs’ which were subtle issues to do with require.js or type-os has definitely made the approach above my preferred approach.

AngularJS Promises - The Definitive Guide

Wed, 07 May 2014 12:06:55 +0000

Promises are a core feature of AngularJS - whether you understand them or not, if you use AngularJS you’ve almost certainly been using them for a while.

In this post I’m going to explain what promises are, how they work, where they’re used and finally how to use them effectively.

Once we’ve got the core understanding of promises, we’ll look at some more advanced functionality - chaining and resolving promises when routing.

What are Promises?
How do Promises Work?
A Real World Example
Promises - Success, Error, Then
Advanced Promises - Chaining
Advanced Promises - Routing
Advanced Promises - Tips & Tricks
The Future of Promises
Wrapping Up

What are Promises?

I’m going to try and be as succinct as possible - if anyone has a shorter, clearer description, let me know!

A promise represents the eventual result of an operation. You can use a promise to specify what to do when an operation eventually succeeds or fails.

So let’s see this in action. Look at the code below:

$http.get("/api/my/name");

This code uses the $http service to perform an HTTP GET on the url ‘/api/my/name’. Let’s say that this is an api we’ve implemented on our server that returns the name of the logged in user.

Now a common mistake for JavaScript newcomers might be to assume that the function returns the name:

// The WRONG way!
var name = $http.get("/api/my/name");

It doesn’t - and in fact it can’t. An HTTP request has to be executed, it’ll take a while before it returns - it might not return at all if there are errors. Remember, when we make requests in JavaScript we’re using ajax which is asynchronous javascript and xml. The key word here is asynchronous - we return control to the browser, let it make a request and give it a function to call when the request completes.

So let’s see how you actually make the request.

var promise = $http.get("/api/my/name");
promise.success(function(name) {
 console.log("Your name is: " + name);
});
promise.error(function(response, status) {
 console.log("The request failed with response " + response + " and status code " + status);
});

Now we use the promise object to specify what to do when the request succeeds, or when it fails. Remember, the functions we pass to success or error will be called later - when this block is finished executing we don’t have the name, we’ve just specified what to do when we do eventually get it - or what to do if we fail to get it.

As a convenience, the success and error functions actually just return the promise, so we can simplify the code:

$http.get("/api/my/name")
 .success(function(name) {
 console.log("Your name is: " + name);
 })
 .error(function(response, status) {
 console.log("The request failed with response " + response + " and status code " + status);
 });

In fact, success and error are special functions added to a promise by $http - normally with promises we just use then, which takes the success function as the first parameter and the error function as the second:

$http.get("/api/my/name")
 .then(
 /* success */
 function(response) {
 console.log("Your name is: " + response.data);
 },
 /* failure */
 function(error) {
 console.log("The request failed: " + error);
 });

We’ll see more about the difference between success, error and then later.

That’s all there is to it - a promise lets us specify what to do as the result of an operation.

How do Promises Work?

Promises are not actually complicated, they’re objects that contain a reference to functions to call when something fails or succeeds.

Under the hood, AngularJS actually wires up a promise for an HTTP request in a way a bit like this:

var request = new XMLHttpRequest();
request.addEventListener("load", function() {
 // complete the promise
}, false);
request.addEventListener("error", function() {
 // fail the promise
}, false);
request.open("GET", "/api/my/name", true);
request.send();

this is pseudo-code, but the idea is that its the browser that calls us back, via the event listeners, then AngularJS can just call the appropriate method on the promise.

Now in AngularJS, the promises are created with the $q service (we’ll see exactly how to do this shortly), but why $q?

The reason the service is named $q is that AngularJS’ promise implementation is based on Kris Kowal’s promise mechanism, which is called ‘Q’. You can see the library at github.com/kristkowal/q.

This was a deliberate decision, as the Q library is widely used and well understood by the community. We’re going to see a little bit later what the future of promises is in AngularJS and actually in ECMAScript 6.

A Real World Example

In this example we’ll create a service that gets the user’s name, just like in our examples. However, to make it interesting, we’ll set our service up so that the first time we get the name from the server, and then afterwards we’ll return a cached copy.

This means we’ll have to build our code to deal with the asynchronous case (the first one) and the more trivial synchronous case (getting the name from the cache).

Let’s look at a pure asynchronous implementation.

app.factory('NameService', function($http, $q) {

 // Create a class that represents our name service.
 function NameService() {

 var self = this;

 // getName returns a promise which when
 // fulfilled returns the name.
 self.getName = function() {
 return $http.get('/api/my/name');
 };
 }

 return new NameService();
});

Here’s how it looks in a fiddle - just click ‘Result’ to see it working. You can click on ‘Update’ name to get the name, but each time it sends a request. This is what we’ll change next.

Now let’s update our service so that we hit the server only if we haven’t already cached the name. I’ll build the service blow by blow, then we can see a fiddle of it working.

app.factory('NameService', function($http, $q) {

 // Create a class that represents our name service.
 function NameService() {

 var self = this;

 // Initially the name is unknown....
 self.name = null;

so first we create a service which is in the form of a class. It has a name field which is initially null.

 self.getName = function() {
 // Create a deferred operation.
 var deferred = $q.defer();

Now in the getName function we start by creating a deferred object, using the $q service. This object contains the promise we’ll return, and has some helper functions to let us build the promise.

We create a deferred object because whether we use ajax or not, we want the consumer to use the promise - even if we can return straightaway in some circumstances (when we have the name) we can’t in all - so the caller must always expect a promise.

 if(self.name !== null) {
 deferred.resolve(self.name + " (from Cache!)");
 }

If we already have the name, we can just resolve the deferred object immediately - this is the easy case. I’ve added ‘from cache’ to the name so we can see when it comes from the cache compared to the server.

Tip: You can resolve a promise even before you return it. It still works fine for the consumer.

Finally, we can handle the case if we don’t already have the name:

 else {
 // Get the name from the server.
 $http.get('/api/my/name/')
 .success(function(name) {
 self.name = name;
 deferred.resolve(name + " (from Server!)");
 })
 .error(function(response) {
 deferred.reject(response);
 });
 }

So if we get success from the server, we can resolve the promise. Otherwise, we reject it, which means failure.

Call resolve on a deferred object to complete it successfully, call reject to fail it with an error.

Finally, we just return the promise we’ve built with deferred:

 return deferred.promise;
}

And that’s it! You can see it in action below, press ‘Update Name’ a few times and you’ll see it uses the cache.

How do we use this? We’ll it’s simple, here’s a controller that uses the service we’ve built:

app.controller('MainController', function ($scope, NameService) {

 // We have a name on the code, but it's initially empty...
 $scope.name = "";

 // We have a function on the scope that can update the name.
 $scope.updateName = function() {
 NameService.getName()
 .then(
 /* success function */
 function(name) {
 $scope.name = name;
 },
 /* error function */
 function(result) {
 console.log("Failed to get the name, result is " + result);
 });
 };
});

Now there’s something different here. Before, we might have used the error or success function of the promise. But here we use then. Why is that?

success and error are functions on a promise that AngularJS adds for us when using $http or $resource. They’re not standard, you won’t find them on other promises.

So we’ve seen how promises work, what they are and so on, now we’ll look into this success/error/then stuff.

Promises - Success, Error, Then

Now we know that $http returns a promise, and we know that we can call success or error on that promise. It would be sensible to think that these functions are a standard part of promise - but they’re not!

When you are using a promise, the function you should call is then. then takes two parameters - a callback function for success and a callback function for failure. Taking a look at our original $http example, we can rewrite it to use this function. So this code:

$http.get("/api/my/name")
 .success(function(name) {
 console.log("Your name is: " + name);
 })
 .error(function(response, status) {
 console.log("The request failed with response " + response + " and status code " + status);
 };

becomes:

$http.get("/api/my/name")
 .then(function(response) {
 console.log("Your name is: " + response.data);
 }, function(result) {
 console.log("The request failed: " + result);
 };

We can use success or error when using $http - it’s convenient. For one thing, the error function gives us a response and status (and more) and the success function gives us the response data (rather than the full response object).

But remember that it’s not a standard part of a promise. You can can add your own versions of these functions to promises you build yourself if you want:

promise.success = function(fn) {
 promise.then(function(response) {
 fn(response.data, response.status, response.headers, config);
 });
 return promise;
 };

promise.error = function(fn) {
 promise.then(null, function(response) {
 fn(response.data, response.status, response.headers, config);
 });
 return promise;
 };

this is exactly how angular does it.

So what’s the advice?

Use success or error with $http promises if you want to - just remember they’re not standard, and the parameters are different to those for that callbacks.

So if you change your code so that your promise is not returned from $http, as we did in the earlier example when we load data from a cache, your code will break if you expect success or error to be there.

A safe approach is to use then wherever possible.

Advanced Promises - Chaining

If you’ve had your fill of promises for now, you can skip to The Future of Promises or Wrapping Up.

One useful aspect of promises is that the then function returns the promise itself. This means that you can actually chain promises, to create conscise blocks of logic that are executed at the appropriate times, without lots of nesting.

Let’s consider an example where we need to fetch the user’s name from the backend, but we have to use separate requests to get their profile information and then their application permissions.

Here’s an example:

var details {
 username: null,
 profile: null,
 permissions: null
};

$http.get('/api/user/name')
 .then(function(response) {
 // Store the username, get the profile.
 details.username = response.data;
 return $http.get('/api/profile/' + details.username);
 })
 .then(function(response) {
 // Store the profile, now get the permissions.
 details.profile = response.data;
 return $http.get('/api/security/' + details.username);
 })
 .then(function(response) {
 // Store the permissions
 details.permissions = response.data;
 console.log("The full user details are: " + JSON.stringify(details);
 });

Now we have a series of asynchronous calls that we can coordinate without having lots of nested callbacks.

We can also greatly simplify error handling - let’s see the example again, with an exception thrown in:

$http.get('/api/user/name')
 .then(function(response) {
 // Store the username, get the profile.
 details.username = response.data;
 return $http.get('/api/profile/' + details.username);
 })
 .then(function(response) {
 // Store the profile, now get the permissions.
 details.profile = response.data;
 throw "Oh no! Something failed!";
 })
 .then(function(response) {
 // Store the permissions
 details.permissions = response.data;
 console.log("The full user details are: " + JSON.stringify(details);
 })
 .catch(function(error) {
 console.log("An error occured: " + error);
 });

We can use catch(callback) - which is actually just shorthand for then(null, callback). There’s even a finally - which is executed whether or not the operations fail or succeed.

Use catch and for error handling with promises - and use finally for logic that’s executed after success OR failure.

The composition of promises can simplify complicated code - particularly when you add in error handling!

One final point to make which is not quite related to chaining but does relate to multiple promises is $q.all. all can be used to build a single promise from a set of promises.

You can pass an array of promises to all and you get back a single promise - which is resolved when all of the promises it contains resolve. This can be useful if you are building complex methods that may have to perform multiple asynchronous tasks - such as multiple ajax calls.

Advanced Promises - Routing

There’s a particular area of AngularJS that uses promises to great effect, and that’s the router.

Let’s imagine we have a router like the following:

$routeProvider
 .when('/home', {
 templateUrl: 'home.html',
 controller: 'MainController'
 })
 .when('/profile', {
 templateUrl: 'profile.html',
 controller: 'ProfileController'
 })

Here we have two routes. The home route takes us to the home page, with the MainController, and the profile route takes us to the user’s profile page.

Our ProfileController uses our funky name service:

app.controller('ProfileController', function($scope, NameService) {
 $scope.name = null;

 NameService.getName().then(function(name) {
 $scope.name = name;
 });
});

The problem is, until the name service gets the name from the backend, the name is null. This means if our view binds to the name, it’ll flicker - first it’s empty then its set.

What we’d like to do is actully say to the router - “I’m going to go to this view, but only when you can tell me my name”.

We can do this with the resolves in the router, here’s how it works:

// Create a function that uses the NameService
// to return the getName promise.
var getName = function(NameService) {
 return NameService.getName();
 };

$routeProvider
 .when('/home', {
 templateUrl: '/home.html',
 controller: 'MainController'
 })
 .when('/profile', {
 templateUrl: '/profile.html',
 controller: 'ProfileController',
 /* only navigate when we've resolved these promises */
 resolve: {
 name: getName
 }
 })

so now we have a resolve on the route - when we go to the profile page the router will wait until the promise returned by getName resolves, then it will pass the result into the controller, as the parameter called name. Now our controller looks like this:

app.controller('ProfileController', function($scope, name) {

 $scope.name = name;

});

Much better! And also much more testable.

One thing you may wonder - why do I use getName as the resolve function instead of just using NameService.getName directly?

That’s because the route is set up in a config function - and that function cannot have services injected. However, a resolve function can, so we just use a function and let AngularJS inject the NameService for us.

Now for an important statement:

If the first thing your controller does is fetch data from the server, it’s probably wrong.

Why? Because if your controller needs data, inject it - let the router ensure the data is ready. Then you don’t have controllers in an invalid state as they’re loading - and your controllers become easier to test.

Be aware of resolve for routes - it’s a great way to handle loading of required data, authentication and other things that you might be putting into the wrong place.

You can see the example above in action here:

What’s cool is we can also see our caching logic by going to and from the Home and Profile pages. The promises are keeping our code clean and testable.

As a final note on promises when routing, you can specify multiple resolves if you need to:

$routeProvider
 .when('/profile', {
 templateUrl: '/profile.html',
 controller: 'ProfileController',
 /* only navigate when we've resolved these promises */
 resolve: {
 name: getName,
 profile: getProfile,
 anythingElse: getAnythingElse
 }
 })

in this case each resolve is injected into the controller.

Advanced Promises - Tips & Tricks

This section just contains some tips and tricks you might find useful when working with promises.

Promises in directives are not resolved automatically since AngularJS 1.2. Previously, if you passed a promise to a directive with an ‘=’ binding, AngularJS would resolve the promise for you, this is no longer the case.

The Future of Promises

So promises are a core part of AngularJS and to use the framework effectively, you must understand how to use them and how they work. But what is the future of promises?

It’s almost certain that promises are going to become a native feature of JavaScript, they are part of the proposed ECMAScript 6 specification.

The functionality of the q library and AngularJS’ implementation of promises are very similar indeed to the proposed specification, but be aware that when promises become standard, AngularJS is most likely to adapt their own promises to work like native promises.

You can read more at html5rocks.com/en/tutorials/es6/promises/.

Just be aware that you’ll see promises more and more, in other frameworks and in vanilla JavaScript.

Wrapping Up

I hope this post has been useful to understanding promises. Any feedback is always good, so let me know if anything is unclear or could be improved. To finish this article, here are some useful links:

The Q library github.com/kriskowal/q
The AngularJS $q Service docs.angularjs.org/api/ng/service/$q
Promises in ECMAScript 6 html5rocks.com/en/tutorials/es6/promises/
XmlHttpRequest, which we used in an example developer.mozilla.org/en/docs/Web/API/XMLHttpRequest

And also some interesting discussions:

Why I am switching to promises - Written by Gorgi Kosev, great article describing why a switch from callbacks to promises can be a very good thing in NodeJS applications.

Callbacks, sychronous and asynchronous - From Havoc, this post contains many useful points for API writers who are using callbacks or promises. One key takeaway is to never do what a sample in this article does which is resolve a promise either synchronously or asynchronously, as it leads to code which can be difficult to reason about. I’ll be mentioning this more in a later update which will explain the problem and solution.

Designing for Asynchrony - Written by Isaac Z. Schlueter, this post is another great one for API designers that takes a look into asynchrony.

ECMAScript 6 on dwmkerr.com

Getting Started with React & ES6

Building the Code

Using ES6!

Adding some React

Testing

Adding Code Coverage

Wrapping Up

Glossary of Conventions

Always support install/test/start

Footnotes

The Best Module System for AngularJS Applications

Words for Gulpers

What about other stuff?

AngularJS Promises - The Definitive Guide

Contents

What are Promises?

How do Promises Work?

A Real World Example

Promises - Success, Error, Then

Advanced Promises - Chaining

Advanced Promises - Routing

Advanced Promises - Tips & Tricks

The Future of Promises

Wrapping Up