AngularJS on dwmkerr.com

Moving from React + Redux to Angular 2

Mon, 25 Apr 2016 09:45:00 +0000

I’ve just finished working on a very large project written in React and Redux. The whole team were new to both and we loved them.

I’m going to share my experiences of experimenting in Angular 2 with you, from the point of view of someone who needs a pretty compelling reason to move away from my JSX and reducers.

The Journey So Far

Let me highlight a few key moments in my UI development experiences, to give a bit of context to my ramblings.

Reading about redux was a lightbulb moment for me - rather than a complex framework it’s a simply library to help apply a few common sense functional programming principles - state is immutable, functions apply predictable transformations to data to produce new data.

Learning React took a little bit of getting used to, but not too much, it was quite a bit more simple than Angular anyway.

Long story short, simple React components and rigorous state management has so far resulted in the most manageable and well written very large scale UIs I’ve worked on so far - can Angular 2 compete with this?

First Step with Angular 2 - Folder Structure, Typescript, Sublime Text

I checked out the pretty neat ‘Getting Started’ guide from Angular which promised to get me started in five minutes.

It didn’t take five minutes, there’s a few gotchas, so I’m going to give a condensed guide here.

Step 1: The Folder Structure

The first few steps of the angular guide creates the following folder structure:

|-- angular2-starter
|-- tsconfig.json
|-- typings.json
|-- package.json

This is the standard package.json with some scripts ready to go. We also have tsconfig.json to configure the typescript compiler and typings.json to provide info to the compiler on where to get type information.

You can check the code at this stage here:

https://github.com/dwmkerr/angular2-starter/tree/step1

Node & NPM Issues

At this stage the quickstart says you can run npm install and all will be well:

npm ERR! cb() never called!

