Promises API

[Back to Additional Features] (Additional-Features)

If you aren’t familiar with Promises, perhaps the Wikipedia definition will help:

In computer science, future, promise, and delay refer to constructs used for synchronizing in some concurrent programming languages. They describe an object that acts as a proxy for a result that is initially unknown, usually because the computation of its value is yet incomplete.

Put another way, a Promise represents a future value that will eventually be returned asynchronously. In the JavaScript world, the folks at CommonJS have proposed a specification called Promises/A, which is what the DeftJS Promise API is modeled upon.

Basic Usage

In it's most basic and common form, a method will create and return a Promise like this:

// A method in a service class which uses a Store and returns a Promise
loadCompanies: function() {
  var deferred = Ext.create('Deft.Deferred');
  
  this.companyStore.load({

    callback: function(records, operation, success) {
      if (success) {
        return deferred.resolve(records);
      } else {
        return deferred.reject("Error loading Companies.");
      }
    }

  });
  
  return deferred.promise;
}

You can see this method first creates a Deferred object. It then returns a Promise object for use by the caller. Finally, in the asynchronous callback, it resolves the Deferred object if the call as successful, and rejects the Deferred if the call failed.

The method which calls the above code and works with the returned Promise might look like:

// Using a Promise returned by another object.
loadCompanies: function() {

  this.companyService.loadCompanies().then({
    success: function(records) {
      // Do something with result.
    },
    failure: function(error) {
      // Do something on failure.
    }
  }).always(function() {
    // Do something whether call succeeded or failed
  });

}

The calling code uses the Promise returned from the companyService.loadCompanies() method and uses then() to attach success and failure handlers. Finally, an always() method call is chained onto the returned Promise. This specifies a callback function that will run whether the underlying call succeeded or failed.

Promise vs. Deferred

A common first question is: "What is the difference between a Deferred and a Promise?" Here is a list which highlights some of the differences:

Deferred:

• Wraps asynchronous call(s)
• Manages the state of the asynchronous call
• Exposes methods to change the state of the asynchronous call (resolve(), reject(), etc.)

Promise:

• Represents a future value that will be returned asynchronously
• A "public" view of the underlying Deferred object state
• Only exposes callback hooks (success, failure, etc.)

So the general idea is that the Deferred is “private”, and actually wraps the async call. The Promise is the “public” view of the state of the Deferred. It won’t allow you to resolve or reject its state, but it will allow you to attach callbacks that are invoked when the state of the Deferred changes.

Next: Advanced IoC Configuration