I'm Postal for Promises in Angular

I’m POSTAL For PROMISES

@

2014

by: Christian Lilley

about.me/xml

Thursday, January 16, 14

@xmlilley

Intro to Promises on my
blog: christianlilley.com


We're going to move really fast today, but if you want to go in depth, I’ve got some training slides on my blog.
• If you're at ng-conf, chances are, you've at least SEEN promises. They're those weird things you have to
extract your data from when they come out of the $http service, right? So, why do they exist?

UNCERTAINTY
ASYNC


• If you've heard of them, you've probably heard that they're about async. Which is true. But that signiﬁcantly
understates their usefulness. Really, they’re designed in a way that lets them be about the bigger, more general
idea of uncertainty. About being able to crystallize uncertainty about time, space, user-based uncertainty or
almost anything, into a nice neat package, put a bow on it, and give it a super-useful API that provides us with a
gorgeous interaction pattern, that allows you to reason about and make DECISIONS about uncertainty throughout
your application.

BRAINS!!!!


• and they're about helping you make the most of your brain when dealing with that uncertainty. Promises
make engineer brains work better. Zombie approved.


But even though promises ARE about way more than just async, the truth is its what justiﬁes their existence, so
let’s talk async.
In the beginning was the Word, and the Word was Callback, and the Callback was...

meh.


Callbacks: Strengths
They make Non-Blocking I/O possible.
You know how to use them.
</strengths>


Look, callbacks do the job: they make non-blocking I/O possible, and everybody knows how to use them. But...

Callbacks/CPS
NOW, NOW, NOW, NOW, NOW, NOW, NOW
No API for further interaction
No API for crossing contexts
Doesn’t Scale: works fine for 1,
horrible for more
Monolithic Handlers that break your


... they don't scale. They lead us towards huge, monolithic handler functions that try to do everything all at once,
and an attitude towards async that it's something you want to do as little of as possible and get it out of the way.

step1(value1,
function
(output)
{

step2(output1,
function(output2)
{

step3(output2,
function(output3)
{

step4(output3,
function(output4)
{

//
Do
something
with
value4,

quick,
before
it

disappears!!!

});

});

});
});


When you start trying to stack a complex operation with callbacks, things get ugly, and nested, and complex, and
unreadable really quickly. We haven’t even put anything into these handler functions yet, and they’re already a
mess. See this shape forming here on the left? You know what this shape is called?

PYRAMID
OF
DOOOM!!!!


In the PYRAMID of DoOOOOM, we need to do everything RIGHT NOW, because in a second, it's going to be gone.
Forget about coming back and picking up later where you left off. And forget about that code being intuitive and
readable and clear and maintainable.

var
step1Started
=
true;
step1(value1,
callback1);
var
step1State
=
false;
function
callback1(data)
{

step1State
=
true;

step1Data
=
data;

doSomethingWithStep1Data();
}
.... later ....
if (step1State && step1Data) {
doSomethingElseWithStep1();
}

•And if you do invade the PYRAMID of DoOOOOM, and try to implement something that does let you leave off in
the middle of the pyramid and come back later, you’re going to start building boilerplate like this, caching state
variables and outputs, and adding either timers or events to trigger downstream actions.
•It works, but good luck with interop with other modules you didn't write, and good luck passing sequenced
instructions back and forth between scopes that don't all exist yet, and hence can't listen for events.

step1(value1,
callback1);

step2(value2,
callback2);

var
step1State
=
false;
function
callback1(data)
{

step1State
=
true;

step1Data
=
data;

}
.... timer... later ....
}

var
step2State
=
false;
function
callback2(data)
{

step2State
=
true;

step2Data
=
data;

}
}

step3(value3,
callback3);

step4(value4,
callback4);

var
step3State
=
false;
function
callback3(data)
{

step3State
=
true;

step3Data
=
data;

}
.... timer ... later ....
}

var
step4State
=
false;
function
callback4(data)
{

step4State
=
true;

step4Data
=
data;

}
}


