A promise implementation in one of its simplest forms is as follows:

// create deferred object through $q api
var deferred = $q.defer();

// deferred objects are created with a promise attached
var promise = deferred.promise;

// define handlers to execute once promise state becomes definite
promise.then(function success(data) {
  // deferred.resolve() handler
  // in this implementation, data === 'resolved'
}, function error(data) {
  // deferred.reject() handler
  // in this implementation, data === 'rejected'
});

// this function can be called anywhere to resolve the promise
function asyncResolve() {
  deferred.resolve('resolved');
};

// this function can be called anywhere to reject the promise
function asyncReject() {
  deferred.reject('rejected');
};

To a person seeing promises for the first time, what makes them difficult to comprehend is quite plain: much of what is going on here is not intuitive.

The promise ecosystem can be more readily decoded by gaining a better understanding of the nomenclature behind it, and what problems it intends to solve.

Promises are by no means a new concept in AngularJS, or even in JavaScript; part of the inspiration for $q was taken from Kris Kowal's Q library, and for a long time, jQuery has had key promise concepts incorporated into many of its features.

Promises in JavaScript confer to the developer the ability to write asynchronous code in parallel with synchronous code more easily. In JavaScript, this was formerly solved with nested callbacks, colloquially referred to as callback hell. A single callback-oriented function might be written as follows:

// a prototypical asynchronous callback function
function asyncFunction(data, successCallback, errorCallback) {
  // this will perform some operation that may succeed,
  // may fail, or may not return at all, any of which
  // occurs in an unknown amount of time

  // this pseudo-response contains a success boolean,
  // and the returned data if successful
  var response = asyncOperation(data);

  if (response.success === true) {
    successCallback(response.data);
  } else {
    errorCallback();
  }
};

If your application does not demand any semblance of in-order or collective completion, then the following will suffice:

function successCallback(data) {
  // asyncFunction succeeded, handle data appropriately
};
function errorCallback() {
  // asyncFunction failed, handle appropriately
};

asyncFunction(data1, successCallback, errorCallback);
asyncFunction(data2, successCallback, errorCallback);
asyncFunction(data3, successCallback, errorCallback);

This is almost never the case though, since your application will often demand either that the data should be acquired in a sequence or that an operation that requires multiple asynchronously-acquired pieces of data should only be executed once all the pieces have been successfully acquired. In this case, without access to promises, the callback hell emerges, as follows:

asyncFunction(data1, function(foo) {
  asyncFunction(data2, function(bar) {
    asyncFunction(data3, function(baz){
      // foo, bar, baz can now all be used together
      combinatoricFunction(foo, bar, baz);
    }, errorCallback);
  }, errorCallback);
}, errorCallback);

This so-called callback hell is really just attempting to serialize three asynchronous calls, but the parametric topology of these asynchronous functions forces the developer to subject their application to this ugliness. Promises to the rescue!

var deferred = $q.defer()
  , promise = deferred.promise;

var deferred = $q.defer()
  , promise = deferred.promise; 

// the following are pseudo-methods, each of which can be called 
// independently and asynchronously, or not at all
function canHappenFirst() { deferred.resolve(); }
function mayHappenFirst() { deferred.resolve(); }
function mightHappenFirst() { deferred.reject(); }

var deferred = $q.defer()
  , promise = deferred.promise; 

// define handlers on the promise to gain visibility 
// into their execution
promise.then(function resolved() {
  $log.log('success');
}, function rejected() {
  $log.log('rejected');
});

// verify initial state
$log.log(promise.$$state.status); // 0

// resolve the promise
deferred.resolve();
// >> "resolved"

$log.log(promise.$$state.status); // 1
// output and state check verify state transition

// attempt to reject the already resolved promise
deferred.reject();

$log.log(promise.$$state.status); // 1
// output and state check verify no state transition

var deferred = $q.defer()
  , promise = deferred.promise;

promise.then(successHandler, failureHandler);

// state can be defined with any of the following:
// deferred.resolve();
// deferred.reject();
// deferred.resolve(myData);
// deferred.reject(myData);

var deferred = $q.defer()
  , promise = deferred.promise;

// $log.info is the resolve handler,
// $log.error is the reject handler 
promise.then($log.info, $log.error);

deferred.resolve(123);  
// (info) 123

