API.md

#API Reference

• Core
  • new Promise(Function<Function resolve, Function reject> resolver)
  • .then([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])
  • .catch(Function handler)
  • .catch([Function ErrorClass...], Function handler)
  • .finally(Function handler)
  • .bind(dynamic thisArg)
  • .progressed(Function handler)
  • .done([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])
  • Promise.try(Function fn [, Array<dynamic>|dynamic arguments] [, dynamic ctx] )
  • Promise.fulfilled(dynamic value)
  • Promise.rejected(dynamic reason)
  • Promise.pending()
  • Promise.cast(dynamic value)
  • Promise.bind(dynamic thisArg)
  • Promise.is(dynamic value)
  • Promise.longStackTraces()
• Promise resolution
  • .fulfill(dynamic value)
  • .reject(dynamic reason)
  • .progress(dynamic value)
  • .asCallback
• Collections
  • .all()
  • .props()
  • .settle()
  • .any()
  • .some(int count)
  • .spread([Function fulfilledHandler] [, Function rejectedHandler ])
  • .map(Function mapper)
  • .reduce(Function reducer [, dynamic initialValue])
  • .filter(Function filterer)
  • Promise.all(Array<dynamic>|Promise values)
  • Promise.props(Object|Promise object)
  • Promise.settle(Array<dynamic>|Promise values)
  • Promise.any(Array<dynamic>|Promise values)
  • Promise.some(Array<dynamic>|Promise values, int count)
  • Promise.join([dynamic value...])
  • Promise.map(Array<dynamic>|Promise values, Function mapper)
  • Promise.reduce(Array<dynamic>|Promise values, Function reducer [, dynamic initialValue])
  • Promise.filter(Array<dynamic>|Promise values, Function filterer)
• Cancellation
  • .cancel()
  • .fork([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ])
  • .uncancellable()
  • .isCancellable()
• Synchronous inspection
  • .isFulfilled()
  • .isRejected()
  • .isPending()
  • .isResolved()
  • .inspect()
• Utility
  • .call(String propertyName [, dynamic arg...])
  • .get(String propertyName)
  • .nodeify([Function callback])
  • .toString()
  • .toJSON()
  • Promise.promisify(Function nodeFunction [, dynamic receiver])
  • Promise.promisify(Object target)
  • Promise.promisifyAll(Object target)
  • Promise.coroutine(GeneratorFunction generatorFunction)
  • Promise.spawn(GeneratorFunction generatorFunction)
  • Promise.noConflict()
  • Promise.onPossiblyUnhandledRejection(Function handler)

##Core

Core methods of Promise instances and core static methods of the Promise class.

#####new Promise(Function<Function resolve, Function reject> resolver) -> Promise

Create a new promise. The passed in function will receive functions resolve and reject as its arguments which can be called to seal the fate of the created promise.

Example:

function ajaxGetAsync(url) {
    return new Promise(function (resolve, reject) {
        var xhr = new XMLHttpRequest;
        xhr.addEventListener("error", reject);
        xhr.addEventListener("load", resolve);
        xhr.open("GET", url);
        xhr.send(null);
    });
}

Performance tips

new Promise(resolver) should be avoided in performance sensitive code.

In V8, anytime you call the above, you will create 3 function identities and 2 context objects because the resolve, reject callbacks require .binding for API ergonomics.

For instance when implementing a delay function, it's possible to just do this:

function delay(ms, value) {
    var resolver = Promise.pending();
    setTimeout(function(){
        resolver.fulfill(value);
    }, ms);
    return resolver.promise;
}

The above will only create 1 function identity and a context object and wasn't too hard to write. The savings are relatively good - it's possible to create 2.5 additional bluebird promises from the memory we saved ((2 * 80 + 60) / 88 =~ 2.5).

Note that it isn't really about raw memory - I know you have plenty. It's about the additional GC work which uses CPU.

#####.then([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ]) -> Promise

Promises/A+ .then() with progress handler. Returns a new promise chained from this promise. The new promise will be rejected or resolved depending on the passed fulfilledHandler, rejectedHandler and the state of this promise.

Example:

promptAsync("Which url to visit?").then(function(url){
    return ajaxGetAsync(url);
}).then(function(contents){
    alertAsync("The contents were: " + contents);
}).catch(function(e){
    alertAsync("Exception " + e);
});

#####.catch(Function handler) -> Promise

This is a catch-all exception handler, shortcut for calling .then(null, handler) on this promise. Any exception happening in a .then-chain will propagate to nearest .catch handler.

For compatibility with earlier ECMAScript version, an alias .caught() is provided for .catch().

#####.catch([Function ErrorClass...], Function handler) -> Promise

