#API Reference

##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);
    });
}

If you pass a promise object to the resolve function, the created promise will follow the state of that promise.

To make sure a function that returns a promise is following the implicit but critically important contract of promises, you can start a function with new Promise if you cannot start a chain immediately:

function getConnection(urlString) {
    return new Promise(function(resolve) {
        //Without new Promise, this throwing will throw an actual exception
        var params = parse(urlString);
        resolve(getAdapater(params).getConnection());
    });
}

The above ensures getConnection() fulfills the contract of a promise-returning function of never throwing a synchronous exception. Also see Promise.try and Promise.method

#####.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 dedefer 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 predicate...], 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 parameter 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.resolve().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)

This method also supports predicate-based filters. If you pass a predicate function instead of an error constructor, the predicate will receive the error as an argument. The return result of the predicate will be used determine whether the error handler should be called.

Predicates should allow for very fine grained control over caught errors: pattern matching, error-type sets with set operations and many other techniques can be implemented on top of them.

Example of using a predicate-based filter:

var Promise = require("bluebird");
var request = Promise.promisify(require("request"));

function clientError(e) {
    return e.code >= 400 && e.code < 500;
}

request("http://www.google.com").then(function(contents){
    console.log(contents);
}).catch(clientError, function(e){
   //A client error like 400 Bad Request happened
});

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

#####.error( [rejectedHandler] ) -> Promise

Like .catch but instead of catching all types of exceptions, it only catches those that don't originate from thrown errors but rather from explicit rejections.

Note, “errors” mean errors, as in objects that are instanceof Error - not strings, numbers and so on. See a string is not an error.

For example, if a promisified function errbacks the node-style callback with an error, that could be caught with .error(). However if the node-style callback throws an error, only .catch would catch that.

In the following example you might want to handle just the SyntaxError from JSON.parse and Filesystem errors from fs but let programmer errors bubble as unhandled rejections:

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

fs.readFileAsync("myfile.json").then(JSON.parse).then(function (json) {
    console.log("Successful json")
}).catch(SyntaxError, function (e) {
    console.error("file contains invalid json");
}).error(function (e) {
    console.error("unable to read file, because: ", e.message);
});