// reset to demonstrate reject()
deferred = $q.defer();
promise = deferred.promise;

promise.then($log.log, $log.error);

deferred.reject(123);  
// (error) 123

var deferred = $q.defer()
  , promise = deferred.promise;

// immediately resolve the promise
deferred.resolve(123);

// subsequently define a handler, will be immediately
// invoked since promise is already resolved 
promise.then($log.log); 
// 123

var deferred = $q.defer()
  , promise = deferred.promise
  , cb = function() { $log.log('called'); };

promise.then(cb);
promise.then(cb);

deferred.resolve();
// called
// called

Assume that all the examples in this recipe have been set up in the following manner:

var deferred = $q.defer()
    , promise = deferred.promise;

Also, assume that $q and other built-in AngularJS services have already been injected into the current lexical scope.

The promise handler definition method then() returns another promise, which can further have handlers defined upon it in a chain handler, as shown here:

var successHandler = function() { $log.log('called'); };

promise
  .then(successHandler)
  .then(successHandler)
  .then(successHandler);

deferred.resolve();
// called
// called
// called

var successHandler = function(val) { 
  $log.log(val); 
  return val+1;
};

promise
  .then(successHandler)
  .then(successHandler)
  .then(successHandler);

deferred.resolve(0);
// 0
// 1
// 2

promise
.then(function () {
  // initial promise resolved handler instructs handlers
  // child promise(s) to be rejected
  return $q.reject(123);
})
.then(
  // child promise resolved handler
  function(data) {
    $log.log("resolved", data);
  },
  // child promise rejected handler
  function(data) {
    $log.log("rejected", data);
  }
);

deferred.resolve();
// "rejected", 123

A promise reaching a final state will trigger child promises to follow it in turn. This simple but powerful concept allows you to build broad and fault-tolerant promise structures that elegantly mesh collections of dependent asynchronous actions.

The topology of AngularJS promises lends itself to some interesting utilization patterns, as follows.

var incr = function(val) {
  $log.log(val);
  return val+1;
}

// define the top level promise handler
promise.then(incr);
// append another handler for the first promise, and collect
// the returned promise in secondPromise
var secondPromise = promise.then(incr);
// append another handler for the second promise, and collect
// the returned promise in thirdPromise
var thirdPromise = secondPromise.then(incr);

// at this point, deferred.resolve() will:
// resolve promise; promise's handlers executes
// resolve secondPromise; secondPromises's handler executes
// resolve thirdPromise; no handlers defined yet

// additional promise handler definition order is
// unimportant; they will be resolved as the promises
// sequentially have their states defined
secondPromise.then(incr);
promise.then(incr);
thirdPromise.then(incr);

// the setup currently defined is as follows:
// promise -> secondPromise -> thirdPromise
// incr()     incr()           incr()
// incr()     incr()
// incr()

deferred.resolve(0);
// 0
// 0
// 0
// 1
// 1
// 2

promise
.then(function () {
  return $q.reject();
})
.catch(function(data) {
  $log.log("rejected");
});

deferred.resolve();
// "rejected"

var deferred1 = $q.defer();
  , promise1 = deferred1.promise
  , deferred2 = $q.defer()
  , promise2 = deferred2.promise
  , cb = $log.log("called");

promise1.finally(cb);
promise2.finally(cb);

deferred1.resolve();
// "called"
deferred2.reject();
// "called"

The promise.then() method accepts a third argument, a notification handler, which can be accessed through the deferred an unlimited number of times until the promise state has been resolved. This is shown here:

promise
.then(
  // resolved handler
  function() {
    $log.log('success');
  },
  // empty rejected handler
  null,
  // notification handler
  $log.log
);

function resolveWithProgressNotifications() {
  for (var i=0; i<=100; i+=20) {
    // pass the data to the notification handler
    deferred.notify(i);
    if (i>=100) { deferred.resolve() };
  };
}

resolveWithProgressNotifications();
// 0
// 20
// 40
// 60
// 80
// 100
// "success"

The notification handler allows the notifications to be enqueued upon the promise, and they are sequentially executed at the conclusion of the $digest cycle. Another example is as follows:

promise
.then(
  function() {
    $log.log('success');
  },
  null,
  $log.log
);

function asyncNotification() {
  deferred.notify('Hello, ');
  $log.log('world!');
  deferred.resolve();
};