This extends .catch to work more like catch-clauses in languages like Java or C#. Instead of manually checking instanceof or .name === "SomeError", you may specify a number of error constructors which are eligible for this catch handler. The catch handler that is first met that has eligible constructors specified, is the one that will be called.

Example:

somePromise.then(function(){
    return a.b.c.d();
}).catch(TypeError, function(e){
    //If a is defined, will end up here because
    //it is a type error to reference property of undefined
}).catch(ReferenceError, function(e){
    //Will end up here if a wasn't defined at all
}).catch(function(e){
    //Generic catch-the rest, error wasn't TypeError nor
    //ReferenceError
});

You may also add multiple filters for a catch handler:

somePromise.then(function(){
    return a.b.c.d();
}).catch(TypeError, ReferenceError, function(e){
    //Will end up here on programmer error
}).catch(NetworkError, TimeoutError, function(e){
    //Will end up here on expected everyday network errors
}).catch(function(e){
    //Catch any unexpected errors
});

For a paramater to be considered a type of error that you want to filter, you need the constructor to have its .prototype property be instanceof Error.

Such a constructor can be minimally created like so:

function MyCustomError() {}
MyCustomError.prototype = Object.create(Error.prototype);

Using it:

Promise.fulfilled().then(function(){
    throw new MyCustomError();
}).catch(MyCustomError, function(e){
    //will end up here now
});

However if you want stack traces and cleaner string output, then you should do:

in Node.js and other V8 environments, with support for Error.captureStackTrace

function MyCustomError(message) {
    this.message = message;
    this.name = "MyCustomError";
    Error.captureStackTrace(this, MyCustomError);
}
MyCustomError.prototype = Object.create(Error.prototype);
MyCustomError.prototype.constructor = MyCustomError;

Using CoffeeScript's class for the same:

class MyCustomError extends Error
  constructor: (@message) ->
    @name = "MyCustomError"
    Error.captureStackTrace(this, MyCustomError)

For compatibility with earlier ECMAScript version, an alias .caught() is provided for .catch().

#####.finally(Function handler) -> Promise

Pass a handler that will be called regardless of this promise's fate. Returns a new promise chained from this promise. There are special semantics for .finally() in that the final value cannot be modified from the handler.

Consider the example:

function anyway() {
    $("#ajax-loader-animation").hide();
}

function ajaxGetAsync(url) {
    return new Promise(function (resolve, reject) {
        var xhr = new XMLHttpRequest;
        xhr.addEventListener("error", reject);
        xhr.addEventListener("load", resolve);
        xhr.open("GET", url);
        xhr.send(null);
    }).then(anyway, anyway);
}

This example doesn't work as intended because the then handler actually swallows the exception and returns undefined for any further chainers.

The situation can be fixed with .finally:

function ajaxGetAsync(url) {
    return new Promise(function (resolve, reject) {
        var xhr = new XMLHttpRequest;
        xhr.addEventListener("error", reject);
        xhr.addEventListener("load", resolve);
        xhr.open("GET", url);
        xhr.send(null);
    }).finally(function(){
        $("#ajax-loader-animation").hide();
    });
}

Now the animation is hidden but an exception or the actual return value will automatically skip the finally and propagate to further chainers. This is more in line with the synchronous finally keyword.

The .finally works like Q's finally method.

For compatibility with earlier ECMAScript version, an alias .lastly() is provided for .finally().

#####.bind(dynamic thisArg) -> Promise

Create a promise that follows this promise, but is bound to the given thisArg value. A bound promise will call its handlers with the bound value set to this. Additionally promises derived from a bound promise will also be bound promises with the same thisArg binding as the original promise.

---

Without arrow functions that provide lexical this, the correspondence between async and sync code breaks down when writing object-oriented code. .bind() alleviates this.

Consider:

MyClass.prototype.method = function() {
    try {
        var contents = fs.readFileSync(this.file);
        var url = urlParse(contents);
        var result = this.httpGetSync(url);
        var refined = this.refine(result);
        return this.writeRefinedSync(refined);
    }
    catch (e) {
        this.error(e.stack);
    }
};

The above has a direct translation:

MyClass.prototype.method = function() {
    return fs.readFileAsync(this.file).bind(this)
    .then(function(contents) {
        var url = urlParse(contents);
        return this.httpGetAsync(url);
    }).then(function(result){
        var refined = this.refine(result);
        return this.writeRefinedAsync(refined);
    }).catch(function(e){
        this.error(e.stack);
    });
};

.bind() is the most efficient way of utilizing this with promises. The handler functions in the above code are not closures and can therefore even be hoisted out if needed. There is literally no overhead when propagating the bound value from one promise to another.

---

.bind() also has a useful side purpose - promise handlers don't need to share a function to use shared state:

somethingAsync().bind({})
.then(function (aValue, bValue) {
    this.aValue = aValue;
    this.bValue = bValue;
    return somethingElseAsync(aValue, bValue);
})
.then(function (cValue) {
    return this.aValue + this.bValue + cValue;
});

The above without .bind() could be achieved with:

var scope = {};
somethingAsync()
.then(function (aValue, bValue) {
    scope.aValue = aValue;
    scope.bValue = bValue;
    return somethingElseAsync(aValue, bValue);
})
.then(function (cValue) {
    return scope.aValue + scope.bValue + cValue;
});

However, there are many differences when you look closer:

• Requires a statement so cannot be used in an expression context
• If not there already, an additional wrapper function is required to avoid leaking or sharing scope
• The handler functions are now closures, thus less efficient and not reusable

---

Note that bind is only propagated with promise transformation. If you create new promise chains inside a handler, those chains are not bound to the "upper" this:

something().bind(var1).then(function(){
    //`this` is var1 here
    return Promise.all(getStuff()).then(function(results){
        //`this` is undefined here
        //refine results here etc
    });
}).then(function(){
    //`this` is var1 here
});

However, if you are utilizing the full bluebird API offering, you will almost never need to resort to nesting promises in the first place. The above should be written more like:

something().bind(var1).then(function() {
    //`this` is var1 here
    return getStuff();
}).map(function(result){
    //`this` is var1 here
    //refine result here
}).then(function(){
    //`this` is var1 here
});

Also see this Stackoverflow answer on a good example on how utilizing the collection instance methods like .map() can clean up code.

---

If you don't want to return a bound promise to the consumers of a promise, you can rebind the chain at the end:

MyClass.prototype.method = function() {
    return fs.readFileAsync(this.file).bind(this)
    .then(function(contents) {
        var url = urlParse(contents);
        return this.httpGetAsync(url);
    }).then(function(result){
        var refined = this.refine(result);
        return this.writeRefinedAsync(refined);
    }).catch(function(e){
        this.error(e.stack);
    }).bind(); //The `thisArg` is implicitly undefined - I.E. the default promise `this` value
};

Rebinding can also be abused to do something gratuitous like this:

Promise.fulfilled("my-element")
    .bind(document)
    .then(document.getElementById)
    .bind(console)
    .then(console.log);

The above does console.log(document.getElementById("my-element"));. The .bind()s are necessary because in browser neither of the methods can be called as a stand-alone function.

#####.progressed(Function handler) -> Promise

Shorthand for .then(null, null, handler);. Attach a progress handler that will be called if this promise is progressed. Returns a new promise chained from this promise.

#####.done([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ]) -> Promise

Like .then(), but any unhandled rejection that ends up here will be thrown as an error.

#####Promise.try(Function fn [, Array<dynamic>|dynamic arguments] [, dynamic ctx] ) -> Promise

Start the chain of promises with Promise.try. Any synchronous exceptions will be turned into rejections on the returned promise.

function getUserById(id) {
    return Promise.try(function(){
        if (typeof id !== "number") {
            throw new Error("id must be a number");
        }
        return db.getUserById(id);
    });
}

Now if someone uses this function, they will catch all errors in their Promise .catch handlers instead of having to handle both synchronous and asynchronous exception flows.

Note about second argument: if it's specifically a true array, its values become respective arguments for the function call. Otherwise it is passed as is as the first argument for the function call.

For compatibility with earlier ECMAScript version, an alias Promise.attempt() is provided for Promise.try().

#####Promise.fulfilled(dynamic value) -> Promise

Create a promise that is fulfilled with the given value. If value is a trusted Promise, the promise will instead follow that promise, adapting to its state. The promise is synchronously fulfilled in the former case.

#####Promise.rejected(dynamic reason) -> Promise

Create a promise that is rejected with the given reason. The promise is synchronously rejected.

#####Promise.pending() -> PromiseResolver

Create a promise with undecided fate and return a PromiseResolver to control it. See Promise resultion.

#####Promise.cast(dynamic value) -> Promise

