![Build Status](https://travis-ci.org/petkaantonov/bluebird.png?branch=master)
#Introduction
Bluebird is a fully featured promise library with focus on innovative features and performance.
#Topics
#Features:
- Promises A+ 3.x.x
- Promises A+ 2.x.x
- Cancellation
- Progression
- Synchronous inspection
.bind
- Complete parallel for C# 5.0 async and await
- Collection methods such as All, any, some, settle, map, filter, reduce, spread, join, race...
- Practical debugging solutions such as unhandled rejection reporting, typed catches, catching only what you expect and very long, relevant stack traces without losing perf
- Sick performance
Passes AP2, AP3, Cancellation, Progress, promises_unwrapping (Just in time thenables), Q and When.js tests. See testing.
#Quick start
##Node.js
npm install bluebird
Then:
var Promise = require("bluebird");
If you want to ensure you get your own fresh copy of bluebird, do instead:
var Promise = require("bluebird/js/main/promise")();
##Browsers
Download the bluebird.js file. And then use a script tag:
<script type="text/javascript" src="/scripts/bluebird.js"></script>
The global variable Promise
becomes available after the above script tag.
After quick start, see API Reference and examples
###Browser support
Browsers that implement ECMA-262, edition 5 and later are supported.
IE8 (ECMAS-262, edition 3) is supported if you include es5-shim.js and es5-sham.js.
#What are promises and why should I use them?
You should use promises to turn this:
readFile("file.json", function(err, val) {
if( err ) {
console.error("unable to read file");
}
else {
try {
val = JSON.parse(val);
console.log(val.success);
}
catch( e ) {
console.error("invalid json in file");
}
}
});
Into this:
readFile("file.json").then(JSON.parse).then(function(val) {
console.log(val.success);
})
.catch(SyntaxError, function(e) {
console.error("invalid json in file");
})
.catch(function(e){
console.error("unable to read file")
});
Actually you might notice the latter has a lot in common with code that would do the same using synchronous I/O:
try {
var val = JSON.parse(readFile("file.json"));
console.log(val.success);
}
catch(SyntaxError e) {
console.error("invalid json in file");
}
catch(Error e) {
console.error("unable to read file")
}
And that is the point - being able to have something that is a lot like return
and throw
in synchronous code.
You can also use promises to improve code that was written with callback helpers:
mapSeries(URLs, function (URL, done) {
var options = {};
needle.get(URL, options, function (error, response, body) {
if (error) {
return done(error)
}
try {
var ret = JSON.parse(body);
return done(null, ret);
}
catch (e) {
done(e);
}
});
}, function (err, results) {
if (err) {
console.log(err)
} else {
console.log('All Needle requests successful');
processAndSaveAllInDB(results, function (err) {
if (err) {
return done(err)
}
console.log('All Needle requests saved');
done(null);
});
}
});
Is more pleasing to the eye when done with promises:
Promise.promisifyAll(needle);
var options = {};
var current = Promise.fulfilled();
Promise.map(URLs, function(URL) {
current = current.then(function () {
return needle.getAsync(URL, options);
});
return current;
}).map(function(responseAndBody){
return JSON.parse(responseAndBody[1]);
}).then(function (results) {
return processAndSaveAllInDB(results);
}).then(function(){
console.log('All Needle requests saved');
}).catch(function (e) {
console.log(e);
});
Also promises don't just give you correspondences for synchronous features but can also be used as limited event emitters or callback aggregators.
More reading:
#Error handling
This is a problem every promise library needs to handle in some way. Unhandled rejections/exceptions don't really have a good agreed-on asynchronous correspondence. The problem is that it is impossible to predict the future and know if a rejected promise will eventually be handled.
There are two common pragmatic attempts at solving the problem that promise libraries do.
The more popular one is to have the user explicitly communicate that they are done and any unhandled rejections should be thrown, like so:
download().then(...).then(...).done();
For handling this problem, in my opinion, this is completely unacceptable and pointless. The user must remember to explicitly call .done
and that cannot be justified when the problem is forgetting to create an error handler in the first place.
The second approach, which is what bluebird by default takes, is to call a registered handler if a rejection is unhandled by the start of a second turn. The default handler is to write the stack trace to stderr or console.error
in browsers. This is close to what happens with synchronous code - your code doens't work as expected and you open console and see a stack trace. Nice.
Of course this is not perfect, if your code for some reason needs to swoop in and attach error handler to some promise after the promise has been hanging around a while then you will see annoying messages. In that case you can use the .done()
method to signal that any hanging exceptions should be thrown.
If you want to override the default handler for these possibly unhandled rejections, you can pass yours like so:
Promise.onPossiblyUnhandledRejection(function(error){
throw error;
});
If you want to also enable long stack traces, call:
Promise.longStackTraces();
right after the library is loaded.
In node.js use the environment flag BLUEBIRD_DEBUG
:
BLUEBIRD_DEBUG=1 node server.js
to enable long stack traces in all instances of bluebird.
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, even after using every trick to optimize them.
Long stack traces are enabled by default in the debug build.
####Expected and unexpected errors
A practical problem with Promises/A+ is that it models Javascript try-catch
too closely for its own good. Therefore by default promises inherit try-catch
warts such as the inability to specify the error types that the catch block is eligible for. It is an anti-pattern in every other language to use catch-all handlers because they swallow exceptions that you might not know about.
Now, Javascript does have a perfectly fine and working way of creating error type hierarchies. It is still quite awkward to use them with the built-in try-catch
however:
try {
}
catch(e) {
if( e instanceof WhatIWantError) {
}
else {
throw e;
}
}
Without such checking, unexpected errors would be silently swallowed. However, with promises, bluebird brings the future (hopefully) here now and extends the .catch
to accept potential error type eligibility.
For instance here it is expected that some evil or incompetent entity will try to crash our server from SyntaxError
by providing syntactically invalid JSON:
getJSONFromSomewhere().then(function(jsonString) {
return JSON.parse(jsonString);
}).then(function(object) {
console.log("it was valid json: ", object);
}).catch(SyntaxError, function(e){
console.log("don't be evil");
});
Here any kind of unexpected error will automatically reported on stderr along with a stack trace because we only register a handler for the expected SyntaxError
.
Ok, so, that's pretty neat. But actually not many libraries define error types and it is in fact a complete ghetto out there with ad hoc strings being attached as some arbitrary property name like .name
, .type
, .code
, not having any property at all or even throwing strings as errors and so on. So how can we still listen for expected errors?
Bluebird defines a special error type RejectionError
(you can get a reference from Promise.RejectionError
). This type of error is given as rejection reason by promisified methods when
their underlying library gives an untyped, but expected error. Primitives such as strings, and error objects that are directly created like new Error("database didn't respond")
are considered untyped.
Example of such library is the node core library fs
. So if we promisify it, we can catch just the errors we want pretty easily and have programmer errors be redirected to unhandled rejection handler so that we notice them:
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");
}).catch(Promise.RejectionError, function (e) {
console.error("unable to read file, because: ", e.message);
});
The last catch
handler is only invoked when the fs
module explicitly used the err
argument convention of async callbacks to inform of an expected error. The RejectionError
instance will contain the original error in its .cause
property but it does have a direct copy of the .message
and .stack
too. In this code any unexpected error - be it in our code or the fs
module - would not be caught by these handlers and therefore not swallowed.
Since a catch
handler typed to Promise.RejectionError
is expected to be used very often, it has a neat shorthand:
.error(function (e) {
console.error("unable to read file, because: ", e.message);
});
See API documentation for .error()
####How do long stack traces differ from e.g. Q?
Bluebird attempts to have more elaborate traces. Consider:
Error.stackTraceLimit = 25;
Q.longStackSupport = true;
Q().then(function outer() {
return Q().then(function inner() {
return Q().then(function evenMoreInner() {
a.b.c.d();
}).catch(function catcher(e){
console.error(e.stack);
});
})
});
You will see
ReferenceError: a is not defined
at evenMoreInner (<anonymous>:7:13)
From previous event:
at inner (<anonymous>:6:20)
Compare to:
Error.stackTraceLimit = 25;
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);
});
});
});
ReferenceError: a is not defined
at evenMoreInner (<anonymous>:7:13)
From previous event:
at inner (<anonymous>:6:36)
From previous event:
at outer (<anonymous>:5:32)
From previous event:
at <anonymous>:4:21
at Object.InjectedScript._evaluateOn (<anonymous>:572:39)
at Object.InjectedScript._evaluateAndWrap (<anonymous>:531:52)
at Object.InjectedScript.evaluate (<anonymous>:450:21)
A better and more practical example of the differences can be seen in gorgikosev's debuggability competition.
####Can I use long stack traces in production?
Probably yes. Bluebird uses multiple innovative techniques to optimize long stack traces. Even with long stack traces, it is still way faster than similarly featured implementations that don't have long stack traces enabled and about same speed as minimal implementations. A slowdown of 4-5x is expected, not 50x.
What techniques are used?
#####V8 API second argument
This technique utilizes the slightly under-documented second argument of V8 Error.captureStackTrace
. It turns out that the second argument can actually be used to make V8 skip all library internal stack frames for free. It only requires propagation of callers manually in library internals but this is not visible to you as user at all.
Without this technique, every promise (well not every, see second technique) created would have to waste time creating and collecting library internal frames which will just be thrown away anyway. It also allows one to use smaller stack trace limits because skipped frames are not counted towards the limit whereas with collecting everything upfront and filtering afterwards would likely have to use higher limits to get more user stack frames in.
#####Sharing stack traces
Consider:
function getSomethingAsync(fileName) {
return readFileAsync(fileName).then(function(){
}).then(function() {
}).then(function() {
});
}
Everytime you call this function it creates 4 promises and in a straight-forward long stack traces implementation it would collect 4 almost identical stack traces. Bluebird has a light weight internal data-structure (kcnown as context stack in the source code) to help tracking when traces can be re-used and this example would only collect one trace.
#####Lazy formatting
After a stack trace has been collected on an object, one must be careful not to reference the .stack
property until necessary. Referencing the property causes
an expensive format call and the stack property is turned into a string which uses much more memory.
What about Q #111?
Long stack traces is not inherently the problem. For example with latest Q with stack traces disabled:
var Q = require("q");
function test(i){
if (i <= 0){
return Q.when('done')
} else {
return Q.when(i-1).then(test)
}
}
test(1000000000).then(function(output){console.log(output) });
After 2 minutes of running this, it will give:
FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - process out of memory
So the problem with this is how much absolute memory is used per promise - not whether long traces are enabled or not.
For some purpose, let's say 100000 parallel pending promises in memory at the same time is the maximum. You would then roughly use 100MB for them instead of 10MB with stack traces disabled.For comparison, just creating 100000 functions alone will use 14MB if they're closures. All numbers can be halved for 32-bit node.
#Development
For development tasks such as running benchmarks or testing, you need to clone the repository and install dev-dependencies.
Install node, npm, and grunt.
git clone git@github.com:petkaantonov/bluebird.git
cd bluebird
npm install
##Testing
To run all tests, run grunt test
. Note that 10 processes are created to run the tests in parallel. The stdout of tests is ignored by default and everything will stop at the first failure.
Individual files can be run with grunt test --run=filename
where filename
is a test file name in /test
folder or /test/mocha
folder. The .js
prefix is not needed. The dots for AP compliance tests are not needed, so to run /test/mocha/2.3.3.js
for instance:
grunt test --run=233
When trying to get a test to pass, run only that individual test file with --verbose
to see the output from that test:
grunt test --run=233 --verbose
The reason for the unusual way of testing is because the majority of tests are from different libraries using different testing frameworks and because it takes forever to test sequentially.
###Testing in browsers
To test in browsers:
cd browser
setup
Then open the index.html
in your browser. Requires bash (on windows the mingw32 that comes with git works fine too).
You may also visit the github hosted page.
Keep the test tab active because some tests are timing-sensitive and will fail if the browser is throttling timeouts. Chrome will do this for example when the tab is not active.
##Benchmarks
Currently the most relevant benchmark is @gorkikosev's benchmark in the article Analysis of generators and other async patterns in node. The benchmark emulates a situation where n amount of users are making a request in parallel to execute some mixed async/sync action. The benchmark has been modified to include a warm-up phase to minimize any JITing during timed sections.
You can run the benchmark with:
bench spion
While on the project root. Requires bash (on windows the mingw32 that comes with git works fine too).
Node 0.11.2+ is required to run the generator examples.
Another benchmark to run is the When.js benchmarks by CujoJS. The reduce and map have been modified from the original. The benchmarks also include warmup-phases.
bench cujojs
While on the project root. Requires bash (on windows the mingw32 that comes with git works fine too).
##Custom builds
Custom builds for browsers are supported through a command-line utility.
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#any---promise"><code>.any</code></a> and <a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promiseanyarraydynamicpromise-values---promise"><code>Promise.any</code></a></td><td><code>any</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#race---promise"><code>.race</code></a> and <a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promiseracearraypromise-promises---promise"><code>Promise.race</code></a></td><td><code>race</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#callstring-propertyname--dynamic-arg---promise"><code>.call</code></a> and <a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#getstring-propertyname---promise"><code>.get</code></a></td><td><code>call_get</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#filterfunction-filterer---promise"><code>.filter</code></a> and <a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promisefilterarraydynamicpromise-values-function-filterer---promise"><code>Promise.filter</code></a></td><td><code>filter</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#mapfunction-mapper---promise"><code>.map</code></a> and <a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promisemaparraydynamicpromise-values-function-mapper---promise"><code>Promise.map</code></a></td><td><code>map</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#reducefunction-reducer--dynamic-initialvalue---promise"><code>.reduce</code></a> and <a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promisereducearraydynamicpromise-values-function-reducer--dynamic-initialvalue---promise"><code>Promise.reduce</code></a></td><td><code>reduce</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#props---promise"><code>.props</code></a> and <a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promisepropsobjectpromise-object---promise"><code>Promise.props</code></a></td><td><code>props</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#settle---promise"><code>.settle</code></a> and <a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promisesettlearraydynamicpromise-values---promise"><code>Promise.settle</code></a></td><td><code>settle</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#someint-count---promise"><code>.some</code></a> and <a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promisesomearraydynamicpromise-values-int-count---promise"><code>Promise.some</code></a></td><td><code>some</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#nodeifyfunction-callback---promise"><code>.nodeify</code></a></td><td><code>nodeify</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promisecoroutinegeneratorfunction-generatorfunction---function"><code>Promise.coroutine</code></a> and <a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promisespawngeneratorfunction-generatorfunction---promise"><code>Promise.spawn</code></a></td><td><code>generators</code></td></tr>
<tr><td><a href="#complex-thenables">Complex thenables</a></td><td><code>simple_thenables</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#progression">Progression</a></td><td><code>progress</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#promisification">Promisification</a></td><td><code>promisify</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#cancellation">Cancellation</a></td><td><code>cancel</code></td></tr>
<tr><td><a href="https://github.com/petkaantonov/bluebird/blob/master/API.md#synchronous-inspection">Synchronous inspection</a></td><td><code>synchronous_inspection</code></td></tr>
</tbody>
The following features can be disabledFeature(s) | Command line identifier |
---|
Make sure you have cloned the repo somewhere and did npm install
successfully.
After that you can run:
grunt build --features="core simple_thenables"
The above builds the most minimal build you can get. You can add more features separated by spaces from the above list:
grunt build --features="core simple_thenables filter map reduce"
The custom build file will be found from /js/browser/bluebird.js
. It will have a comment that lists the disabled and enabled features.
Note that the build leaves the /js/main
etc folders with same features so if you use the folder for node.js at the same time, don't forget to build
a full version afterwards (after having taken a copy of the bluebird.js somewhere):
grunt build
####Complex thenables
In order to provide smooth interoperability experience, Promises/A+ requires supporting "thenables" which are promise-like objects but not trusted bluebird promises.
For example this should work:
bluebirdPromise.then(function(){
return $.get("/file.php");
});
Even though the handler returns a jQuery promise, it should work as if it returned a real bluebird promise, that is, the next .then()
will wait until the ajax
request is complete.
However the specification in A+ 2.x.x requires handling of many theoretical edge cases that will never be seen in practice, such as:
- Trying to retrieve the
.then
property from object to see if it's a function might throw. - Retrieving
.then
property multiple times from an object might return different result every time, or might be deleted after some time - Calling the
.then
property of an object before necessary (just in time thenables) might cause problems - etc.
What you want in a browser is pretty much that the return $.get
line works. Can you imagine jQuery defining a getter on .then
property that throws?
Handling such cases requires a lot of code in bluebird. You can use the simple_thenables
feature which matches what other libraries such as Q are doing.
##What is the sync build?
You may now use sync build by:
var Promise = require("bluebird/zalgo");
The sync build is provided to see how forced asynchronity affects benchmarks. It should not be used in real code due to the implied hazards.
The normal async build gives Promises/A+ guarantees about asynchronous resolution of promises. Some people think this affects performance or just plain love their code having a possibility
of stack overflow errors and non-deterministic behavior.
The sync build skips the async call trampoline completely, e.g code like:
async.invoke( this.fn, this, val );
Appears as this in the sync build:
this.fn(val);
This should pressure the CPU slightly less and thus the sync build should perform better. Indeed it does, but only marginally. The biggest performance boosts are from writing efficient Javascript, not from compromising determinism.
Note that while some benchmarks are waiting for the next event tick, the CPU is actually not in use during that time. So the resulting benchmark result is not completely accurate because on node.js you only care about how much the CPU is taxed. Any time spent on CPU is time the whole process (or server) is paralyzed. And it is not graceful like it would be with threads.
var cache = new Map();
function getResult(url) {
var resolver = Promise.pending();
if (cache.has(url)) {
resolver.fulfill(cache.get(url));
}
else {
http.get(url, function(err, content) {
if (err) resolver.reject(err);
else {
cache.set(url, content);
resolver.fulfill(content);
}
});
}
return resolver.promise;
}
function guessWhatItPrints( url ) {
var i = 3;
getResult(url).then(function(){
i = 4;
});
console.log(i);
}
#Optimization guide
todo
#License
Copyright (c) 2013 Petka Antonov
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.