norman-promise

ECMAScript 6 compliant Promise implementation with a few nice extensions.

#API

##Creating Promises

###Standard Promise API

var p = new Promise(function (resolve, reject) {
    // Do something async and eventually call resolve or reject
});

###Defer API

var p = Promise.defer(); // Underlying promise is p.promise

// Do something async and eventually call p.resolve or p.reject

##Promise.prototype methods ###then(function: onFulfilled, function: onRejected)

var p = new Promise(function (resolve, reject { ... })
                .then(function (result) {
                    // this will be called if promise is fulfilled
                }, function (err) {
                    // this will be called if promise is rejected
                });

###catch(function: onRejected)

var p = new Promise(function (resolve, reject { ... })
                .catch(function (err) {
                    // this will be called if promise is rejected
                });

###Correctly catching errors

// Not recommanded: if something happen in the onFulfilled callback, onRejected will not be called
var p1 = new Promise(function (resolve, reject { ... })
                .then(onFulfilled, onRejected);
                
// Much better: if something happen in the onFulfilled callback, onRejected will be called
var p2 = new Promise(function (resolve, reject { ... })                 
                .then(onFulfilled)
                .catch(onRejected);

###finally(function: finalizer)

This promise extension allows having garbage collection code running without interfering with the promise chain

var p = doSomethingAsync1()
            .then(function (result) {
                return doSomethingAsync2(result);
            })
            .finally(function () {
                // you may put cleanup code here, it will always be called
            })
            .then (function (result2) {
                // result2 is the resolved value of doSomethingAsync2(result)
            });

###callback(function(Error, any): done) This promise extension allows supporting optional callbacks when promise is settled

function myFunctionWithOptionalCallback(done) {
  return doSomethingAsync().callback(done);
}

• p.callback(done) returns a promise which will be settled after p is settled

• If done is a function, done will be called when p is settled

• Callback function follows standard node.js convention:

  • if promise is fulfilled, result is passed as second parameter

  • if promised is rejected, error is passed as first parameter

##Promise.prototype properties

###id: Number Unique promise identifier (could be useful for debugging)

###result: any Once the promise is settled this property returns the promise result or reject error

###status: The status of the promise, possible values are

• Promise.PENDING

• Promise.FULFILLED

• Promise.REJECTED

##Promise constructor methods

###Promise.resolve(any: resolution) Returns a promise resolved with the given resolution. If the resolution is a Promise or a thenable object, the resulting promise will be settled when the resolution is settled and fulfilled or rejected accordingly.

###Promise.reject(Error: err) Returns a rejected promise with reason err.

###Promise.cast(any: wrapped) Returns a promise wrapping the wrapped input.

• if wrapped is a Promise, Promise.cast returns wrapped itself

• otherwise, Promise.cast is equivalent to Promise.resolve.

###Promise.all(Promise[]: promises) Returns a promise with the following properties.

• It will be fulfilled if/when all promises in promises array are fulfilled. In that case, it is fulfilled with an array of the promises results.

• it will be rejected if/when one the promises is rejected. In that case it is rejected with the reason of the rejected promise.

###Promise.race(Promise[]: promises) Returns a promise fulfilled/rejected with the result of the first promise to be settled.

###Promise.waitAll(Promise[]: promises) Returns a promise with the following properties

• It will be settled when all promises are settled.

• If all promises are fulfilled, Promise.all will be fulfilled with an array of the promise results

• If at least one promise is rejected, Promise.all will be rejected with an error object with a detail property

  • detail.failCount contains the number of rejected promises

  • detail.errors is an array of promise reject errors: if k-th promise is rejected detail.errors[k] contains the corresponding error otherwise detail.errors[k] is undefined

  • detail.results is an array of promise results: if k-th promise is fulfilled detail.results[k] contains the corresponding result otherwise detail.result[k] is undefined

###Promise.invoke(function: fn, ...) Convert a standard node.js callback-based call to a promise-based one

var fs = require("fs");

var p = Promise.invoke(fs.open, "tempFile.txt", "r")
          .then(function (fd) {
            // If method returns a single value it is available as promise result
            var buffer = new Buffer(4096);
            return Promise.invoke(fs.read, fd, 0, 4096, 0)
                .then(function (result) {
                  // If method returns multiple values, the promise result wraps them in an array
                  var bytesRead = result[0];
                  var buf = result[1];
                });
          });