Cast the given value to a trusted promise. If value is already a trusted Promise, it is returned as is. If value is not a thenable, a fulfilled Promise is returned with value as its fulfillment value. If value is a thenable (Promise-like object, like those returned by jQuery's $.ajax), returns a trusted Promise that assimilates the state of the thenable.

Example: ($ is jQuery)

Promise.cast($.get("http://www.google.com")).then(function(){
    //Returning a thenable from a handler is automatically
    //cast to a trusted Promise as per Promises/A+ specification
    return $.post("http://www.yahoo.com");
}).then(function(){

}).catch(function(e){
    //jQuery doesn't throw real errors so use catch-all
    console.log(e.statusText);
});

#####Promise.bind(dynamic thisArg) -> Promise

Sugar for Promise.fulfilled(undefined).bind(thisArg);. See .bind().

#####Promise.is(dynamic value) -> boolean

See if value is a trusted Promise.

Promise.is($.get("http://www.google.com")); //false
Promise.is(Promise.cast($.get("http://www.google.com"))) //true

#####Promise.longStackTraces() -> void

Call this right after the library is loaded to enabled long stack traces. Long stack traces cannot be disabled after being enabled, and cannot be enabled after promises have alread been created. Long stack traces imply a substantial performance penalty, around 4-5x for throughput and 0.5x for latency.

Long stack traces are enabled by default in the debug build.

To enable them in all instances of bluebird in node.js, use the environment variable BLUEBIRD_DEBUG:

BLUEBIRD_DEBUG=1 node server.js

You should enabled long stack traces if you want better debugging experience. For example:

Promise.longStackTraces();
Promise.fulfilled().then(function outer() {
    return Promise.fulfilled().then(function inner() {
        return Promise.fulfilled().then(function evenMoreInner() {
            a.b.c.d()
        }).catch(function catcher(e){
            console.error(e.stack);
        });
    });
});

Gives

ReferenceError: a is not defined
    at evenMoreInner (<anonymous>:6:13)
From previous event:
    at inner (<anonymous>:5:24)
From previous event:
    at outer (<anonymous>:4:20)
From previous event:
    at <anonymous>:3:9
    at Object.InjectedScript._evaluateOn (<anonymous>:581:39)
    at Object.InjectedScript._evaluateAndWrap (<anonymous>:540:52)
    at Object.InjectedScript.evaluate (<anonymous>:459:21)

While with long stack traces disabled, you would get:

ReferenceError: a is not defined
    at evenMoreInner (<anonymous>:6:13)
    at tryCatch1 (<anonymous>:41:19)
    at Promise$_resolvePromise [as _resolvePromise] (<anonymous>:1739:13)
    at Promise$_resolveLast [as _resolveLast] (<anonymous>:1520:14)
    at Async$_consumeFunctionBuffer [as _consumeFunctionBuffer] (<anonymous>:560:33)
    at Async$consumeFunctionBuffer (<anonymous>:515:14)
    at MutationObserver.Promise$_Deferred (<anonymous>:433:17)

On client side, long stack traces currently only work in Firefox and Chrome.

##Promise resolution

A PromiseResolver can be used to control the fate of a promise. It is like "Deferred" known in jQuery. The PromiseResolver objects have a .promise property which returns a reference to the controlled promise that can be passed to clients. .promise of a PromiseResolver is not a getter function to match other implementations.

The methods of a PromiseResolver have no effect if the fate of the underlying promise is already decided (follow, reject, fulfill).

#####.fulfill(dynamic value) -> undefined

Fulfill the underlying promise with value as the fulfillment value. If value is a trusted Promise, the underlying promise will instead follow that promise, adapting to its state.

#####.reject(dynamic reason) -> undefined

Reject the underlying promise with reason as the rejection reason.

#####.progress(dynamic value) -> undefined

Progress the underlying promise with value as the progression value.

Example

function delay(ms) {
    var resolver = Promise.pending();
    var now = Date.now();
    setTimeout(function(){
        resolver.fulfill(Date.now() - now);
    }, ms);
    return resolver.promise;
}

delay(500).then(function(ms){
    console.log(ms + " ms passed");
});

#####.asCallback -> Function

Gives you a callback representation of the PromiseResolver. Note that this is not a method but a property. The callback accepts error object in first argument and success values on the 2nd parameter and the rest, I.E. node js conventions.

If the the callback is called with multiple success values, the resolver fullfills its promise with an array of the values.

var fs = require("fs");
function readAbc() {
    var resolver = Promise.pending();
    fs.readFile("abc.txt", resolver.asCallback);
    return resolver.promise;
}

readAbc()
.then(function(abcContents) {
    console.log(abcContents);
})
.catch(function(e) {
    console.error(e);
});

This example is an alternative to automatic promisification of node functions.

Performance tips

The asCallback is actually an accessor property (except on legacy browsers where it's eager data property) - so save the result if you need to call it multiple times.

This is more efficient way of promisification than using new Promise.

##Collections

Methods of Promise instances and core static methods of the Promise class to deal with collections of promises or mixed promises and values.

#####.all() -> Promise

Same as calling Promise.all(thisPromise). With the exception that if this promise is bound to a value, the returned promise is bound to that value too.

#####.props() -> Promise

Same as calling Promise.props(thisPromise). With the exception that if this promise is bound to a value, the returned promise is bound to that value too.

#####.settle() -> Promise

Same as calling Promise.settle(thisPromise). With the exception that if this promise is bound to a value, the returned promise is bound to that value too.

#####.any() -> Promise

Same as calling Promise.any(thisPromise). With the exception that if this promise is bound to a value, the returned promise is bound to that value too.

#####.some(int count) -> Promise

Same as calling Promise.some(thisPromise, count). With the exception that if this promise is bound to a value, the returned promise is bound to that value too.

#####.spread([Function fulfilledHandler] [, Function rejectedHandler ]) -> Promise

Like calling .then, but the fulfillment value or rejection reason is assumed to be an array, which is flattened to the formal parameters of the handlers.

Promise.all([task1, task2, task3]).spread(function(result1, result2, result3){

});

Normally when using .then the code would be like:

Promise.all([task1, task2, task3]).then(function(results){
    var result1 = results[0];
    var result2 = results[1];
    var result3 = results[2];
});

This is useful when the results array contains items that are not conceptually items of the same list.

#####.map(Function mapper) -> Promise

Same as calling Promise.map(thisPromise, mapper). With the exception that if this promise is bound to a value, the returned promise is bound to that value too.

#####.reduce(Function reducer [, dynamic initialValue]) -> Promise

Same as calling Promise.reduce(thisPromise, Function reducer, initialValue). With the exception that if this promise is bound to a value, the returned promise is bound to that value too.

#####.filter(Function filterer) -> Promise

Same as calling Promise.filter(thisPromise, filterer). With the exception that if this promise is bound to a value, the returned promise is bound to that value too.

In this example, a list of websites are pinged with 100ms timeout. .settle() is used to wait until all pings are either fulfilled or rejected. Then the settled list of PromiseInspections is filtered for those that fulfilled (responded in under 100ms) and mapped to the actual fulfillment value.

pingWebsitesAsync({timeout: 100}).settle()
.filter(function(inspection){
    return inspection.isFulfilled();
})
.map(function(inspection){
    return inspection.value();
})
.then(function(websites){
   //List of website names which answered
});

The above pattern is actually reusable and can be captured in a method:

Promise.prototype.settledWithFulfill = function() {
    return this.settle()
        .filter(function(inspection){
            return inspection.isFulfilled();
        })
        .map(function(inspection){
            return inspection.value();
        });
};

#####Promise.all(Array<dynamic>|Promise values) -> Promise

Given an array, or a promise of an array, which contains promises (or a mix of promises and values) return a promise that is fulfilled when all the items in the array are fulfilled. The promise's fulfillment value is an array with fulfillment values at respective positions to the original array. If any promise in the array rejects, the returned promise is rejected with the rejection reason.

In this example we create a promise that is fulfilled only when the pictures, comments and tweets are all loaded.

Promise.all([getPictures(), getComments(), getTweets()].then(function(results){
    //Everything loaded and good to go
    var pictures = results[0];
    var comments = results[1];
    var tweets = results[2];
}).catch(function(e){
    alertAsync("error when getting your stuff");
});

See .spread\(\) for a more convenient way to extract the fulfillment values.

The original array is not modified. The input array sparsity is retained in the resulting array.

#####Promise.props(Object|Promise object) -> Promise

Like Promise.all but for object properties instead of array items. Returns a promise that is fulfilled when all the properties of the object are fulfilled. The promise's fulfillment value is an object with fulfillment values at respective keys to the original object. If any promise in the object rejects, the returned promise is rejected with the rejection reason.

If object is a trusted Promise, then it will be treated as a promise for object rather than for its properties. All other objects are treated for their properties as is returned by Object.keys - the object's own enumerable properties.

Promise.props({
    pictures: getPictures(),
    comments: getComments(),
    tweets: getTweets()
}).then(function(result){
    console.log(result.tweets, result.pictures, result.comments);
});

Note that if you have no use for the result object other than retrieving the properties, it is more convenient to use Promise.all and .spread():

Promise.all([getPictures(), getComments(), getTweets()])
.spread(function(pictures, comments, tweets) {
    console.log(pictures, comments, tweets);
});

The original object is not modified.

#####Promise.settle(Array<dynamic>|Promise values) -> Promise

Given an array, or a promise of an array, which contains promises (or a mix of promises and values) return a promise that is fulfilled when all the items in the array are either fulfilled or rejected. The fulfillment value is an array of PromiseInspection instances at respective positions in relation to the input array.

The original array is not modified. The input array sparsity is retained in the resulting array.

#####Promise.any(Array<dynamic>|Promise values) -> Promise

Like Promise.some\(\), with 1 as count. However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly.

#####Promise.some(Array<dynamic>|Promise values, int count) -> Promise

Initiate a competetive race between multiple promises or values (values will become immediately fulfilled promises). When count amount of promises have been fulfilled, the returned promise is fulfilled with an array that contains the fulfillment values of the winners in order of resolution.

This example pings 4 nameservers, and logs the fastest 2 on console:

Promise.some([
    ping("ns1.example.com"),
    ping("ns2.example.com"),
    ping("ns3.example.com"),
    ping("ns4.example.com")
], 2).spread(function(first, second) {
    console.log(first, second);
});

If too many promises are rejected so that the promise can never become fulfilled, it will be immediately rejected with an array of rejection reasons in the order they were thrown in.

The original array is not modified.

#####Promise.join([dynamic value...]) -> Promise

Like Promise.all\(\) but instead of having to pass an array, the array is generated from the passed variadic arguments.

So instead of:

Promise.all([a, b]).spread(function(aResult, bResult) {

});

You can do:

Promise.join(a, b).spread(function(aResult, bResult) {

});

#####Promise.map(Array<dynamic>|Promise values, Function mapper) -> Promise

Map an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given mapper function with the signature (item, index, arrayLength) where item is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well.

If the mapper function returns promises, the returned promise will wait for all the mapped results to be resolved as well.

(TODO: an example where this is useful)

The original array is not modified. Sparse array holes are not visited and the resulting array retains the same sparsity as the original array.

#####Promise.reduce(Array<dynamic>|Promise values, Function reducer [, dynamic initialValue]) -> Promise

Reduce an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given reducer function with the signature (total, current, index, arrayLength) where item is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well.

(TODO: an example where this is useful)

The original array is not modified. Sparse array holes are not visited. If no intialValue is given and the array doesn't contain at least 2 items, the callback will not be called and undefined is returned. If initialValue is given and the array doesn't have at least 1 item, initialValue is returned.

#####Promise.filter(Array<dynamic>|Promise values, Function filterer) -> Promise

Filter an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given filterer function with the signature (item, index, arrayLength) where item is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well.

See the instance method .filter() for an example.

*The original array is not modified. Sparse array holes are not visited.

##Cancellation

By default, all Promises are cancellable. A cancellable promise can be cancelled if it's not resolved. Cancelling a promise propagates to the farthest ancestor of the target promise that is still pending, and rejects that promise with CancellationError. The rejection will then propagate back to the original promise and to its descendants. This roughly follows the semantics described here

If you are the resolver for a promise, you can react to a cancel in your promise by catching the CancellationError:

function ajaxGetAsync(url) {
    var xhr = new XMLHttpRequest;
    return new Promise(function (resolve, reject) {
        xhr.addEventListener("error", reject);
        xhr.addEventListener("load", resolve);
        xhr.open("GET", url);
        xhr.send(null);
    }).catch(Promise.CancellationError, function(e) {
        xhr.abort();
        throw e; //Don't swallow it
    });
}

#####.cancel() -> Promise

Cancel this promise. The cancellation will propagate to farthest ancestor promise which is still pending.

That ancestor will then be rejected with a CancellationError object as the rejection reason.

In a promise rejection handler you may check for a cancellation by seeing if the reason object has .name === "Cancel".

Promises are by default cancellable. If you want to restrict the cancellability of a promise before handing it out to a client, call .uncancellable() which returns an uncancellable promise.

#####.fork([Function fulfilledHandler] [, Function rejectedHandler ] [, Function progressHandler ]) -> Promise

Like .then(), but cancellation of the the returned promise or any of its descendant will not propagate cancellation to this promise or this promise's ancestors.

#####.uncancellable() -> Promise

Create an uncancellable promise based on this promise

#####.isCancellable() -> boolean

See if this promise can be cancelled.

##Synchronous inspection

Because .then() must give asynchronous guarantees, it cannot be used to inspect a given promise's state synchronously. The following code won't work:

var wasFulfilled = false;
var wasRejected = false;
var resolutionValueOrRejectionReason = null;
somePromise.then(function(v){
    wasFulfilled = true;
    resolutionValueOrRejectionReason = v
}).catch(function(v){
    wasRejected = true;
    resolutionValueOrRejectionReason = v
});
//Using the variables won't work here because .then must be called asynchronously

Synchronous inspection API allows you to do this like so:

var inspection = somePromise.inspect();

if(inspection.isFulfilled()){
    console.log("Was fulfilled with", inspection.value());
}

#####.isFulfilled() -> boolean

See if this promise has been fulfilled.

#####.isRejected() -> boolean

See if this promise has been rejected.

#####.isPending() -> boolean

See if this promise is still pending.

#####.isResolved() -> boolean

See if this promise is resolved -> either fulfilled or rejected.

#####.inspect() -> PromiseInspection

Synchronously inspect the state of this promise. The PromiseInspection will represent the state of the promise as snapshotted at the time of calling .inspect(). It will have the following methods:

.isFulfilled() -> boolean

See if the underlying promise was fulfilled at the creation time of this inspection object.

.isRejected() -> boolean

See if the underlying promise was rejected at the creation time of this inspection object.

.isPending() -> boolean

See if the underlying promise was pending at the creation time of this inspection object.

.value() -> dynamic, throws TypeError

Get the fulfillment value of the underlying promise. Throws if the promise wasn't fulfilled at the creation time of this inspection object.

.error() -> dynamic, throws TypeError

Get the rejection reason for the underlying promise. Throws if the promise wasn't rejected at the creation time of this inspection object.

##Utility

Functions that could potentially be handy in some situations.

#####.call(String propertyName [, dynamic arg...]) -> Promise

This is a convenience method for doing:

promise.then(function(obj){
    return obj[propertyName].call(obj, arg...);
});

#####.get(String propertyName) -> Promise

This is a convenience method for doing:

promise.then(function(obj){
    return obj[propertyName];
});

#####.nodeify([Function callback]) -> Promise

Register a node-style callback on this promise. When this promise is is either fulfilled or rejected, the node callback will be called back with the node.js convention where error reason is the first argument and success value is the second argument. The error argument will be null in case of success.

Returns back this promise instead of creating a new one. If the callback argument is not a function, this method does not do anything.

This can be used to create APIs that both accept node-style callbacks and return promises:

function getDataFor(input, callback) {
    return dataFromDataBase(input).nodeify(callback);
}

The above function can then make everyone happy.

Promises:

getDataFor("me").then(function(dataForMe) {
    console.log(dataForMe);
});

Normal callbacks:

getDataFor("me", function(err, dataForMe) {
    if( err ) {
        console.error( err );
    }
    console.log(dataForMe);
});

There is no effect on peformance if the user doesn't actually pass a node-style callback function.

#####.toString() -> String

#####.toJSON() -> Object

This is implicitly called by JSON.stringify when serializing the object. Returns a serialized representation of the Promise.

#####Promise.promisify(Function nodeFunction [, dynamic receiver]) -> Function

Returns a function that will wrap the given nodeFunction. Instead of taking a callback, the returned function will return a promise whose fate is decided by the callback behavior of the given node function. The node function should conform to node.js convention of accepting a callback as last argument and calling that callback with error as the first argument and success value on the second argument.

If the nodeFunction calls its callback with multiple success values, the fulfillment value will be an array of them.

If you pass a receiver, the nodeFunction will be called as a method on the receiver.

Example of promisifying the asynchronous readFile of node.js fs-module:

var readFile = Promise.promisify(require("fs").readFile);

readFile("myfile.js", "utf8").then(function(contents){
    return eval(contents);
}).then(function(result){
    console.log("The result of evaluating myfile.js", result);
}).catch(SyntaxError, function(e){
    console.log("File had syntax error", e);
//Catch any other error
}).catch(function(e){
    console.log("Error reading file", e);
});

Note that if the node function is a method of some object, you need to pass the object as the second argument like so:

var redisGet = Promise.promisify(redisClient.get, redisClient);
redisGet.then(function(){
    //...
});

Tip

Use .spread with APIs that have multiple success values:

var Promise = require("bluebird");
var request = Promise.promisify(require('request'));
request("http://www.google.com").spread(function(request, body) {
    console.log(body);
}).catch(function(err) {
    console.error(err);
});

The above uses request library which has a callback signature of multiple success values.

#####Promise.promisify(Object target) -> Object

This overload has been deprecated. The overload will continue working for now. The recommended method for promisifying multiple methods at once is Promise.promisifyAll(Object target)

#####Promise.promisifyAll(Object target) -> Object

Promisifies the entire object by going through the object's properties and creating an async equivalent of each function on the object and its prototype chain. The promisified method name will be the original method name postfixed with Async. Returns the input object.

Note that the original methods on the object are not overwritten but new methods are created with the Async-postfix. For example, if you promisifyAll() the node.js fs object use fs.statAsync() to call the promisified stat method.

Example:

Promise.promisifyAll(RedisClient.prototype);

//Later on, all redis client instances have promise returning functions:

redisClient.hexistsAsync("myhash", "field").then(function(v){

}).catch(function(e){

});

If you don't want to write on foreign prototypes, you can sub-class the target and promisify your subclass:

function MyRedisClient() {
    RedisClient.apply(this, arguments);
}
MyRedisClient.prototype = Object.create(RedisClient.prototype);
MyRedisClient.prototype.constructor = MyRedisClient;
Promise.promisify(MyRedisClient.prototype);

The promisified methods will be written on the MyRedisClient.prototype instead. This specific example doesn't actually work with node_redis because the createClient factory is hardcoded to instantiate RedisClient from closure.

It also works on singletons or specific instances:

var fs = Promise.promisifyAll(require("fs"));

fs.readFileAsync("myfile.js", "utf8").then(function(contents){
    console.log(contents);
}).catch(function(e){
    console.error(e.stack);
});

The entire prototype chain of the object is promisified on the object. Only enumerable are considered. If the object already has a promisified version of the method, it will be skipped. The target methods are assumed to conform to node.js callback convention of accepting a callback as last argument and calling that callback with error as the first argument and success value on the second argument. If the node method calls its callback with multiple success values, the fulfillment value will be an array of them.

If a method already has "Async" postfix, it will be duplicated. E.g. getAsync's promisified name is getAsyncAsync.

#####Promise.coroutine(GeneratorFunction generatorFunction) -> Function

Returns a function that can use yield to run asynchronous code synchronously. This feature requires the support of generators which are drafted in the next version of the language. Node version greater than 0.11.2 is required and needs to be executed with the --harmony-generators (or --harmony) command-line switch.

This is the recommended, simplest and most performant way of using asynchronous generators with bluebird. It is even faster than typical promise code because the creation of new anonymous function identities at runtime can be completely avoided without obfuscating your code.

var Promise = require("bluebird");

function delay(ms) {
    return new Promise(function(f){
        setTimeout(f, ms);
    });
}

function PingPong() {

}

PingPong.prototype.ping = Promise.coroutine(function* (val) {
    console.log("Ping?", val)
    yield delay(500)
    this.pong(val+1)
});

PingPong.prototype.pong = Promise.coroutine(function* (val) {
    console.log("Pong!", val)
    yield delay(500);
    this.ping(val+1)
});

var a = new PingPong();
a.ping(0);

Running the example with node version at least 0.11.2:

$ node --harmony test.js
Ping? 0
Pong! 1
Ping? 2
Pong! 3
Ping? 4
Pong! 5
Ping? 6
Pong! 7
Ping? 8
...

When called, the coroutine function will start an instance of the generator and returns a promise for its final value.

Doing Promise.coroutine(function*(){}) is almost like using the C# async keyword to mark the function, with yield working as the await keyword. Promises are somewhat like Tasks.

#####Promise.spawn(GeneratorFunction generatorFunction) -> Promise

Spawn a coroutine which may yield promises to run asynchronous code synchronously. This feature requires the support of generators which are drafted in the next version of the language. Node version greater than 0.11.2 is required and needs to be executed with the --harmony-generators (or --harmony) command-line switch.

Promise.spawn(function* () {
    var data = yield $.get("http://www.example.com");
    var moreUrls = data.split("\n");
    var contents = [];
    for( var i = 0, len = moreUrls.length; i < len; ++i ) {
        contents.push(yield $.get(moreUrls[i]));
    }
    return contents;
});

In the example is returned a promise that will eventually have the contents of the urls separated by newline on example.com.

Note that you need to try-catch normally in the generator function, any uncaught exception is immediately turned into a rejection on the returned promise. Yielding a promise that gets rejected causes a normal error inside the generator function.

Tip:

When Promise.spawn is called as a method of an object, that object becomes the receiver of the generator function too.

function ChatRoom(roomId) {
    this.roomId = roomId
}
ChatRoom.prototype.spawn = Promise.spawn;

ChatRoom.prototype.addUser = function( userId ) {
    return this.spawn(function* () {
        var isBanned = yield chatStore.userIsBannedForRoom(this.roomId, userId);
        if (isBanned) {
            throw new ChatError("You have been banned from this room");
        }
        return chatStore.addUserToRoom(this.roomId, userId);
    });
};

var room = new ChatRoom(1);
room.addUser(2);

In the above example, all the methods of ChatRoom can avoid the var self = this prologue and just use this normally inside the generator.

#####Promise.noConflict() -> Object

This is relevant to browser environments with no module loader.

Release control of the Promise namespace to whatever it was before this library was loaded. Returns a reference to the library namespace so you can attach it to something else.

<!-- the other promise library must be loaded first -->
<script type="text/javascript" src="/scripts/other_promise.js"></script>
<script type="text/javascript" src="/scripts/bluebird_debug.js"></script>
<script type="text/javascript">
//Release control right after
var Bluebird = Promise.noConflict();

//Cast a promise from some other Promise library using the Promise namespace to Bluebird:
var promise = Bluebird.cast(new Promise());
</script>

#####Promise.onPossiblyUnhandledRejection(Function handler) -> undefined

Add handler as the handler to call when there is a possibly unhandled rejection. The default handler logs the error stack to stderr or console.error in browsers.

Promise.onPossiblyUnhandledRejection(function(e, promise){
    throw e;
});

Passing no value or a non-function will have the effect of removing any kind of handling for possibly unhandled rejections.