And if you want try that with all four of the tasks from that PYRAMID of DoOOOOM, you get this. Mind you, all this
junk doesn’t even include any error or success handlers yet. This is JUST what you need to have to be able to talk
reasonably about whether these four async functions have ﬁred yet, whether they’ve returned yet, and whether
you can do anything useful with their data yet. And NONE of this code is making your application do anything yet.
It’s all just a bunch of imperative-style housekeeping that’s hard enough to keep track of and maintain, and even
harder to reason about and extend.

Promises to the
rescue.



Let's be clear: promises are not a technical innovation in the javascript execution engine. They don't make
anything happen more quickly. They don't execute async operations with different native code. Promises are all
about the brains of programmers, the same reason we do automated testing & TDD, talk about principles like
'single responsibility' and 'least surprise'.
The promise pattern is about making engineers more efficient, enabling them to actually reason about async
sensibly. It allows you to look at async stuff and uncertain stuff, visualize it, and write efficient code AS IF it were
predictable, consecutive synchronous operations. And to link those operations together in virtuous cycles or
ﬂows.

And again, what
promises are not:


• So, if all that’s true, the naiive understanding of promises needs to go out the door:

action(target,
callback, error)
!==
action(target).then(
callback, error)

Promises are NOT simply a syntax replacement for callbacks. There wouldn't be any point in Promises if that was
all there was to it.

Promises are just a
“replacement for
callbacks”...
...if internal
combustion was just
a “replacement for
horses.”

Used right, Promises are a qualitative change, a fundamental shift in how we compose and plan for uncertainty
and sequencing.
So how about an example.

IMPERATIVE

------->

DECLARATIVE


How about if, instead of all that boilerplate I just showed you, what if you could just DECLARE what you want to
have happen? That you want a bunch of uncertain things to happen in a certain sequence, based on some other
uncertain things?

step1.
then(step2).
then(step3).
then(step4)


How about that? Welcome to declarative async and uncertainty with promises.

step1(value1,
callback1);

step2(value2,
callback2);

var
step1State
=
false;
function
callback1(data)
{

step1State
=
true;

step1Data
=
data;

}
}

var
step2State
=
false;
function
callback2(data)
{

step2State
=
true;

step2Data
=
data;

}
}

step3(value3,
callback3);

step4(value4,
callback4);

var
step3State
=
false;
function
callback3(data)
{

step3State
=
true;

step3Data
=
data;

}
}

var
step4State
=
false;
function
callback4(data)
{

step4State
=
true;

step4Data
=
data;

}
}


Instead of you writing all this boilerplate just to sequence 4 async operations across your application, and be able
to come back and interact with them later...

step1.
then(step2).
then(step3).
then(step4)


... all you need is this. This is how the promise pattern sequences things. It knows when it’s allowed to move
forward between steps, and keeps everything in order.

Or, decompose
them...


as1 = step1();
as2 = as1.then(step2);


And we can decompose that chain of operations incredibly easily, just by storing a reference to the promises for
each stage of that sequence. The promises are the variables on the left. These actions will still ﬁre in the same
order as the previous example, but now we can start additional actions, later, whenever and wherever we want,
from any point in the middle of the sequence, using the data that comes out of those operations.

$HTTP


It’s like having DVR, for your async operations. And we can even pass these references into other contexts of the
application, without those contexts needing to know anything at all about the process that generated the promise.

And if you need
parallelism...


What if you want to have three of them run in parallel instead of in sequence, and have the fourth one kick in only
when all three are done?

as4 =
$Q.all([as1, as2, as3])
.then(step4)


Either, you write all the imperative boilerplate and state variables and other junk we saw before, THEN set a timer
to check every few ms to see if they’re all done yet, or use events if you’re lucky... all that OR you do this one line
that replaces all of that. That’s composition with promises. That’s the pattern they allow you to work with. So, if
that’s the overall pattern, how should we understand the component promise objects themselves?

So, in a nutshell, a
promise object
itself is...


So... I promised a certain metaphor in my talk title, even though we don’t have time for all the details here. But at
root, understand that a promise is basically just a mailbox.


It’s a special, standardized repository where you can stash the data that outputs from an operation, it has a
property representing the completion and success state of the operation, and it has utilities for leveraging that
knowledge into further operations. And all your functions can have a key to this mailbox, so they know what’s
going on. You can even pick this mailbox up and carry it around with you by reference into different contexts of
your app, providing your components with all the beneﬁts of async, without needing to understand
implementation.