Now, because there is no catch-all handler, if you typed console.lag (causes an error you don't expect), you will see:

Possibly unhandled TypeError: Object #<Console> has no method 'lag'
    at application.js:8:13
From previous event:
    at Object.<anonymous> (application.js:7:4)
    at Module._compile (module.js:449:26)
    at Object.Module._extensions..js (module.js:467:10)
    at Module.load (module.js:349:32)
    at Function.Module._load (module.js:305:12)
    at Function.Module.runMain (module.js:490:10)
    at startup (node.js:121:16)
    at node.js:761:3

( If you don't get the above - you need to enable long stack traces )

And if the file contains invalid JSON:

file contains invalid json

And if the fs module causes an error like file not found:

unable to read file, because:  ENOENT, open 'not_there.txt'

#####.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().

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

Like .finally that is not called for rejections.

getUser().tap(function(user) {
    //Like in finally, if you return a promise from the handler
    //the promise is awaited for before passing the original value through
    return recordStatsAsync();
}).then(function(user) {
    //user is the user from getUser(), not recordStatsAsync()
});

#####.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.resolve("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.

#####.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.method(Function fn) -> Function

Returns a new function that wraps the given function fn. The new function will always return a promise that is fulfilled with the original functions return values or rejected with thrown exceptions from the original function.

This method is convenient when a function can sometimes return synchronously or throw synchronously.

Example without using Promise.method:

MyClass.prototype.method = function(input) {
    if (!this.isValid(input)) {
        return Promise.reject(new TypeError("input is not valid"));
    }

    if (this.cache(input)) {
        return Promise.resolve(this.someCachedValue);
    }

    return db.queryAsync(input).bind(this).then(function(value) {
        this.someCachedValue = value;
        return value;
    });
};

Using the same function Promise.method, there is no need to manually wrap direct return or throw values into a promise:

MyClass.prototype.method = Promise.method(function(input) {
    if (!this.isValid(input)) {
        throw new TypeError("input is not valid");
    }

    if (this.cachedFor(input)) {
        return this.someCachedValue;
    }

    return db.queryAsync(input).bind(this).then(function(value) {
        this.someCachedValue = value;
        return value;
    });
});

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

Create a promise that is resolved with the given value. If value is a thenable or promise, the returned promise will assume its state.

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

Create a promise that is rejected with the given reason.

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

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

The use of Promise.defer is discouraged - it is much more awkward and error-prone than using new Promise.

#####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.resolve(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 , thenable returned from $.get is not a `Promise` instance
Promise.is(Promise.cast($.get("http://www.google.com"))) //true, `.cast` cast the thenable into a `Promise`

Trusted Promises are promises originating in the currently used copy of Bluebird. Promises originating in other libraries are called thenables and are not trusted promises. This method is used for checking if a passed value is of the same type as Promise itself creates.

#####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.resolve().then(function outer() {
    return Promise.resolve().then(function inner() {
        return Promise.resolve().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.

##Progression

#####.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.

##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).

The use of Promise.defer and deferred objects is discouraged - it is much more awkward and error-prone than using new Promise.

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

Resolve the underlying promise with value as the resolution value. If value is a thenable or a promise, the underlying promise will assume 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.defer();
    var now = Date.now();
    setTimeout(function(){
        resolver.resolve(Date.now() - now);
    }, ms);
    return resolver.promise;
}

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

#####.callback -> 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.defer();
    fs.readFile("abc.txt", resolver.callback);
    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 callback 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.

##Timers

Methods to delay and time promises out.

#####.delay(int ms) -> Promise

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

#####.timeout(int ms [, String message]) -> Promise

Returns a promise that will be fulfilled with this promise's fulfillment value or rejection reason. However, if this promise is not fulfilled or rejected within ms milliseconds, the returned promise is rejected with a Promise.TimeoutError instance.

You may specify a custom error message with the message parameter.

The example function fetchContent tries to fetch the contents of a web page with a 50ms timeout and sleeping 100ms between each retry. If there is no response after 5 retries, then the returned promise is rejected with a ServerError (made up error type). Additionally the whole process can be cancelled from outside at any point.

function fetchContent(retries) {
    if (!retries) retries = 0;
    var jqXHR = $.get("http://www.slowpage.com");
    //Cast the jQuery promise into a bluebird promise
    return Promise.cast(jqXHR)
        .cancellable()
        .timeout(50)
        .catch(Promise.TimeoutError, function() {
            if (retries < 5) {
                return Promise.delay(100).then(function(){
                    return fetchContent(retries+1);
                });
            }
            else {
                throw new ServerError("not responding after 5 retries");
            }
        })
        .catch(Promise.CancellationError, function(er) {
            jqXHR.abort();
            throw er; //Don't swallow it
        });
}

#####Promise.delay([dynamic value], int ms) -> Promise

Returns a promise that will be fulfilled with value (or undefined) after given ms milliseconds. If value is a promise, the delay will start counting down when it is fulfilled and the returned promise will be fulfilled with the fulfillment value of the value promise.

Promise.delay(500).then(function(){
    console.log("500 ms passed");
    return "Hello world";
}).delay(500).then(function(helloWorldString) {
    console.log(helloWorldString);
    console.log("another 500 ms passed") ;
});

##Promisification

#####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.

#####.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.

##Cancellation

By default, a promise is not cancellable. A promise can be marked as cancellable with .cancellable(). A cancellable promise can be cancelled if it's not resolved. Cancelling a promise propagates to the farthest cancellable 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.

Promises marked with .cancellable() return cancellable promises automatically.

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);
    }).cancellable().catch(Promise.CancellationError, function(e) {
        xhr.abort();
        throw e; //Don't swallow it
    });
}

#####.cancellable() -> Promise

Marks this promise as cancellable. Promises by default are not cancellable after v0.11 and must be marked as such for .cancel() to have any effect. Marking a promise as cancellable is infectious and you don't need to remark any descendant promise.

If you have code written prior v0.11 using cancellation, add calls to .cancellable() at the starts of promise chains that need to support cancellation in themselves or somewhere in their descendants.

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

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