// this function is invoked by some non-AngularJS entity
asyncNotification();
// world!
// Hello, 
// success

The order of the console log statements might surprise you. Since the notifications often arrive from an event that is not bound to the AngularJS $digest cycle, a call to $scope.$apply() will push through the execution of the notification handler(s) immediately. This is shown here:

promise
.then(
  function() {
    $log.log('success');
  },
  null,
  $log.log
);

function newAsyncNotification() {
  deferred.notify('Hello, ');
  $scope.$apply();
  $log.log('world!');
  deferred.resolve();
};

// this function is invoked by some non-AngularJS entity
newAsyncNotification();
// Hello,
// world!
// success

The notification handler cannot transit the promise into a final state with its return value, although it can use the deferred object to cause a state transition, as demonstrated earlier in this recipe.

Notifications will not be executed after the promise has transitioned to a final state, as shown here:

// resolve or reject handlers not needed in this example
promise.then(null, null, $log.log);

deferred.notify('Hello, ');
deferred.resolve();
deferred.notify('world!');

// Hello, 

The $q.all() method accepts an enumerable collection of promises, either an array of promise objects or an object with a number of promise properties, and will attempt to resolve all of them as a single aggregate promise. The parameter of the aggregate resolved handler will be an array or object that matches the resolved values of the contained promises. This is shown here:

var deferred1 = $q.defer()
  , promise1 = deferred1.promise
  , deferred2 = $q.defer()
  , promise2 = deferred2.promise;

$q.all([promise1, promise2]).then($log.log);

deferred1.resolve(456);
deferred2.resolve(123);
// [456, 123]

If any of the promises in the collection are rejected, the aggregate promise will be rejected. The parameter of the aggregate rejected handler will be the returned value of the rejected promise. This is shown here:

var deferred1 = $q.defer()
  , promise1 = deferred1.promise
  , deferred2 = $q.defer()
  , promise2 = deferred2.promise;

$q.all([promise1, promise2]).then($log.log, $log.error);

// resolve a collection promise, no handler execution
deferred1.resolve(456);

// reject a collection promise, rejection handler executes
deferred2.reject(123);
// (error) 123

As demonstrated, the aggregate promise will reach a final state only when all of the enclosed promises are resolved, or when a single enclosed promise is rejected. Using this type of promise is useful when the promises in a collection do not need to reason about one another, but their collective completion is the only metric of success for the group.

In the case of a contained rejection, the aggregate promise will not wait for the remaining promises to get completed, but those promises will not be prevented from reaching their final state. Only the first promise to be rejected will be able to pass the rejection data to the aggregate promise rejection handler.

The $q.all() method is in many ways extremely similar to an operating-system-level process synchronization barrier. A process barrier is a common point in a thread instruction execution, which a collection of processes will reach independently and at different times, and none can proceed until all have reached this point. In the same way, $q.all() will not proceed unless either all of the contained promises have been resolved (reached the barrier) or a single contained rejection has prevented that state from ever being achieved, in which case the failover handler logic will take over.

Since $q.all() allows the recombination of promises, this also allows your application's promise chains to become a directed acyclic graph (DAG). The following diagram is an example of a promise progression graph that has diverged and later converged:

This level of complexity is uncommon, but it is available for use should your application require it.

The $q.when() method accepts promise and non-promise objects, as follows:

var deferred = $q.defer()
  , promise = deferred.promise;

$q.when(123);
$q.when(promise);
// both create new promise objects

If $q.when() is passed a non-promise object, it is effectively the same as creating an immediately resolved promise object, as shown here:

var newPromise = $q.when(123);

// promise will wait for a $digest cycle to update $$state.status,
// this forces it to update for inspection
$scope.$apply();

// inspecting the status reveals it has already resolved
$log.log(newPromise.$$state.status);
// 1

// since it is resolved, the handler will execute immediately
newPromise.then($log.log);
// 123

The $q.when() method wraps whatever is passed to it with a new promise. If it is passed a promise, the new promise will retain the state of that promise. Otherwise, if it is passed a non-promise value, the new promise created will get resolved and pass that value to the resolved handler.

Since $q.when() will return an identical promise when passed a promise, this method is effectively idempotent. However, the promise argument and the returned promise are different promise objects, as shown here:

$log.log($q.when(promise)===promise);
// false

The $http service methods return an AngularJS promise with some extra methods, success() and error(). These extra methods will return the same promise returned by the $http service, as opposed to .then(), which returns a new promise. This allows you to chain the methods as $http().success().then() and have the .success() and .then() promises attempt to resolve simultaneously.

The following two implementations are more or less identical, as everything is being chained upon the $http promise:

// Implementation #1
// $http.get() returns a promise
$http.get('/myUrl')
// .success() is an alias for the resolved handler
.success(function(data, status, headers, config, statusText) {
  // resolved handler
})
// .error() is an alias for the rejected handler
.error(function(data, status, headers, config, statusText) {
  // rejected handler
});

// Implementation #2
$http.get('/myUrl')
.then(
  // resolved handler
  function(response) {
    // response object has the properties
    // data, status, headers, config, statusText
  },
  // rejected handler
  function(response) {
    // response object has the properties
       // data, status, headers, config, statusText
  }
); 

However, the following two implementations are not identical:

// Implementation #3
// $http.get() returns a promise
$http.get('/myUrl')
// .success() is an alias for the resolved handler
.success(function(data, status, headers, config, statusText) {
  // resolved handler
})
// .error() is an alias for the rejected handler
.error(function(data, status, headers, config, statusText) {
  // rejected handler
})
.then( ... );

// Implementation #4
$http.get('/myUrl')
.then(
  // resolved handler
  function(response) {
    // response object has the properties
    // data, status, headers, config, statusText
  },
  // rejected handler
  function(response) {
    // response object has the properties
       // data, status, headers, config, statusText
  }
)
.then( ... );

The differences are explained in the following example:

// these are split into variables to be able to inspect
// the returned promises
var a = $http.get('/')
  , b = a.success(function() {})
  , c = b.error(function() {})
  , d = c.then(function() {});

$log.log(a===b, a===c, a===d, b===c, b===d, c===d);
//       true   true   false  true   false  false

var e = $http.get('/')
  , f = e.then(function() {})
  , g = e.then(function() {});

$log.log(e===f, e===g, f===g);
//       false  false  false

The success/error dichotomy for an HTTP request is decided by the response status code, as follows:

Although it wraps $http, $resource actually does not use promises in its default implementation. The $promise property can be used to access the promise object of the HTTP request, as follows:

// creates the resource object, which exposes get(), post(), etc.
var Widget = $resource('/widgets/:widgetId', {widgetId: '@id'});

// resource object must be coaxed into returning its promise
// this can be done with the $promise property
Widget.get({id: 8})
.$promise
.then(function(widget) {
  // widget is the returned object with id=8
});

A $resource object accepts success and error function callbacks as its second and third arguments, which can be utilized if the developer desires a callback-driven request pattern instead of promises. Since it does use $http, promises are still very much integrated and available to the developer.

The Restangular REST API mapping will always return a promise. This is shown here:

(app.js)

angular.module('myApp', ['restangular'])
.controller('Ctrl', function($scope, Restangular) {
  Restangular
  .one('widget', 4)
  // get() will return a promise for the GET request
  .get()
  .then(
    function(data) {
      // consume response data in success handler
      $scope.status = 'One widget success!';
    },
    function(response) {
      // consume response message in error handler
      $scope.status = 'One widget failure!';
    }
  );
  
  // generally, the API mapping is stored in a variable,
  // and the promise-returning method will be invoked as needed
  var widgets = Restangular.all('widgets');
  
  // create the request promise
  widgets.getList()
  .then(function(widgets) {
    // success handler
    $scope.status = 'Many widgets success!';
  }, function() {
    // error handler
    $scope.status = 'Many widgets failure!';
  });
});

Since Restangular objects don't create promises until the request method is invoked, it is possible to chain Restangular route methods before creating the request promise, in order to match the nested URL structure. This can be done as follows:

// GET request to /widgets/6/features/11
Restangular
.one('widgets', 6)
.one('features', 11)
.get()
.then(function(feature) {
  // success handler
});

Every Restangular object method can be chained to develop nested URL objects, and every request to a remote API through Restangular returns a promise. In conjunction with its flexible and extensible resource CRUD methods, it creates a powerful toolkit to communicate with REST APIs.

Resolves are declared in the route definition, as follows:

(app.js)

angular.module('myApp', ['ngRoute'])
.config(function($routeProvider){
  $routeProvider
  .when('/myUrl', {
    template: '<h1>Resolved!</h1>',
    // resolved values are injected by property name
    controller: function($log, myPromise, myData) {
      $log.log(myPromise, myData);
    },
    resolve: {
      // $q injected into resolve function
      myPromise: function($q) {
        var deferred = $q.defer()
          , promise = deferred.promise;
        deferred.resolve(123);
        return promise;
      },
      myData: function() {
        return 456;
      }
    }
  });
})
.controller('Ctrl', function($scope, $location) {
  $scope.navigate = function() {
    $location.url('myUrl')
  };
});

(index.html)

<div ng-app="myApp">
  <div ng-controller="Ctrl">
    <button ng-click="navigate()">Navigate!</button>
    <div ng-view></div>
  <div>
</div>

With this configuration, navigating to /myUrl will log 123, 456 and render the template.

The premise behind route resolves is that the promises gather data or perform tasks that need to be done before the route changes and the controller is created. A resolved promise signals the router that the page is safe to be rendered.

The object provided to the route resolve evaluates the functions provided to it and consequently makes injectables available in the route controller.

There are several important details to keep in mind involving route resolves, which are as follows:

By definition, promises are not guaranteed to undergo a final state transition, and the AngularJS router diligently waits for promises to get resolved unless they get rejected. Therefore, if a promise never gets resolved, the route change will never occur and your application will appear to hang.

The ui-router framework supports resolves for states in the same way that ngRoute does for routes. Suppose your application displayed individual widget pages that list the features each widget has, as well as individual pages for each widget's features.

(app.js)

angular.module('myApp', ['ui.router'])
.config(function($stateProvider) {
  $stateProvider
  .state('widget', {
    url: '/widgets/:widgetId',
    template: 'Widget ID: {{ widgetId }} <div ui-view></div>',
    controller: function($scope, $stateParams, widgetId){
      // the widgetId is only available in this state due to
      // the :widgetId variable definition in the state url
      $scope.widgetId = $stateParams.widgetId;
    },
    resolve:{
      // the stateParam widget property is wrapped in a property
      // to enable it to be injected in child states
      widgetId: function($stateParams){
        return $stateParams.widgetId;
      }
    }
  })
  .state('widget.feature', {
    url: '/features/:featureId',
    template: 'Feature ID: {{ featureId }}',
    // widgetId can now be injected from the parent state
    controller: function($scope, $stateParams, widgetId){
      // both widgetId and featureId are made available
      // in this state controller
      $scope.featureId = $stateParams.featureId;
      $scope.widgetId = widgetId;
    }
  });
});

(index.html)

<div ng-app="myApp">
  <a ui-sref="widget({widgetId:6})">
    See Widget 6
  </a>
  <a ui-sref="widget.feature({widgetId: 6, featureId:11})">
    See Feature 11 of Widget 6
  </a>
  <div ui-view></div>
</div>

(app.js)

angular.module('myApp', ['ui.router'])
.config(function($stateProvider) {
  $stateProvider
  .state('widget', {
    url: '/widgets',
    template: 'Widget: {{ widget }} Features: {{ features }}',
    controller: function($scope, widget, features){
      // resolve promises are injectable in the route controller
      $scope.widget = widget;
      $scope.features = features;
    },
    resolve: {
      // standard resolve value promise definition
      widget: function() {
        return {
          name: 'myWidget'
        };
      },
      // resolve promise injects sibling promise
      features: function(widget) {
        return ['featureA', 'featureB'].map(function(feature) { 
          return widget.name+':'+feature;
        });
      }
    }
  });
});

(index.html)

<div ng-app="myApp">
  <a ui-sref="widget({widgetId:6})">See Widget 6</a>
  <div ui-view></div>
</div>

Widget: {"name":"myWidget"} 
Features: ["myWidget:featureA","myWidget:featureB"]

Route resolves effectively represent an amount of work that needs to be completed before a route change can happen. These units of work, represented in the resolve as promises, are able to be dependency injected anywhere in the route state construct, which allows you a great deal of flexibility. Since the route change will only occur once all promises have resolved, you are able to effectively chain the promises within the route by chaining them using dependency injection.