If the Promise is the
mailbox, then the Deferred:
Is the Postman.


Then, there’s this thing called the deferred. Lots of folks get Promises but have trouble with the Deferred object.
But it’s really straightforward once you think of the promise as a mailbox. The deferred is simply the postman.

No, not that
one, thank
God...


No, not THAT endless tribute to Kevin Costner’s vanity, thank god.

If the Promise is the
mailbox, then the Deferred:
Is the Postman.
The Postman is the only one who’s
allowed to:
Assign you a new mailbox.
(ie. create a promise)
Put new packages into the
mailbox. (resolve the promise)
Raise the little flag on the
side. (set state of the promise)

Just like with actual postal workers the postman is the only one who’s allowed to: Assign you a new P.O. Box, put
new packages into the mailbox, and, inverting the real life example, let’s pretend the little ﬂag on the side of the
mailbox is used to show the box has incoming mail, not outgoing mail.
With the deferred, you’re the postman, and you can create and administer the mailbox. Without the deferred,
you’re a customer, a promise-consumer.

But it’s the pattern
that matters most...


That’s the main idea. But the pattern of use is more signiﬁcant than the individual promise objects themselves.
Alone, they’re just syntactic sugar.

DECLARATIVE, NOT IMPERATIVE.
A UNIVERSAL API for uncertainty about
time & place.
An abstraction for any operation that
has happened or will happen.
A proxy for a remote object, which
allows you to abstract away all the
complexity of going and getting it.
A zero-boilerplate API for interacting
with the state, data, timing &
sequence of complex operations.

Together, they can change your whole approach to composition, and they can sure as hell reduce the amount of
code you write.

NOT JUST FOR ASYNC


Now, remember, PROMISES ARE NOT JUST FOR ASYNC.

userRegistered.then()
tutorialComplete.then()
purchaseSuccessful.then()
profileLocated.then()
etc...


Time and place uncertainty are certainly the conventional context for promises. But there are other kinds,
especially user-related uncertainty. A given AJAX request is actually semi-predictable, within a range. Users,
though, are totally unpredictable. You have no idea when - or if - your user will get around to doing certain
things, or in what order. Take advantage of promises as a way to encapsulate and abstract this kind of sequencing
uncertainty as well, even though it’s not execution engine asynchronousness in the way we mean that term. But
using promises, you can build custom async interfaces around user uncertainty.


Which brings us to Angular. Angular is an example of what happens when you start thinking in promises,
structurally. When you bake them right into the fabric of the application and use them as a way to model process
ﬂows and make sure that the right things happen in the right place at the right time, so the different parts of your
application can hand-off those ﬂows seamlessly, and customize them.
If you think that Misko and Vojta and Igor and Brian and Brad and all the other cats on the angular team are pretty
smart, if you're HERE, in other words, then follow their example and get way into promises.

1. Consume promises returned by
essential built-in Services.
$http
$timeout
$interval


Here’s sort-of an 8-step program to using promises in Angular.
Step 1: When you get started with promises, you’ll just consume them, from built-in services that return promises.
$http.... and very notably $timeout and $interval.
Angular has gone to the trouble to make all of the most fundamental async functions into promise generators, so
that Promises can be the seamless common API for all async.

var promise=
$http.get(‘URL’)
promise.then(doSomething);
promise.then(doThing2);
promise.then(doThing∞);


It’s as simple as this: if $http returns a promise, all you have to do is store a reference to that promise. Forever
after, for as long as you hold that reference, you can run other operations against it.

2. $resource calls
now return promises (in 1.2),
& $resource objects *have* one.

(Aren’t one. Have one.)


Step 2, when you’re ready to get a little tricky, try $resource. (The implementation of $resource has shifted quite a
bit in the past, but here’s the 1.2 skinny:)
$resource works a little differently than $http, but is nonetheless promise-style processing, via a useful, but
perhaps confusing, pattern: $http.get() returns a simple *promise*. But calling the initial .get() method on a
$resource type that you’ve deﬁned, returns a... *resource object*, which itself *has* a promise. It Isn't one. But it
has one, as a property.