That ancestor will then be rejected with a CancellationError (get a reference from Promise.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 not cancellable. Use .cancellable() to mark a promise as cancellable.

#####.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 defer.

#####.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 defer 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.

##Generators

Using ECMAScript6 generators feature to implement C# 5.0 async/await like syntax.

#####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.

Tip

If you yield an array then its elements are implicitly waited for. You may add your own custom special treatments with Promise.coroutine.addYieldHandler

You can combine it with ES6 destructuring for some neat syntax:

var getData = Promise.coroutine(function* (urlA, urlB) {
    [resultA, resultB] = yield [http.getAsync(urlA), http.getAsync(urlB)];
    //use resultA
    //use resultB
});

You might wonder why not just do this?

var getData = Promise.coroutine(function* (urlA, urlB) {
    var resultA = yield http.getAsync(urlA);
    var resultB = yield http.getAsync(urlB);
});

The problem with the above is that the requests are not done in parallel. It will completely wait for request A to complete before even starting request B. In the array syntax both requests fire off at the same time in parallel.

#####Promise.coroutine.addYieldHandler(function handler) -> void

By default you can only yield Promises, Thenables and Arrays inside coroutines. You can use this function to add yielding support for arbitrary types.

For example, if you wanted yield 500 to be same as yield Promise.delay(500):

Promise.coroutine.addYieldHandler(function(value) {
     if (typeof value === "number") return Promise.delay(value);
});

Yield handlers are called when you yield something that is not supported by default. The first yield handler to return a promise or a thenable will be used. If no yield handler returns a promise or a thenable then an error is raised.

An example of implementing callback support with addYieldHandler:

This is a demonstration of how powerful the feature is and not the recommended usage. For best performance you need to use promisifyAll and yield promises directly.

var Promise = require("bluebird");
var fs = require("fs");

var _ = (function() {
    var promise = null;
    Promise.coroutine.addYieldHandler(function(v) {
        if (v === void 0 && promise != null) {
            return promise;
        }
        promise = null;
    });
    return function() {
        var def = Promise.defer();
        promise = def.promise;
        return def.callback;
    };
})();


var readFileJSON = Promise.coroutine(function* (fileName) {
   var contents = yield fs.readFile(fileName, "utf8", _());
   return JSON.parse(contents);
});

An example of implementing thunks support with addYieldHandler:

This is a demonstration of how powerful the feature is and not the recommended usage. For best performance you need to use promisifyAll and yield promises directly.

var Promise = require("bluebird");
var fs = require("fs");

Promise.coroutine.addYieldHandler(function(v) {
    if (typeof v === "function") {
        var def = Promise.defer();
        try { v(def.callback); } catch(e) { def.reject(e); }
        return def.promise;
    }
});

var readFileThunk = function(fileName, encoding) {
    return function(cb) {
        return fs.readFile(fileName, encoding, cb);
    };
};

var readFileJSON = Promise.coroutine(function* (fileName) {
   var contents = yield readFileThunk(fileName, "utf8");
   return JSON.parse(contents);
});

##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];
});

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

Convenience method for:

.then(function() {
   return value;
});

in the case where value doesn't change its value.

That means value is bound at the time of calling .return() so this will not work as expected:

function getData() {
    var data;

    return query().then(function(result) {
        data = result;
    }).return(data);
}

because data is undefined at the time .return is called.

For compatibility with earlier ECMAScript version, an alias .thenReturn() is provided for .return().

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

Convenience method for:

.then(function() {
   throw reason;
});

Same limitations apply as with .return().

For compatibility with earlier ECMAScript version, an alias .thenThrow() is provided for .throw().

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

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

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

#####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.

##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.

#####.race() -> Promise

Same as calling Promise.race(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.race(Array|Promise promises) -> 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 or rejected as soon as a promise in the array is fulfilled or rejected with the respective rejection reason or fulfillment value.

Example of implementing a timeout in terms of Promise.race:

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

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

function timeout(promise, time) {
    var timeout = delay(time).then(function () {
        throw new Promise.TimeoutError("Operation timed out after " + time + " ms");
    });

    return Promise.race([promise, timeout]);
}

timeout(fs.readFileAsync("slowfile.txt"), 300).then(function (contents) {
    console.log("Here are the contents", contents);
}).
catch(Promise.TimeoutError, function (e) {
    console.error("Sorry retrieving file took too long");
});

Note If you pass empty array or a sparse array with no values, or a promise/thenable for such, it will be forever pending.

#####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 or thenables, 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.

#####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.

If the reducer function returns a promise or a thenable, the result for the promise is awaited for before continuing with next iteration.

Read given files sequentially while summing their contents as an integer. Each file contains just the text 10.

Promise.reduce(["file1.txt", "file2.txt", "file3.txt"], function(total, fileName) {
    return fs.readFileAsync(fileName, "utf8").then(function(contents) {
        return total + parseInt(contents, 10);
    });
}, 0).then(function(total) {
    //Total is 30
});

The original array is not modified. If intialValue is undefined (or a promise that resolves to undefined) and the array contains only 1 item, the callback will not be called and undefined is returned. If the array is empty, the callback will not be called and initialValue is returned (which may be undefined).

#####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.

The return values from the filtered functions are coerced to booleans, with the exception of promises and thenables which are awaited for their eventual result.

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

*The original array is not modified.