Promise in AngularJS

What's promise

Angular’s event system provides a lot of power to our Angular apps. One of the most powerful features that it enables is automatic resolution of promises.

Promises are a method of resolving a value or not in an asynchronous manner. Promises are objects that represent the return value or a thrown exception that a function may eventually provide.

Promises are incredibly useful in dealing with remote objects and we can think of them as a proxy for them.

 

Promises are first-class objects and carry with them a few guarantees:

• Only one resolve or reject will ever be called

– resolve will be called with a single fulfillment value

– reject will only be called with a single rejection reason

• If the promise has been resolved or rejected, any handlers depending upon them will still be called
• Handlers will always be called asynchronously

Additionally, we can also chain promises and allow the code to process as it will normally would run. Exceptions from one promise bubble up through the entire promise chain.

They are always asynchronous, so we can use them in the flow of our code without worry that they will block the rest of the app.

Promise in AngularJS

Angular’s event-loop gives angular the unique ability to resolve promises in it’s $rootScope. $evalAsync stage (see under the hood for more detail on the run loop). The promises will sit inert until the $digest run loop finishes.

bind promise and view directly

This allows for Angular to turn the results of a promise into the view without any extra work. It enables us to assign the result of an XHR call directly to a property on a $scope object and think nothing of it. For instance, we might have a list of friends in a view, like so:

< ul>
  < li ng-repeat= "friend in friends">
     {{ friend. name }}
  </ li>
</ ul>

 

If we have a service that returns a promise , we can simply place the promise in the view and expect that Angular will resolve it for us:

angular.module( 'myApp', [])
 .controller( 'DashboardController', [ '$scope', 'UserService', function($scope, UserService) {
    // UserService's getFriends() method
    // returns a promise
    $scope.friends = User.getFriends( 123);
 }]);

 

When the asynchronous call to getFriends returns, the $scope.friends value will automatically update the view.

 

How to create a promise

In order to create a promise in Angular, we’ll use the built-in $q service. The $q service provides a few methods in it’s deferred API.

1. inject $q service

First, we’ll need to inject the $q service into our object where we want to use it.

angular.module( 'myApp', [])
   .factory( 'UserService', [ '$q', function($q) {
    // Now we have access to the $q library
 }]);

 

2. $q.defer()

To created a deferred object, we’ll call the method defer():

var deferred = $q.defer();

 

The deferred object exposes three methods and the single promise property that can be used in dealing with the promise.

• resolve(value)

The resolve function will resolve the deferred promise with the value.

 

deferred .resolve({name : "Ari", username : "@auser"});

 

• reject(reason)

This will reject the deferred promise with a reason. This is equivalent to resolving a promise with a rejection

deferred .reject( "Can't update user");
// Equivalent to
deferred.resolve( $q.reject( "Can't update user"));

 

• notify(value)

This will respond with the status of a promises execution.

TODO: Add notify example

• promise property

We can get access to the promise as a property on the deferred object:

deferred.promise

 

A full example of creating a function that responds with a promise might look similar to the following method on the UserService as mentioned above.

angular.module( 'UserService', [ '$q', function($q) {
  var getFriends = function(id) {
    var deferred = $q.defer();
 
   // Get friends from a remote server
   $http.get( '/user/' + id + '/friends')
   .success( function(data) {
      deferred.resolve(data.friends);
   })
   .error( function(reason) {
      deferred.reject(reason);
   });
 
   return deferred.promise;
 }
 }]);

 

3. interact with promise

Now we can use the promise API to interact with the getFriends() promise.

In the case of the above service, we can interact with the promise in two different ways.

• then(successFn, errFn, notifyFn)

Regardless of the success or failure of the promise, then will call either the successFn or the errFn asynchronously as soon as the result is available. The callbacks are always called with a single argument: the result or the rejection reason.

The notifyFn callback may be called zero or more times to provide a progress status indication before the promise is resolved or rejected.

The then() method always returns a new promise which is either resolved or rejected through the return value of the successFn or the errFn. It also notifies through the notifyFn.

• catch(errFn)

This is simply a helper function that allows for us to replace the err callback with .catch(function(reason){}):

 

$http.get( '/user/' + id + '/friends')
 . catch( function(reason) {
    deferred.reject(reason);
 });

 

• finally(callback)

This allows you to observe the fulfillment or rejection of a promise, but without modifying the result value. This is useful for when we need to release a resource or run some clean-up regardless of the success/error of the promise.

We cannot call this directly due to finally being a reserved word in IE javascript. To use finally, we have to call it like:

 

promise[ 'finally']( function() {});

 

 

Angular’s $q deferred objects are chainable in that even then returns a promise. As soon as the promise is resolved, the promise returned by then is resolved or rejected.

These promise chains are how Angular can support $http’s interceptors.

The $q service is similar to the original Kris Kowal’s Q library:

1. $q is integrated with the angular $rootScope model, so resolutions and rejections happen quickly inside the angular
2. $q promises are integrated with angular’s templating engine which means that any promises that are found in the views will be resolved/rejected in the view
3. $q is tiny and doesn’t contain the full functionality of the Q library

$q library

The $q library comes with several different useful methods.

all(promises)

If we have multiple promises that we want to combine into a single promise, then we can use the $q.all(promises) method to combine them all into a single promise. This method takes a single argument:

 

promises (array or object of promises)

 

Promises as an array or hash of promises

The all() method returns a single promise that will be resolved with an array or hash of values. Each value will correspond to the promises at the same index/key in the promises hash. If any of the promises are resolved with a rejection, then the resulting promise will be rejected as well.

defer()

The defer() method creates a deferred object. It takes no parameters. It returns a new instance of a single deferred object.

reject(reason)

This will create a promise that is resolved as rejected with a specific reason. This is specifically designed to give us access to forwarding rejection in a chain of promises.

This is akin to throw in javascript. In the same sense that we can catch an exception in javascript and we can forward the rejection, we’ll need to rethrow the error. We can do this with $q.reject(reason).

This method takes a single parameter:

reason (constant, string, exception, object)

The reasons for the rejection.

This reject() method returns a promise that has already been resolved as rejected with the reason.

when(value)

The when() function wraps an object that might be a value then-able promise into a $q promise. This allows for us to deal with an object that may or may not be a promise.

The when() function takes a single parameter:

value

This is the value or a promise

The when() function returns a promise that can be then used like any other promise.