No dependencies listed.
|2.3.6||9 months ago||esailija|
|2.3.5||9 months ago||esailija|
|2.3.4||9 months ago||esailija|
|2.3.3||9 months ago||esailija|
|2.3.2||10 months ago||esailija|
|2.3.1||10 months ago||esailija|
|2.3.0||a year ago||esailija|
|2.2.2||a year ago||esailija|
|2.2.1||a year ago||esailija|
|2.2.0||a year ago||esailija|
|2.1.3||a year ago||esailija|
|2.1.2||a year ago||esailija|
|2.1.1||a year ago||esailija|
|2.0.7||a year ago||esailija|
|2.0.6||a year ago||esailija|
|2.0.5||a year ago||esailija|
|2.0.4||a year ago||esailija|
|2.0.3||a year ago||esailija|
|2.0.2||a year ago||esailija|
|1.2.4||a year ago||esailija|
|1.2.3||a year ago||esailija|
|1.2.2||a year ago||esailija|
|1.2.1||a year ago||esailija|
|1.2.0||a year ago||esailija|
|1.1.1||a year ago||esailija|
|1.1.0||a year ago||esailija|
|1.0.8||a year ago||esailija|
|1.0.7||a year ago||esailija|
|1.0.5||a year ago||esailija|
|1.0.4||a year ago||esailija|
|1.0.3||a year ago||esailija|
|1.0.2||a year ago||esailija|
|1.0.1||a year ago||esailija|
|1.0.0||a year ago||esailija|
|0.11.6||9 months ago||esailija|
|0.11.6-0||2 years ago||esailija|
|0.11.5-1||2 years ago||esailija|
|0.11.5-0||2 years ago||esailija|
|0.11.4-1||2 years ago||esailija|
|0.11.4-0||2 years ago||esailija|
|0.11.3-0||2 years ago||esailija|
|0.11.2-0||2 years ago||esailija|
|0.11.1-0||2 years ago||esailija|
|0.11.0-0||2 years ago||esailija|
|0.10.14-0||2 years ago||esailija|
|0.10.13-1||2 years ago||esailija|
|0.10.13-0||2 years ago||esailija|
|0.10.12-0||2 years ago||esailija|
|0.10.11-4||2 years ago||esailija|
|0.10.11-2||2 years ago||esailija|
|0.10.11-1||2 years ago||esailija|
|0.10.11-0||2 years ago||esailija|
|0.10.10-0||2 years ago||esailija|
|0.10.9-1||2 years ago||esailija|
|0.10.9-0||2 years ago||esailija|
|0.10.8-0||2 years ago||esailija|
|0.10.7-0||2 years ago||esailija|
|0.10.6-0||2 years ago||esailija|
|0.10.5-0||2 years ago||esailija|
|0.10.4-1||2 years ago||esailija|
|0.10.4-0||2 years ago||esailija|
|0.10.3-0||2 years ago||esailija|
|0.10.2-1||2 years ago||esailija|
|0.10.2-0||2 years ago||esailija|
|0.10.1-0||2 years ago||esailija|
|0.10.0-1||2 years ago||esailija|
|0.10.0-0||2 years ago||esailija|
|0.9.11-1||2 years ago||esailija|
|0.9.11-0||2 years ago||esailija|
|0.9.10-1||2 years ago||esailija|
|0.9.10-0||2 years ago||esailija|
|0.9.9-0||2 years ago||esailija|
|0.9.8-0||2 years ago||esailija|
|0.9.7-0||2 years ago||esailija|
|0.9.6-0||2 years ago||esailija|
|0.9.5-0||2 years ago||esailija|
|0.9.4-1||2 years ago||esailija|
|0.9.4-0||2 years ago||esailija|
|0.9.3-0||2 years ago||esailija|
|0.9.2-1||2 years ago||esailija|
|0.9.2-0||2 years ago||esailija|
|0.9.1-1||2 years ago||esailija|
|0.9.1-0||2 years ago||esailija|
|0.9.0-0||2 years ago||esailija|
|0.8.5-1||2 years ago||esailija|
|0.8.5-0||2 years ago||esailija|
|0.8.4-1||2 years ago||esailija|
|0.8.4-0||2 years ago||esailija|
|0.8.3-3||2 years ago||esailija|
|0.8.3-2||2 years ago||esailija|
|0.8.3-1||2 years ago||esailija|
|0.8.3-0||2 years ago||esailija|
|0.8.2-2||2 years ago||esailija|
|0.8.2-1||2 years ago||esailija|
|0.8.2-0||2 years ago||esailija|
|0.8.1-0||2 years ago||esailija|
|0.8.0-3||2 years ago||esailija|
|0.8.0-2||2 years ago||esailija|
|0.8.0-1||2 years ago||esailija|
|0.8.0-0||2 years ago||esailija|
|0.7.12-2||2 years ago||esailija|
|0.7.12-1||2 years ago||esailija|
|0.7.12-0||2 years ago||esailija|
|0.7.11-0||2 years ago||esailija|
|0.7.10-1||2 years ago||esailija|
|0.7.10-0||2 years ago||esailija|
|0.7.9-1||2 years ago||esailija|
|0.7.9-0||2 years ago||esailija|
|0.7.8-1||2 years ago||esailija|
|0.7.8-0||2 years ago||esailija|
|0.7.7-1||2 years ago||esailija|
|0.7.7-0||2 years ago||esailija|
|0.7.6-0||2 years ago||esailija|
|0.7.5-0||2 years ago||esailija|
|0.7.4-1||2 years ago||esailija|
|0.7.4-0||2 years ago||esailija|
|0.7.3-0||2 years ago||esailija|
|0.7.2-0||2 years ago||esailija|
|0.7.1-5||2 years ago||esailija|
|0.7.1-4||2 years ago||esailija|
|0.7.1-3||2 years ago||esailija|
|0.7.1-2||2 years ago||esailija|
|0.7.1-1||2 years ago||esailija|
Bluebird is a fully featured promise library with focus on innovative features and performance
- Quick start
- API Reference and examples
- What are promises and why should I use them?
- Questions and issues
- Error handling
- What is the sync build?
- Snippets for common problems
- Promise anti-patterns
- Optimization guide
- Promises A+
- Synchronous inspection
- Concurrency coordination
- Promisification on steroids
- Resource management through a parallel of python
- Cancellation and timeouts
- Parallel for C#
- Mind blowing utilities such as
- Practical debugging solutions and sane defaults
- Sick performance
Download the bluebird.js file. NOTE: bluebird also has a bower package.
And then use a script tag:
The global variables
P (alias for
Promise) become available after the above script tag.
A minimal bluebird browser build is ̃38.92KB minified*, 11.65KB gzipped and has no external dependencies.
*Google Closure Compiler using Simple.
Browsers that implement ECMA-262, edition 3 and later are supported.
IE7 and IE8 had to be removed from tests due to SauceLabs bug but are supported and pass all tests
Note that in ECMA-262, edition 3 (IE7, IE8 etc.) it is not possible to use methods that have keyword names like
.finally. The API documentation always lists a compatible alternative name that you can use if you need to support these browsers. For example
.catch is replaced with
Also, long stack trace support is only available in Chrome and Firefox.
Previously bluebird required es5-shim.js and es5-sham.js to support Edition 3 - these are no longer required as of 0.10.4.
After quick start, see API Reference and examples
- IRC: #promises @freenode
- StackOverflow: bluebird tag
- Bugs and feature requests: github issue tracker
What are promises and why should I use them?
You should use promises to turn this:
If you are wondering "there is no
readFileAsync method on
fs that returns a promise", see promisification
Actually you might notice the latter has a lot in common with code that would do the same using synchronous I/O:
And that is the point - being able to have something that is a lot like
throw in synchronous code.
You can also use promises to improve code that was written with callback helpers:
Is more pleasing to the eye when done with promises:
Also promises don't just give you correspondences for synchronous features but can also be used as limited event emitters or callback aggregators.
- Promise nuggets
- Why I am switching to promises
- What is the the point of promises
- Snippets for common problems
- Promise anti-patterns
Questions and issues
If you find a bug in bluebird or have a feature request, file an issue in the github issue tracker. Anything else, such as questions for help in using the library, should be posted in StackOverflow under tags
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:
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
console.error in browsers. This is close to what happens with synchronous code - your code doesn'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:
If you want to also enable long stack traces, call:
right after the library is loaded.
In node.js use the environment flag
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 already 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
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.
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:
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
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
.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
OperationalError (you can get a reference from
Promise.OperationalError). 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:
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
OperationalError instance will contain the original error in its
.cause property but it does have a direct copy of the
.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.
catch handler typed to
Promise.OperationalError is expected to be used very often, it has a neat shorthand:
See API documentation for
Finally, Bluebird also supports predicate-based filters. If you pass a predicate function instead of an error type, the predicate will receive the error as an argument. The return result 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 typesets with set operations and many other techniques can be implemented on top of them.
Example of using a predicate-based filter:
How do long stack traces differ from e.g. Q?
Bluebird attempts to have more elaborate traces. Consider:
You will see
A better and more practical example of the differences can be seen in gorgikosev's debuggability competition.
For development tasks such as running benchmarks or testing, you need to clone the repository and install dev-dependencies.
Install node, npm, and grunt.
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. If you want to run tests sequentially with all output, do:
You may also give a higher
--jobs value to run more tests concurrently (and finish faster).
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:
When trying to get a test to pass, run only that individual test file with
--verbose to see the output from that test:
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:
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.
To run a benchmark, run the given command for a benchmark 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.
1. DoxBee sequential
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.
2. Made-up parallel
This made-up scenario runs 15 shimmed queries in parallel.
Custom builds for browsers are supported through a command-line utility.
|Feature(s)||Command line identifier|
Make sure you have cloned the repo somewhere and did
npm install successfully.
After that you can run:
The above builds the most minimal build you can get. You can add more features separated by spaces from the above list:
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):
For library authors
Building a library that depends on bluebird? You should know about a few features.
If your library needs to do something obtrusive like adding or modifying methods on the
Promise prototype, uses long stack traces or uses a custom unhandled rejection handler then... that's totally ok as long as you don't use
require("bluebird"). Instead you should create a file
that creates an isolated copy. For example, creating a file called
bluebird-extended.js that contains:
Your library can then use
var Promise = require("bluebird-extended"); and do whatever it wants with it. Then if the application or other library uses their own bluebird promises they will all play well together because of Promises/A+ thenable assimilation magic.
You should also know about
.nodeify() which makes it easy to provide a dual callback/promise API.
What is the sync build?
You may now use sync build by:
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:
Appears as this in the sync build:
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.
Articles about optimization will be periodically posted in the wiki section, polishing edits are welcome.
A single cohesive guide compiled from the articles will probably be done eventually.
The MIT License (MIT)
Copyright (c) 2014 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.