var bob =
resourceType.get({params})
// returns...

Resource {$promise: Object,
$resolved: true, $get:
function, $save: function,
$query: function…}
// after that...

bob.$promise.then(doStuff)

* To chain from that $resource with .then(), just use resourceObject.$promise
• Note that the reference is circular. So, if you unwrap a $resource's $promise object, what you get back is the
original $resource. Which, of course, still has a $promise. Which you can unwrap. So, the $resource has a
$promise which has a $resource which has a $promise...

credit:
substack/stream-handbook

Truly, it’s turtles all the way down.
Complicating things further, the other instance methods on a $resources, like $save(), they don’t modify that
original promise, instead they return a new bare $promise for the state of the operation, rather than the $resource
itself.

3. $route:resolve

(Integrating the promise architecture
so cleanly that controllers can be
fully ignorant of it.)


Step 3 is such a big, worthwhile feature that one of the release candidates for the version of Angular it debuted in
was named 'promise-resolution'.

$routeProvider
.when('/dashboard', {
templateUrl: 'URL',
controller: 'Ctrl',
resolve: {myData:
['myService', function(myService)
{return
myService.get('URL', {params}).$promise
}]
}


Using the :resolve property in the route, you get several huge beneﬁts that you just don’t want to be operating
without. 1. the route won’t change until your data has been obtained, and you have everything you need to render
the view. No ﬂicker, nothing looks broken. 2. Your controller gets to be totally, completely ignorant of
implementation. It doesn’t need to know what a promise is. It doesn’t need to know how to unwrap it, or check the
success of the operation. $routeProvider does all of that for you. All the controller gets is a data object, injected at
creation time, so it gets to be totally implementation independent.

angular.module('myApp')
.controller('Ctrl',
function(myData) {
// do stuff with myData
$scope.myData = myData;
})


And so then, in the controller, all you have to do is inject the name of the property, and you can do whatever you
want with it, like bind it to the $scope.

4. Note:
Automatic unwrapping in views:
GONE in 1.2

(Too much magic.)


Step 4 is just: be aware of a big recent change in Angular 1.2. For a little while there, we could place a promise
object on the $scope, and angular would automagically extract the value from it and inject *that* into the view.
Yadda yadda yadda, reading the repo, it seems it was just too much magic for people. It made consumers of
promises less aware of how they worked and how to use them. It was also slow. So, that feature, which you might
see in old documentation on the web, is gone now.

Alternatives:
Either inject your promises
via :resolve, so they’re autounwrapped, or...
promise.then(function(value)
{$scope.value = value})


Your Alternatives are clear and easy: Either inject promises with the :resolve property if you like magical
unwrapping, or just unwrap ‘em yourself.

5. Create your own promises
with $Q.

(Just like Q.js, only smaller.)


Step 5, start creating your own promises with $Q. Check out my detailed slides for more on how to do that.

6. Third-party libraries
like angular-ui-bootstrap
are built on promises, too.

(Great example of workflow:
ng-modal.)


Step 6: Start noticing how many Third-Party Implementations, like UI-Bootstrap Modal also take advantage of
promise ﬂows.

$scope.modalOpen = function () {
var modalConfigs = {
templateUrl: ...,
controller: ...,
scope: $scope,
resolve: {
specialData: function ()

{return $http.get(‘/somedata’);}
}
}
var modalInstance =
$modal.open(modalConfigs);
modalInstance.result.then(handlerFunc);
};

// Inside the modalInstance: result.resolve();

When you deﬁne a modal instance, which carries a promise, you immediately deﬁne a handler, with
modalInstance.result.then(). Before we’ve even had time to do anything with that modal, we’ve already created a
handler for whatever we’re going to eventually return from the modal dialog as the result object. We don’t know
when or if there will be a return. But we’re ready for it, we can reason about it. And we can easily hand off to some
other consumer as well.
ALSO: UI-Modal uses its own :resolve property, just like the Angular router does, to ensure that the view won’t be
rendered until the data is ready.

7. Wrap a promise in
an Angular Service, and
you have a *Lazy Promise*.

(With lazy promises, time is now
fully irrelevant. Point and shoot.)


Step 7: promises that you can reference without needing to care if they even exist yet, let alone if they’ve resolved.
Normally, you need to know that a promise has been instantiated before you start interacting with it. But because
Angular services are instantiated lazily, as needed, and persist throughout application lifecycle, a Promise
wrapped in a service can be referenced at any time, from any location, provided you inject the service. The caller
of the promise need not know or care anything about the implementation.

function getDivision(divisionName) {
if (!divisionObjects[divisionName])
{
divisionObjects[divisionName] =
$http.get(baseUrl + divisionName)
.error(function(data, status) {
console.error('getDivision
failed, error:' + status)
});
} else {
return
divisionObjects[divisionName];
}
}

• Outside of Angular (or if you want multiple promises in one service) you can do the same thing, using a simple
getter function that will return an existing promise if available, or create a new one if not.

8. Interceptors
(and the rest of
the $http lifecycle)

(Great for loaders, other inline
transformations.)


Step 8: is Master-level! HTTP interceptors are these awesome things that allow you to mess around with every
single AJAX operation that goes in or out of your application, all from a single location. And they’re promised
based... in BOTH DIRECTIONS, in and out, request and response. Promises, again, aren't just something for async
output. They’re part of the modeling of the $http cycle from the very beginning, and you can thus chain even
before an async operation kicks off, perhaps executing another async operation before the main one is even
allowed to start.

$httpProvider.interceptors.push(function($q, $rootScope) {
return {
'request': function(config) {
$rootScope.$broadcast('asyncLoadStart');
return config || $q.when(config);
},
'requestError': function(rejection) {
$rootScope.$broadcast('asyncLoadEnd');
return $q.reject(rejection);
},
'response': function(response) {
return response || $q.when(response);
},
'responseError': function(rejection) {
return $q.reject(rejection);
}
};
})

This example is stripped bare and over-simpliﬁed, just so it ﬁts on-screen. It shows a way to trigger an automatic,
universal loader screen for your app. With promises, we’re able to interact with the stream of low-level
instructions in Angular’s infrastructure, and we can even conveniently pause the stream, while we wait for
something to happen, simply by returning a promise that hasn’t resolved yet. This allows us to: do validation, or
checking that a user session is still open... whatever... before we proceed. By composing and inserting a single
promise object, in the right state, you get that much control, right at the heart of Angular’s operations.

Bonus Detail:
terminate an $http request...
if a promise resolves

(Using the promise API for
mid-stream interventions, not
just outputs...)


Bonus detail: check out the ‘timeout’ property of an $http request’s conﬁg object. It shows us yet another model
for the use of promises, where instead of something starting when a promise resolves, we can terminate
something when a promise resolves. Maybe it’s a parallel $http request, and we want to stop whenever one or the
other returns. Or maybe it’s simply a promise indicating an option that was set somewhere. Either way, Angular
knows what to do with it, because a promise is our universal API for all kinds of uncertainty that we want to
conveniently make decisions about.

Best Practices
Use SOA: goes with promises like
peanut butter with chocolate.
Think of promises as the beginning of
a lifecycle or flow or stream, not
just a one-stop ride to a callback.
Decompose handler functions, as
promises make it easy to chain them.


And lest you *still*
thought Promises
weren’t really
mainstream...



• Previously, promises had been a library feature. Now, native promises in the browser are not only part of the
ECMAscript 6 spec, they’re in release, in Chrome 32, as of this very week. Syntax is a little different than the
Promises/A+ spec, but I think in a good way.
• This means that, even though other browsers are going to lag, we can unify around an API for Promises, and
unify around Promises as our key API for uncertainty, and you can invest in learning them knowing that they're not
going anywhere.
• And Not only are they not going anywhere, you're going to HAVE to use them, even outside Angular. New async
DOM APIs will return promises! They'll be unavoidable. Angular ... AND YOU... just got there ahead of the curve.

Thank You!
about.me/XML


I'm Postal for Promises in Angular

More Related Content

Similar to I'm Postal for Promises in Angular

Recently uploaded

I'm Postal for Promises in Angular