Not so good! For the record I’m using NPM 3.7.3 installed via homebrew. This looks like a bug in Beta 15 (see Issue #8053).

I fixed this by using n to upgrade my node version:

$ node -v
v5.9.0
$ npm install -g n # install 'n' node version manager
$ sudo n latest
installed : v5.11.0
$ node -v
v5.11.0

Now it npm install runs OK.

Step 2: Adding Components and Configuring Sublime

The next steps of the walkthrough take us through adding an app component, a main.ts file to bootstrap the application and an index file. You can check the updates here:

https://github.com/dwmkerr/angular2-starter/tree/step2

Essentially we now have:

|-- angular2-starter
|-- tsconfig.json
|-- typings.json
|-- package.json
|-- index.html
|-- styles.css
|-- app
|-- main.ts
|-- app.component.ts

At this stage, running npm start gives us a browerserified app to play with:

Clear enough so far, although the code in Sublime is not looking so pretty:

Quickly installing the TypeScript plugin from Microsoft[^n] seems to do the trick:

If you need more details, here’s a gist with the full setup for Sublime 3, assuming you’ve got nothing installed.

https://gist.github.com/dwmkerr/04fa8b8c15d049d0381e7798a79bcc45

At this stage the app will run, we can see the basics of the Angular 2 syntax and start experimenting.

Step 3: Adding some components

At this stage the quick started guide starts going into more detail, guiding you through the process of creating multiple components. I decided to go off on my own here, with the rough plan of being able to write a set of goals for the day and turn it into a check-list[^n].

Within not much time I had the some basic components, input and output, bindings and so on. Some screenshots:

You can take a look at the code at this stage by checking out the ‘step3’ branch:

github.com/dwmkerr/angular2-starter/tree/step3

Thoughts so far

For now, that’s all I’ve got time for. I’ve had a chance to get a feel for Angular 2, I’m going to come back to this in a few weeks and integrate Redux, maybe swap out System.JS for Webpack and do some experimenting.

Opinions[^n] so far?

Not Sold on TypeScript

I’ve used TypeScript in my mess around, rather than plain ‘ol JavaScript, to keep the experience authentic to the angular team’s goals of using TypeScript to help.

So far, I’m not seeing an enormous benefit. Some of the extra information available to auto-completion in nice, but this is a tooling thing.

JavaScript is not a static language, the TypeScript annotations I find slowing me down a little.

There’s so much extra domain specific stuff in Angular 2 that people might be lost without it. But if your stuff is so complex you need to adapt the base language, is it too complex?

Explicit Component Surface Areas are a Nice Idea

When defining a component, you specify explicitly what comes in (data) and what goes out (events).

This means that the surface area of a component (i.e. the part you touch if you interact with it programmatically) is well defined. This is a good thing.

However, this is all handled with some pretty framework-specific stuff[^n]:

// e.g.
export class GoalsBoxComponent {
 // Event we fire when the goals change.
 @Output() goalsChanged: EventEmitter<Goal[]> = new EventEmitter();
}

// e.g.
export class GoalListComponent {
 // Input is a set of goals to render.
 @Input() goals: Goal[] = [];
}

In a nutshell…

Explicit component surface area is a cool idea.

React does this too with the optional propTypes, but it is not enforced. However, how this is done in Angular has already gone through a few radical changes with some lively debate.

Not ready for production… yet

There’s no standardised, documented way to test a component - nuff said. But things are evolving quickly.

Framework Fatigue

Comparing React to Angular is unfair, one is a view library, one is a framework. But it’s worth pointing out this is a pretty complex framework. There’s a lot of very domain specific stuff. See this documentation for an example:

<li *ngFor="#hero of heroes">

From the documentation:

The (*) prefix to ngFor indicates that the <li> element and its children constitute a master template.

…

The # prefix before “hero” identifies the hero as a local template variable. We can reference this variable within the template to access a hero’s properties.

You’ll get used to it (if you have to), but I think it’s harder to reason about than:

render () {
 return (
 <div>
 {this.props.goals.map((goal) => {
 return <li>{goal.title}</li>;
 }</div>);
}

OK fair enough, JSX is very specific, but the logic (mapping an iterable) is JavaScript.

Wrapping Up

That’s it, for now. Next steps are to experiment more, see if it will play nice with Redux and share the next set of opinions.

I’d love to hear what you think, so drop your comments below!

Footnotes

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.

Fixing Memory Leaks in AngularJS and other JavaScript Applications

Tue, 03 Mar 2015 14:35:36 +0000

Dealing with memory leaks in JavaScript applications can be a complex process. In this article I’m going to show you how to identify whether you have memory leaks, analyse them and ultimately resolve them.

I’m using an AngularJS application to demonstrate the concepts and approaches, but much of this material applies to any JavaScript application.

Understanding Memory Leaks
- What is a Memory Leak?
- Why is a Memory Leak Bad?
Identifying Memory Leaks
- Method 1: The Wrong Way
- Method 2: The Timeline
- Method 3: Recording Heap Allocations
- Method 4: Heap Snapshots
Analysing Memory Leaks
- Analysing the leak in Scenario 2
- More on Graphs
Fixing Memory Leaks
- Three golden rules
- Anti-patterns to avoid
The Future
- Weak Maps
- AngularJS 2
- Even Better Browsers
Appendices
- Thanks
- Mysteries
- Futher Reading

Understanding Memory Leaks

If you’ve dealt with memory leaks before, or the patterns of memory usage we sometimes call memory leaks in memory managed applications, then you can probably skip to Identifying Memory Leaks.

If not let’s start with some theory.

What is a Memory Leak?

A memory leak, at least in the world of unmanaged applications, is what occurs when you allocate memory and forget to free it. In pseudo-code¹:

void leaky()
{
void* memory;
memory = malloc(1000);
/* malloc just gave us some memory, use it! */
}

memory will hold the address of the memory we’ve allocate. We use the memory, then the function ends. memory goes out of scope and whatever address it held is lost - but we didn’t free the memory! Not only that, we’ve lost the address of it so can’t ever free it in the future - it’s leaked.

This memory is lost to the application - we can’t release it. Only terminating the process will release it back to the operating system.

When we allocate memory and don’t release it when we are done, we have ’leaked’ that memory.

So how do we get memory leaks in JavaScript applications? We don’t allocate memory directly, the engine does it for us, and it cleans it up afterwards as well².

If we hold on to objects longer than we need to, that will give us similar results. Let’s look at some code:

function ChessManager() {
 this.moves = [];
 this.makeMove = function(move) {
 this.moves.push(move);
 };
 this.newGame = function() {
 moves.clear();
 };
}

Here we’ve got a bug - the newGame function doesn’t clear the ChessManager’s moves, it just throws a null reference exception. But we could use this class in our code. In theory if we keep on calling makeMove we’ll just grow and grow the moves array. This is a bug leading to memory that can’t be freed, even though we don’t need it.

That’s a contrived example of a JavaScript memory leak.

When we are finished with memory but don’t allow the garbage collector to clean it up, that’s a memory leak.

At least for the purposes of this discussion. We’ll see it’s a very easy thing to do.

Why is a Memory Leak bad?

It might seem obvious but let’s just make sure we’re explicit with everything. As we said in the initial definition, we allocate memory but don’t deallocate it.

In some circumstances, this is not necessarily a disaster, if we don’t leak too much too often, but there are circumstances where this is very serious.

Memory leaks cause performance problems, slow down applications and can lead to a process terminating. There are some times when that’s really not good.

Servers and high performance applications shouldn’t leak, especially as many should be expected to run for long periods of time. Mobile apps or apps for embedded systems will need to deal with fewer resources and will suffer if they leak. Any application an end user is expecting to use for a long time will cause a lot of frustration if it leaks.

That’s enough theory, let’s actually start looking at identifying memory leaks in the context of an AngularJS application.

Identifying Memory Leaks

I’ve created a sample app for showing photo albums which is leaky in parts. The app is at:

dwmkerr.github.io/angular-memory-leaks

It’s a very basic app with a fairly common set of components; Bootstrap, jQuery and AngularJS. We’re going to take a look at how we can identify whether this app suffers from memory leaks.

You can run the app in your browser, or run it locally with the commands:

git clone https://github.com/dwmkerr/angular-memory-leaks.git
cd angular-memory-leaks
npm install && bower install
gulp

Running gulp will serve the app, lint, and reload the browser when you change the code. The project page is at github.com/dwmkerr/angular-memory-leaks.

Method 1: The Wrong Way

First, just be aware that the wrong way to look for leaks is by examing the memory usage of the Chrome process. While an increasing amount of memory usage can indicate a leak, it is not reliable. Why?

Well browsers can allocate memory and use it how they want to. A page it is rendering may no longer need as much memory as it needed before, but that doesn’t mean the browser needs to release it to the OS. It may just keep it to avoid having to re-allocate it later on.

Method 2: The Timeline

Open the Chrome developer tools. Go to ‘Timeline’ select ‘Memory’ and hit ‘Record’.

Now start using your application. After you are done, stop recording. You’ll see a graph of memory usage.

This is almost exactly what we need. I’ll explain the almost shortly, but lets take a look at this graph.

We see a Used JS Heap in blue. Used is important here - Chrome is telling us that there may be more heap usage than shown in its actual process, but what we are seeing here is what is actually used by the page.
We see documents (in this case a steady value of one document).
We see DOM nodes. As I use the app the nodes increase, up until a certain point and then they drop.
We see Listeners (i.e. even handlers). Again, these increase as I use the app and then drop.

So what should we be looking for in this graph? That depends on what our app is doing. But let’s imagine the we are navigating through different photo albums in the albums app. We’ll need more memory to see each album, but once we leave an album we don’t need that memory any more. So we should get a healthy saw-tooth pattern³:

Here we see that we use more and more memory, up until the point that Chrome garbage collects, then goes back to where we started. This is repeated again and again. This is a good sign - when Chrome garbage collects we go back to the same place we started, a strong indication we are not leaking much memory.

If we are doing some work which simply needs more and more memory, and we don’t release it, we would expect to see steps instead⁴:

An example of this might be an infinite scroll situation. I’m looking through a vast photo album, and when I get to the bottom of the screen I load more images automatically. The ones I’ve loaded are still in the DOM so cannot be released. We see no saw-tooth because there’s no release of memory. However, this is not a memory leak - it’s just increasing memory usage. It does mean that if we allow the user to scroll too much we may run out of resources though.

The dangerous case is the one below:

Let’s imaging we’re using the application, navigating through albums, returning the the home page, looking through some more albums and so on. We keep using memory, and Chrome keeps on garbage collecting, but we never quite get back to where we started. We are trending towards increasing memory usage. This indicates we might be leaking memory.

Might is not going to cut the mustard, we need to know categorically what is going on and whether we have a leak.

You said this is ‘almost’ exactly what we need?

Unfortunately, you cannot always trust this graph. See Mystery 1 for the ugly details. Suffice to say that what we’re seeing here is an indicator only, but for more detail we need to look at Method 3.

Method 3: Recording Heap Allocations

Let’s look at a different way of seeing if we’ve got a leak, the ‘Heap Allocations’ view. In the developer tools, go to ‘Profiles’ and ‘Record Heap Allocations’:

When we record heap allocations we get a chart showing us spikes as we allocate memory. These spikes are initially blue (meaning Chrome is using the memory), then change to grey once the memory is freed. If we see spikes or sections of spikes that remain blue, we may have a problem.

Try this, go to the Ablums app and start recording. Click on the ‘India’ album, then go back to the home page. You should see a chart like this:

So we start recording and nothing is being allocated. Then we click on the ‘India’ album (point 1) and we get a few spikes, as chrome allocates memory needed for the content in the new page. Then we click back on the home page (point 2). Some of the memory used in the India album is released (it looks like about half). One spike of memory used for the home page is still in use (what we’d expect) and another spike or two seem to be freed. These other spikes might be memory used for the actual transition, for example in logic in the router.

So this looks like we may have a problem in the album page. In fact, we can drag a selection box around those first three spikes and see what is still in memory (i.e. what might be a potential leak) in the view below:

Dissecting this view we have:

A subset of the data, the blue spike from the album page which is still in use.
The ‘Heap View’, which shows us different types of data in memory. Don’t worry, we’ll see a lot more on this later.
An instance of a specific type of data, in this case an instance of a JavaScript object.
The retainers graph for the specific object.

We’re going to look into what all of this means in a lot of detail as we go through the article. For now, I’ll simply state what we’re seeing, by the end of the article you’ll be able to analyse this (and much more) yourself.

In this snapshot we see a small amount of data still in use. A quick look through the data reveils we have data still in use which relats to the AngularJS template cache.

This is good! It means this is probably not a leak. When I first visit the album page AngularJS is caching the template used to render it, so of course it stays in memory.

When analysing memory usage remember that caching, preloading and other optimisation techniques may cause some noise.

So if we have the albums page in a cache, in theory the next time we visit the page and then return to the home page, we should free a lot more of the memory (because the new memory we allocate will be just for the page itself, not the cache which is already set up). Let’s try it. We’ll record going to the album page, back to the homepage, then the album page and back again:

This is looking good.

We go to the ‘India’ album. Some memory used is now freed, but much is still in use. As we saw, at least some of that is the template cache.
We go back to the home page, lots of memory is used but by the time we’re done recording it’s almost entirely freed.
We visit the India album a second time, requiring some memory almost all of which is freed.
We go back to the home page. Some memory is used during the transition and to render the page, some of that is still in use (which is expected as the page is still open).

The heap allocations chart is exceptionally useful in identifying memory leaks, it has already led to some insights:

Initial loading of pages increases our ‘baseline’ memory footprint due to data being added to caches (such as the AngularJS template cache).
Subsequent loading of pages requires memory, but the vast majority of it is freed.

One thing we noticed from this brief analysis was that the initial result was slightly misleading. With the heap allocations view repeated operations can help you identify trends. In the Albums application I’ve actually set up part of the app to run repeated operations, so we can try to consistently test scenarions. The ‘scenarios’ menu lets us run them. Let’s try running scenario 1.

This scenario will navigate from / (the home page) to /nowhere ten times. /nowhere isn’t matched by the router so takes us back to the home page. This has the effect of reloading the home page 20 times (just reloading doesn’t work, the router is smart enough to realise we’re staying on the same page).

While you are recording the chart you can see peaks go from blue to grey as memory is freed. Let’s see what we’ve got.

Shows our first navigation, some memory is not freed. Everything before this is setup code.
Our last navigation. Some memory still in use (as expected).
A glance at memory in use shows some compiled code and system data (more on this later). At this stage we don’t need to worry, Chrome will allocate data like this when it needs to.
It looks like the 11th page load didn’t free all of it’s memory. This is potential cause for worry.

Altogether this a very healthy looking scenario. The huge majority of what we allocate is freed, as we would hope. Small amounts of memory stay in use (mostly used under the hood by Chrome) and a small amount of memory after the 11th reload is not freed (a quick look suggests a timing issue, definitely something we’d want to investigate further in a real-world app). Our allocations are in the 50 KB to 100 KB range and we’re looking good.

Before we say goodbye to the Heap Allocations view (for now) let’s do the same for Scenario 2 (moving from the home page to the top rated page 10 times).

We are not going to analyse this issue (yet!) but this is an example of a much less healthy chart. In this chart we seem to be allocating memory for each page view and not releasing it. This kind of chart definitely indicates that there could be problems.

So we’ve seen the Heap Allocations view, which is a bit more sophisticated than the memory usage graph. Let’s look at the last way to analyse memory leaks - snapshots.

Method 4: Heap Snapshots

The final method of identifying memory leaks is the most sophisticated and finely controlled. We will take snapshots at specific points in time and analyse the differences between them. To take a snapshot, we go to the Profiles view and choose ‘Take Heap Snapshot’:

When we take a heap snapshot Chrome simply records the details of all memory allocated.

Remember: Taking a Snapshot always runs garbage collection first.

A heap snapshot shows you exactly the same kind of data you get in the Heap Allocations view, except that you are seeing ALL memory in use, not just objects which were allocated and are still alive:

This view is very complete but not necessarily very useful. There’s some extra ways to see the data (if you change from ‘Summary’ to another view or change ‘All Objects’ but we’ll see that later).

Staying on topic, we’ll not yet look in detail at what the data is that we are seeing, we’ll first look into identifying whether there are memory leaks - then we’ll look into tracking them down.

Indivdiual snapshots are not so helpful for checking for leaks, but what is very helpful is the ability to compare memory used between snapshots.

Let’s take some snapshots, try this:

Open the app.
Navigate to the top rated page (caches should now be set up).
Navigate to the home page. Take a snapshot.
Navigate to the top rated page. Take a snapshot.
Navigate to the home page. Take a snapshot.

Now we can do something really cool. Select snapshot 3, and choose to view data allocated between snapshot 1 and 2. This means we’re seeing data allocated for the top rated page, which is still in use when we go back to the home page, i.e. probably leaked.

So what are we seeing now?

We have three snapshots. The size of each one is shown. Sometimes the very first one seems overly high. See Mystery 2. We have selected the 3rd snapshot and are therefore only able to see data still present in this snapshot.
We are chosing to show only objects allocated between Snapshot 1 and 2, i.e. objects allocated to present the page. But we’re in snapshot 3, so we’re seeing those objects which were allocated and are still present.
Objects allocated are looking suspicious - we’ve got DOM elements. This doesn’t look good!

This is the best way to identify memory leaks. So now that we’ve seen how to identify whether we have memory leaks, or at least that we have a potential problem to analyse we can move onto step 2 - Analysing Memory Leaks.

Analysing Memory Leaks

If we think we have a memory leak, we need to be able to look at the heap data and see what’s going on. Whether we are seeing heap data from a selection of allocations from the Heap Allocations view or from the Heap Snapshots, we see the same kind of information:

Starting from the left we have the ‘Constructor’ column. This is the type of object we have. Some of these objects we can see are JavaScript classes (constructed with a new call to a function), such as Scope. As well as our own classes, we have some special classes of data:

(compiled code): Represents JavaScript code compiled by Chrome. Consider this internal - we have no control over it.
(array): Internally used array object. Again, internal.
Array: A JavaScript array. Often we have a lot of data in arrays.
Object: A plain old JavaScript object.
(closure): A closure.
system / Context: The underlying data require to call a function, for example the actual data used by a closure.
system: Internally used data.

There are also plenty of objects that are created by Chrome, such as HTMLDivElement, which is a wrapper around the internally used (native) DOM object.

Let’s dissect some of these objects in detail. Running Scenario 3 allocates some data and puts it on the window object. This is really trivial data but shows a lot. You can use the Heap Allocations View or Heap Snapshots to see the data. I’ve taken three snapshots (once before pressing OK, once after the data is allocated, and the final one when the last modal is closed):

This data has come from the code below:

// Create a class which will hold heap data. Makes it easier
// to find the data in Chrome.
function HeapData() {}

// Create a heap data object.
var heapData = new HeapData();

// Create a function that multiplies two numbers.
function multiply(a, b) {
 return a * b;
}

// Create a 'multiply by' function, which curries the above
// to generate a function which multiplies by a constant. This
// will involve closures.
var multiplyBy = function(a) {
 return function(b) {
 return multiply(a, b);
 }
};

// Add some data to our heap data object.
heapData.fry = "Philip J. Fry";
heapData.zoidberb = "John " + "Zoidberg";
heapData.character = {
 firstName: "Amy",
 secondName: "Wong"
};
heapData.double = multiplyBy(2);
heapData.multiplyBy100 = multiplyBy(100);
heapData.doubledNumber = heapData.double(18);
heapData.multipliedNumber = heapData.multiplyBy100(15);
heapData.div = document.createElement("div");

// Put the heap data on the window, it is now pinned to a GC root.
window.heapData = heapData;

We’ve got a little bit of everything here, some code, some closures, some objects and a DOM element.

As we’ve put most of this data on the heapData object, which is an instance of HeapData we can easily find the object:

So we can see the HeapData constructor, expanding it we see an instance of HeapData. The @420269 is a unique ID assigned by Chrome. If we have lots of heap data objects, we can use this to distinguish between them when we’re looking at other parts of the snapshot. What else do we see?

Distance. How far the instance is from a GC Root. A GC root is anything that can ‘pin’ objects, for example the window object which holds globals. If put something on window it will never be freed, this is what makes it a GC root. Our distance is 2 as we have HeapData (constructor) to heapData (instance) to window.
Objects count. Only valid for the top level nodes, this shows us how many objects of the specified type we have. We have 1 HeapData object.
Shallow Size. The size of the data that is directly allocated for the object. Compare this to Retained Size.
Retained Size. The size of data this object is retaining. For example, out heapData instance holds a reference to an object which contains two fields firstName and secondName. Our shallow size includes enough data for the reference, the retained size includes the full retained size of the retained object.

Notice that our instance of HeapData is highlighted in yellow? That’s a convenience from Chrome, it’s showing us objects which are directly accessible from JavaScript. Our object can be accessed via window.heapData, therefore it’s directly accessible. Other objects we’ve created might not be (for example, a variable used in a closure exists and is on the heap, but not directly accessible).

Let’s see some other data we allocated:

Now we’re looking at closures. We have two closures in yellow next to each other, clicking on one shows the retainer graph. What is going on here?

Our closure is not a simple thing. It has code (of course), which takes up memory. We won’t look into this in detail. It has shared function data (again, internally used and not worth looking into). We also have a reference to a __proto__ (a function object has a prototype!). Finally, we have the context, which contains enough data to call the function. If we look in to the context we will not see much, as our function contains numbers which Chrome can simply store in the code. However, if we use references in closures we’ll actually see them in the context.
We also have the retainers. Our closure is referenced via a variable called multiplyBy100, which itself is referenced by heapData, which if referenced by the window GC root.
The multiplyBy100 variable is also dominated by the second element of an array with id @227339.

The last thing we’ll look at in this snapshot is the div element.

We can see the div element is retained by the div variable in the heapData object. We can also see it is made up of a prototype and some native object. The native object shows no size - don’t be fooled. That just means its taking up no JavaScript heap memory. It is still using memory (just in V8 engine not the JavaScript code).

What’s important to note here is that the element is shown in red. This means it’s detached. So it exists, is referenced (and therefore cannot be garbage collected) but is not in the DOM. This is not necessarily a problem, but lots of detached DOM elements is often a bad sign, especially if the number is increasing.

The rest of the data you can look through yourself. You’ll notice some interesting things, such as how concatenated strings work, but the important stuff we’ve now seen.

Let’s move on to analyising the first potential memory leak we discovered - the transition to the Top Rated page of the albums app.

Analysing the leak in Scenario 2

We saw that Scenario 2 (switching to and from the ’top rated’ view) seemed to leak memory. Let’s use the heap snapshot comparison view to analyse this further. The steps are:

Navigate to the home page.
Navigate to the top rated page (setting up the cache).
Navigate to the home page, take a snapshot.
Navigate to the top rated page, take a snapshot.
Navigate to the home page, take a snapshot.

We can now look at the memory allocated between 1 and 2 which is present in 3 (i.e. what we allocated for the top rated view and potentially leaked):

Some things jump out immediately:

We have gone from 7.5 to 8.4 to 8.5 MB. We are changing from one view to another - and ending in the same place that we started. We should be going back to 7.5 MB.
We’ve got a lot of objects still hanging around, not just system data like compiled code, but HTML elements, detached DOM elements, Promise objects, n.fn.init objects and so on.

This looks like a classic leak situation. Let’s start by looking at some objects we recognise. There are some Scope objects near the top of the chart, let’s look at those.

We’ve got some Scope objects, three in fact. These objects contain the usual AngularJS fields such as $parent, the only field which distinguishes this scope is the album field. If we look at out aml-rated-album directive it looks like it could be the isolated scope for this directive:

.directive('amlRatedAlbum', function() {
 return {
 restrict: "E",
 scope: {
 album: "="
 } // etc

This scope has an album field. There are three albums so it looks likely these are the three albums in the top rated page, the scopes stil in memory. What retains them?

Looking at the retainers (at 2) we don’t see much. We’re retained by a $$ChildScope, which also retained by a $$ChildScope object. In fact we have quite a complex graph of objects.

When we leak a scope in AngularJS, we leak a huge graph of objects.

Scopes know about their parents. They also know about their children, and siblings. If we inadvertantly pin a scope to a GC root, we will probably leak almost all of the scopes in the page.

Why? The graph below should show why. I ’leak’ a scope, and by doing so I retain all of the other scopes, because they are connected. Having a connected graph of scopes is required for angular to work, but it means that we we are extremely susceptible to leaking a lot of data.

This graph shows $parent retained relationships, but don’t forget scopes also know about their children and their siblings, so real graph is even more highly connected.

So just grabbing a specific scope is not good enough. We need to try and be a little bit more specific. Let’s try starting from an element instead. Here we take a look at a div element and its retainers:

Resting the mouse over the instance of a leaked HTMLElement shows a bit of data about it, it’s a aml-rated-album and it is detached. Definitely a symptom of our leak. Let’s see the retainers:

Ouch. This is nasty. Again, we are not seeing much that is particularly useful. We have a long graph of retainers starting with the compileNode function, we also have an array in a n.fn.init function. To cut a long story short, we’re are not going to easily find the root cause here. But I will share some hints.

jQuery isn’t leaking.

We will end up seeing so much jQuery stuff it is natural to wonder whether jQuery is leaking. Almost certainly not. In the graph about n.fn.init is just a jQuery selector, held onto by $$element. No surprise - all angular elements are jQuery or jQuery light objects. We’ve leaked an element, it just happens to be wrapped in a jQuery selector. (You might see a different type of graph, probably due to the jQuery 1 + AngularJS 1.2 combination, we’ll see it later).

You may see low level arrays containing data associated with a scope in jQuery, again, don’t worry. It’s the jQuery data cache (which we’ll also see later), which is associating elements to scopes.

We can try and work through this graph, but let’s try another tack.

It looks like we’re probably leaking the whole of the top rated view. We’re probably leaking the main scope for the view, created by the TopRatedController. Let’s see if we can find it.

You can find objects you think are leaking by tagging them with classes!

This is a neat trick. Let’s add a couple of lines to our top rated controller:

angular.module('app')
.controller('TopRatedController', function($scope, $http, $interval) {

 // Create a class, assign it to the scope. This'll help us
 // see if $scope is leaked.
 function TopRatedControllerTag() {}
 $scope.__tag = new TopRatedControllerTag();

 // etc...
});

Now when we run the analysis again, we can search in the snapshot for TopRatedControllerTag:

We search for ‘Tag’, finding one instance of the TopRatedControllerTag.
Bingo - it is retained by a Scope, with id @534851

Let’s look at this scope in more detail. Right click on it and choose ‘Review in Summary View’, so we can see what is retaining it:

We can now see the root scope for the actual view.
We can see the usual pattern of $$ChildScope and $parent properties, but what else have we got?

Intestingly we can see that our scope is also retained by a context variable called $scope. How do I know it is a context variable? It’s in blue, part of the colour coding (see Mystery 3).

What is a context variable?

A closure is a function which refers to a variable outside of its definition. A context variable is the variable stored in a function context. A function context contains the environment for a closure, which is the data required to execute it.

So basically we have a closure which refers to a variable called $scope, which is the root scope of our view. We can see in detail the closure:

$scope is retained by a context for a closure.
The closure is in the refresh function (this is why the context is retained by refresh).

We can open the function and examine it for issues. There’s an $http.get which has as closure which uses $scope, but alarmingly there is an $interval registered to run every 10 seconds, which is never deregistered. The interval callback uses another $http.get, with a closure that uses $scope. This is the problem.

A simple timeout we forgot to deregister has a closure on $scope. $scope can therefore never be cleaned up, because it is retained by a context.

Some important takeaways:

The framework hides implementation details. Often useful, but in this case it made finding the leak a problem.
This example seems contrived, but how how often do you have a closure using $scope in a controller? In real world apps all of the time time, callbacks to ajax requests, event handlers, promise functions etc.
A leak of a small object that contains the data for three albums has leaked a large graph of other objects, and even DOM elements.

Leaks are not incremental. You don’t get an accumulation of small leaks, one small leak can retain a huge graph.

Let’s talk about this a bit more.

Dealing with Object Graphs

We saw before that a chain of retainers can pin an object, such as a scope, to a GC root. We also saw that AngularJS scopes are part of a highly connected graph, meaning that if we leak part of it, we probably leak it all:

However, things can get worse. Remember how in an angular app you can get the scope for an element with $(selector).scope()? This connection between a scope an an element is maintained in the jQuery data cache. This lets us associate arbitrary data with an element. This introduces another layer of connectivity:

In this graph, we see the jQuery data cache entries (in grey) associating DOM elements to scopes, introducing more connectivity.

We can see here an alarming increase in the size and potential complexity of the graph. We’ve got DOM elements in play now. The chances are that if you are reading this you are dealing with a memory leak in your app, if it’s noticable enough for you to deal with it, you probably have a non-trivial graph.

So how do we fix memory leaks? I’ll show three general approaches and how to use each one.

Fixing Memory Leaks

Fixing memory leaks is hard. As we have seen our problem is highly connected graphs. If we have a part of the graph we want to free for garbage collection (such as a scope and all of it’s children, such as a view or directive) then we must not retain that graph of objects. This means if you have (for example) three problems that lead to retaining a graph, you have to fix all of the problems before the leak goes away.

Let’s generalise the best practices first into three rules, see patterns we should follow for each of them and then look at anti-patterns to avoid.

Three Golden Rules

Rule 1: Understand the framework and lifecycle.

If you are using a framework like AngularJS, you must understand the lifecycle of the objects you are dealing with. Unless you understand how the framework tries to clean up, you may make mistakes that stop it from working.

Rule 2: Be careful at the interface between short and long lived objects.

Whenever you see an interface between a short and long lived object, be extra careful. For example, if you have a directive talking to a service, make sure the service cannot retain the directive through closures, callbacks or any references. Services will last for the lifetime of the application, so they are the sort of object which can inadvertantly retain short lived objects.

Other long lived objects exist but may be more subtle, the interface between AngularJS and other libraries can be a risky area, if other libraries maintain long lived state.

Finally, consider this. The isolated scope for a directive (for example) may inadvertantly be long lived - if it is leaked. That leads us to Rule 3.

Rule 3: Disconnect the graph.

You can be defensive by manually disconnecting graphs of objects. This can aid if you have a memory leak you cannot resolve. By disconnecting the graph, the garbage collector will at least be able to attempt to clean up parts of it.

AngularJS should attempt to do this for you, for example when scopes are destroyed the links to other scopes are severed. But you can also do this yourself. Disconnecting the graph is not always as simple as emptying arrays or nulling objects, it can mean nulling closures and context variables too⁵.

The anti-patterns which follow are all violations of these rules.

Anti-Patterns to Avoid

Whether or not your app is suffering from memory leaks, avoid these patterns.

Poorly Managed Event Handlers

Consider a trivial example in a directive link:

function(scope, element, attrs) {
 element.on('click', function() {
 scope.selected = true;
 });
}

We register an event handler. We’ve now built a closure which will have a context, which retains the scope. If we don’t deregister this event handler, we retain the closure, the context, the scope, and then basically everything in the universe.

The Fix

function(scope, element, attrs) {
 element.on('click', function() {
 scope.selected = true;
 });
 scope.$on('$destroy', function() {
 element.off(); // deregister all event handlers
 })''
}

Note: Angular should handle this. It is supposed to deregister event handlers on elements it manages. In my experience this isn’t always the case, although it seems cases when this doesn’t happen are fewer and fewer as bugs get fixed in the framework. Anyway, Rule 3 - disconnect.

Poorly Managed Watchers

Watchers or angular event handlers, basically the same as above.

$scope.$on('someEvent', function() {
 $scope.refresh();
})

Again, Angular should clean this up if you forget to, but the advice is always do it yourself. Angular watchers return a deregister function.

The Fix

var cleanup = $scope.$on('someEvent', function() {
 $scope.refresh();
});
$scope.$on('$destroy', function() {
 cleanup();
})

Rule 1 - know the framework and how lifecycle is handled. $destroy is sent to a scope specifically to allow it to be cleaned up.

Callback Functions on Services

Services (or other long lived objects) should typically not take callback functions. Imagine a ‘user service’, allowing a scope to discover if the user has changed their name:

UserService.onNameChange(function(newName) {
 $scope.userName = newName;
});

Now the service (a long lived object) takes a closure with a context to a short lived object, the scope. Unless the service is written absolutely correctly, we run the risk of the service retaining the scope. Remember, services are singletons and as such the interface between services and scopes is one that requires careful management.

There are two fixes I would suggest.

Fix 1: For a one-off operation, use a promise

// change and name and wait for the result
UserService.changeName("Fry").then(function(newName) {
 $scope.name = newName;
});

The notification service returns a promise (a short lived object) which holds the closure. If we get things wrong, we are less likely to leak the scope. Plus, promises are typically easy to work with once you’ve got the hang of them⁶.

Fix 2: For notifications, use broadcasts

// more like our original example
$scope.$on('NotificationService:ChangeName', function(data) {
 $scope.name = data;
});

Some will say to not overuse broadcasts as they can be expensive. They can, so use them judiciously. But remember, they’re provided by the framework, typically lead to fairly loose coupling and are probably managing clean up as well or better than a hand-rolled mechanism in a service. Rule 2 - don’t tie short lived objects to long lived objects.

The Future

That’s a wrap. Hopefully this article will grow and improve with feedback from the community. To wind up, lets look at a few things that are on their way which will touch on these issues.

Weak Maps

Finally, in ECMAScript 6 we will get a WeakMap⁷ object. This is ideal for something like the jQuery data cache. A weak map uses weak references (not natively supported in JavaScript). This means that we can map a DOM element to a scope in a weak map, but the map entry doesn’t retain the element or scope. If the element or scope is cleaned up, the map entry is removed. This means internal structures to aid with frameworks don’t need to necessarily retain object graphs.

AngularJS 2

Simplifications to the framework in 2.0 and usage of native features like web components mean less complex framework code and less scope for issues. Consider even the usage of classes in Angular 2.0. We don’t decorate a scope object (of type Object) we create an instance of a class. Easier to see in the heap view.

Even Better Browsers

SPA frameworks are driving improvements to browsers. Frameworks like Angular lead to more SPAs. More SPAs mean we find more bugs and edge cases in browsers. Many memory leak issues in AngularJS have led to fixes in V8.

Appendices

Beware any write up long enough to need appendices.

Thanks

Much of my understanding here came from working with others on real-world issues. I would like to thank the following people for their advice and insights:

James Denning, Shaun Bohannon, Arnaud Rebts, Colin Montgomery, Jon Hamshaw, Christian Lilley, Maarten De Wilde

There are others I have worked on with in this area, if I have forgotten to mention you please let me know.

Mysteries

After a large amount of time spent investigating memory leaks, there are still some things which to me are a mystery. If anyone can shed some light, I’d be interested to know.

Mystery 1: False Charts

As mentioned earlier we cannot always trust the timeline, it is not uncommon to see the memory usage in the timeline increase, even though the size of snapshots seems to be staying constant. This may be related to AngularJS Issue DOM Nodes Leaking.

Mystery 2: Odd Snapshot Sizes

It is not uncommon for the first snapshot to be large, and then subsequent snapshots to all be a bit smaller (even without any state changes). Why this is the case I do not know. To test, run an angular app and take some snapshots without doing anything in between. You’ll normally see (for example) 9 MB, 9MB, 9MB. However, it is not uncommon to see 15 MB, 9MB, 9MB.

Mystery 3: Where’s the colour coding documentation?

The Chrome documentation states that the colour coding key for elements in the heap snapshot is available in the tool. I can’t find it anywhere, so had to research to find the details.

The Only AngularJS Modal Service You'll Ever Need

Mon, 16 Jun 2014 00:48:12 +0000

If you need modals in an AngularJS application, look no further. I’ll show you how to use the Angular Modal Service to add Bootstrap Modals or your own custom modals to your application.

See it in a fiddle or check out a full set of samples online.

[Using the Angular Modal Service](#UsingTheAngular ModalService)
A Quick Example
Design Goals
How It Works
Wrapping Up

Here’s how you can use the Angular Modal Service to add a bootstrap modal to your application.

Step 1: Install with Bower

Install the service with bower:

bower install angular-modal-service --save

If you don’t use bower, just get the source directly from the dst folder of the repo.

Step 2: Include the JavaScript

Include the JavaScript from the dst folder or require it with require.js:

<script src="bower_components\angular-modal-service\dst\angular-modal-service.min.js"></script>

Step 3: Add it as a dependency

Make sure the angularModalService module is listed as a required module for your application:

var app = angular.module('myApp', ['angularModalService']);

Inject ModalService into any controller, directive or service and call the showModal function to show a modal:

app.controller('SampleController', function($scope, ModalService) {
ModalService.showModal({
templateUrl: "template.html",
controller: "ModalController"
}).then(function(modal) {
//it's a bootstrap element, use 'modal' to show it
modal.element.modal();
modal.close.then(function(result) {
console.log(result);
});
});
);

This code loads the HTML from template.html, adds it to the DOM, creates a scope for it and creates an instance of a ModalController.

When this is done, the promise returned by the showModal function resolves and you get a modal object. This object contains the element created. If it’s a Bootstrap modal just call modal to show it, if it’s a custom one you can show it by changing its CSS styles or using whatever APIs are provided. There’s an example ofa custom modal in the samples.

The controller that is created always has one extra parameter injected into it - a function called close. Call this function to close the modal, anything you pass to it is passed to the caller as the result object.

app.controller('ModalController', function($scope, close) {
// when you need to close the modal, call close
close("Success!");
});

You can pass a number of milliseconds to wait before destroying the DOM element as an optional second parameter to close - this is useful if the closing of the modal is animated and you don’t want it to disappear before the animation completes.

A Quick Example

Here’s a fiddle of the modal service in action:

One thing to note in this examples is that the template is just declared in the DOM - this works fine because the service always checks the template cache before attempting to load it from the server.

There are more examples at dwmkerr.github.io/angular-modal-service.

Design Goals

There are some other services for handling modals out there, notably Fundoo’s Modal Service and a few others. However, the design goals for my service were slightly different:

No link to bootstrap. Bootstrap modals are complex with lots of options - if you want to use them then that’s great, the service should work with them, but the complexity of the options for Bootstrap Modals should not increase the complexity of the service.
Extremely simple code. It’s rare you’ll write something that it will suit everyone’s need. Rather than trying to please everyone, I want a service that is simple enough to understand so that it can be easily adapted by others.

So the core goal here is simplicity - if others can understand the code, then they can more effectively decide whether it’s what they need, or build upon it.

With these design goals in mind I built the angular modal service.

How It Works

I’m going to walk through a slightly simplified version of the code because it actually illustrates quite a few important concepts when working with AngularJS.

One of the things that’s useful to know is that this service creates a DOM element, builds a scope for it and instantiates a controller for it - what we’re doing is very similar to what AngularJS does behind the scenes when a directive is created.

So let’s dive in. We’re going to define a service, so we need a module.

var module = angular.module('angularModalService', []);

Now we have our module, we can define our service. I tend to write services in the form of classes, but this is a personal choice - it’s just as valid to return a javascript object that contains functions and data.

module.factory('ModalService', ['$document', '$compile', '$controller', '$http', '$rootScope', '$q', '$timeout',
 function($document, $compile, $controller, $http, $rootScope, $q, $timeout) {

I need a lot of injected components, we’ll see why as we continue. I also use the explicit form of the function which takes the parameters as strings - this is the only safe way to write an injected function if you are minifying code.

 var body = $document.find('body');
 function ModalService() {
 var self = this;

I use the $document object to get the body element, which the modal will be appended to. I then create a class function and record this as self, so that I can refer to the class instance in callbacks and so on.

The next part of the code creates a function that will return the template, given either a raw template string or a template url. The reason we wrap this function like this is that the operation will either be synchronous or asynchronous, and I don’t want the caller to care. So we use promises to wrap the logic.

var getTemplate = function(template, templateUrl) {
 var deferred = $q.defer();
 if(template) {
 deferred.resolve(template);
 } else if(templateUrl) {
 $http({method: 'GET', url: templateUrl, cache: true})
 .then(function(result) {
 deferred.resolve(result.data);
 })
 .catch(function(error) {
 deferred.reject(error);
 });
 } else {
 deferred.reject("No template or templateUrl has been specified.");
 }
 return deferred.promise;
};

If any of this seems confusing, check out my article AngularJS Promises - The Definitive Guide.

Now to the main function.

self.showModal = function(options) {
 var deferred = $q.defer();

The showModal function is going to have to do all sorts of async work - loading the template from the server and so on. So we are going to create a deferred object and build a promise to return to the caller.

var controller = options.controller;
if(!controller) {
 deferred.reject("No controller has been specified.");
 return deferred.promise;
}

Now we validate that a controller has been passed in as part of the options. Notice how just like in getTemplate we use the reject function to deal with error cases. Again, if error handling with promises seems unfamiliar, check out AngularJS Promises - The Definitive Guide.

Next we deal with the template.

getTemplate(options.template, options.templateUrl)
 .then(function(template) {

We’ve used the getTemplate function to get the template, sync or async it doesn’t matter, our logic is the same.

Now we can build a new scope for our modal.

var modalScope = $rootScope.$new();

We’ll refer to this a lot later on. Now for some cleverness.

var closeDeferred = $q.defer();
var inputs = {
 $scope: modalScope,
 close: function(result, delay) {
 if(delay === undefined || delay === null) delay = 0;
 $timeout(function () {
 closeDeferred.resolve(result);
 }, delay);
 }
};

This requires some explanation. First, we create a new deferred object. This is going to be used to build a promise that is resolved when the modal closes.

Now we build an input object. This contains parameters we want to inject to the controller we’re going to create. Any parameters the controller needs, such as $element, $timeout or whatever will be injected by angular. We’re just going to make sure that the $scope that is injected is the one we’ve just created, and that we also inject a function called ‘close’. This function simply resolves the promise we’ve created after a specified timeout.

This means that any controller for a modal can take close as a parameter, and we’ll inject the function that resolves the promise. This promise is returned to the consumer so that they can take action when the modal closes. We also allow the controller to pass a variable to close which is passed to the resolve function as well.

if(options.inputs) {
 for(var inputName in options.inputs) {
 inputs[inputName] = options.inputs[inputName];
 }
}

Without the this code, the service is close to useless. What we do here is allow the caller to provide extra inputs to the controller. Imagine we have a list of items, maybe books for a library program, and when the use clicks on one we want to show a modal. The code that shows the modal needs to pass the selected book to the modal controller - by adding it to the inputs object, the book can be injected into the controller. This allows to client to pass data to the controller, with the parameter of the close function used to return data from the controller.

Ready for some lower level Angular?

var modalController = $controller(controller, inputs);
var modalElementTemplate = angular.element(template);
var linkFn = $compile(modalElementTemplate);
var modalElement = linkFn(modalScope);

Four innocuous lines that are actually quite complex.

First, we create an instance of the controller with name controller. Regardless of what AngularJS injects, we provide inputs to be injected as well.
Now we turn our raw template html into an AngularJS DOM element. AngularJS always works with jQuery or jQuery Lite elements, the angular.element function takes raw HTML and turns it into a DOM element we can work with.
Now we $compile the element. This step goes over the DOM and expands all directives. We’re turning raw DOM elements into elements that are expanded into directives, but we haven’t yet linked this set of elements into a scope. This is the first step of the compile/link process.
Finally, we can link the element. The $compile function returns a link function which we call with a scope to link the DOM elements (fully expanded) to the specified scope.

This is very similar to AngularJS actually handles directives itself - creating a scope, loading a template, turning it into an element, compiling it and linking it.

Why are compile and link separate steps? Think of it like this, the work that is done in compile is actually identical for each instance of a directive (or modal in our case). It’s not related to an instance of a directive or modal, it’s just expanding the elements and directives. So this work can be done once only, saving a lot of time - then we just call link to create an instance of our element, bound to a specific scope. So link logic is always per instance (you have a scope, you can $watch and so on) whereas compile logic is per type of directive.

Based on this, we could in fact cache the results of the compile function on a per-template basis, as they can be reused and linked to a scope as necessary. However this is an optimisation that is currently left out.

Now we can add the fully built element to the DOM and build our return object.

body.append(modalElement);

var modal = {
 controller: modalController,
 scope: modalScope,
 element: modalElement,
 close: closeDeferred.promise
};

We return the four things the caller might need - the controller, scope, element and close promise. When the close promise is resolved, we also want to clean up:

modal.close.then(function(result) {
 modalScope.$destroy();
 modalElement.remove();
});

deferred.resolve(modal);

So when close is resolved, whatever happens we’ll destroy the scope and clean up the DOM. Now we can resolve our promise with the modal object we’ve built…

 .catch(function(error) {
 deferred.reject(error);
});
return deferred.promise;

…and we can pass errors that occured during getTemplate to the caller and finally return the promise we’ve built.

That’s it! With this design we handle errors correctly, can pass data to and from the modal, clean up after ourselves and make sure that units of asynchronous work are handled with the standard pattern of promises.

Wrapping Up

I hope you’ve found the service and some of the details of the code useful, as always comments are welcome, fork the code and have a play - let me know if you think of improvements or have questions,

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.

Practical AngularJS Part 2

Wed, 19 Feb 2014 15:29:29 +0000

I’m going to be working in F# almost exclusively for a short while, so before I throw myself into that I wanted to wind up my Practical AngularJS Part 2 article. It’s ready to rock here:

Practical AngularJS Part 2 - Components of an AngularJS Application

In this article we get a brief introduction to what’s in the toolkit for an angular developers - filters, controllers, services, directives, views and routes. I don’t go into too much detail, we’re just seeing what the different components are. Spread the word, share the article and as always, comments are welcome.

Langton's Ant in Javascript

Sun, 15 Dec 2013 10:47:18 +0000

Langton’s Ant is a great simulation to write to play with a language. Just today I’ve completed my Langton’s Ant write up and published it on the CodeProject, you can see the article at Learn JavaScript Part 3 - Angularjs and Langton’s Ant.

There are some interesting things in the article for angular too - a look at using directives for custom elements, how to handle both the DOM and Angular loading correctly, and timers and intervals. This is the third part on my series on Learn Javascript, the next will focus on NodeJS. Enjoy, share, fork and comments are always welcome.

The default configuration of the simulation is interesting - try a simulation of the form ’left, left, right, right’ for another type of behaviour.

Introducing Practical AngularJS

Mon, 25 Nov 2013 16:16:09 +0000

I was recently at Devoxx in Antwerp, primarily because I wanted to get involved in some of the sessions that were being hosted by guys from the AngularJS team at Google. I’ve had a chance to work a little with Backbone and KnockoutJS and had been recently deliberately holding off looking at AngularJS so I could hit the conference and workshops fresh and unencumbered with any preconceptions.

The sessions were great, and since then I’ve been working on a couple of projects that use Angular. As I’ve always found writing about a topic a great way to really cement what you know about it, and to understand where the holes in your knowledge are, I’ve started a new series of articles called ‘Practical AngularJS’.

This series is a little different to others I’m working on at the moment (such as the seemingly endless SharpShell articles and Learn JavaScript which is taking some time) as I’m writing it on my own blog rather than on the CodeProject. The reason behind this is purely push me into getting better at handling my blog (particularly the code samples) and because the code I’m writing doesn’t need to be associated with download links and so on, it can all be in fiddles.

Anyway, enough chatter - part one of Practical AngularJS is now finished. It’s a new series, so it’s early enough to have a say in where it goes, please comment and share and let me kn0w whether you find it useful, pointless, or anything in-between.

As a short teaser, in Practical AngularJS Part 1 - Introducing AngularJS we take a look at what AngularJS is, why we’d consider using it and when. We start out with a trivial task for a web application, and see how it quickly becomes a bit sluggish and painful to do certain things, then see how using AnguarJS can ease that pain, letting us focus on the important stuff and it help out with the grunt work. We take our initially messy app and make it a lot more manageable, and look into how we can with our new structure start to write unit tests for the logic.

So this is the bulk of Part 1. Unless there’s a strong push for another topic, Part 2 will focus on testing. Testing is core to the development ideals of the AngularJS project and is something that it was built in mind for. We’ll look into how quickly we can write unit tests, and the flexibility that we’ve got.

Rather than advocating patterns such as BDD or TDD, we’ll again shy away from theoretical discussions about what is conceptually the best paradigm and just dig in - playing with the code and seeing what works and what doesn’t. By the end of it you’ll have a good idea of the freedom you’ve got with testing - leaving it up to you to choose the pattern or process that fits your style, or the style of your team and project the best.

AngularJS on dwmkerr.com

Moving from React + Redux to Angular 2

The Journey So Far

First Step with Angular 2 - Folder Structure, Typescript, Sublime Text

Step 1: The Folder Structure

Node & NPM Issues

Step 2: Adding Components and Configuring Sublime

Step 3: Adding some components

Thoughts so far

Not Sold on TypeScript

Explicit Component Surface Areas are a Nice Idea

Not ready for production… yet

Framework Fatigue

Wrapping Up

The Best Module System for AngularJS Applications

Words for Gulpers

What about other stuff?

Fixing Memory Leaks in AngularJS and other JavaScript Applications

Understanding Memory Leaks

What is a Memory Leak?

Why is a Memory Leak bad?

Identifying Memory Leaks

Method 1: The Wrong Way

Method 2: The Timeline

Method 3: Recording Heap Allocations

Method 4: Heap Snapshots

Analysing Memory Leaks

Analysing the leak in Scenario 2

Dealing with Object Graphs

Fixing Memory Leaks

Three Golden Rules

Anti-Patterns to Avoid

Poorly Managed Event Handlers

Poorly Managed Watchers

Callback Functions on Services

The Future

Weak Maps

AngularJS 2

Even Better Browsers

Appendices

Thanks

Mysteries

Further Reading

The Only AngularJS Modal Service You'll Ever Need

Contents

Using the Angular Modal Service

Step 1: Install with Bower

Step 2: Include the JavaScript

Step 3: Add it as a dependency

Step 4: Show the Modal

Step 5: Close the Modal

A Quick Example

Design Goals

How It Works

Wrapping Up

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

Practical AngularJS Part 2

Langton's Ant in Javascript

Introducing Practical AngularJS