bluebird
Advanced tools
Package description
Bluebird is a fully-featured Promise library for JavaScript. It allows for advanced features such as promise chaining, concurrency control, and error handling. It is known for its performance and useful utilities for working with asynchronous operations in JavaScript.
Promisification
Converts Node.js callback-style functions to return a Bluebird promise. In this example, the 'fs' module's 'readFile' function is promisified to use promises instead of callbacks.
const Promise = require('bluebird');
const fs = Promise.promisifyAll(require('fs'));
fs.readFileAsync('example.txt', 'utf8').then(contents => {
console.log(contents);
}).catch(error => {
console.error('Error reading file', error);
});Promise Chaining
Allows for chaining multiple asynchronous operations where each step waits for the previous one to complete. Errors can be caught and handled gracefully.
const Promise = require('bluebird');
Promise.resolve(1)
.then(x => x + 1)
.then(x => { throw new Error('Something went wrong'); })
.catch(Error, e => console.error(e.message));Concurrency Control
Provides utilities to control the concurrency of multiple promises. The 'map' function here runs a maximum of two promises in parallel.
const Promise = require('bluebird');
const tasks = [/* array of functions that return promises */];
Promise.map(tasks, task => task(), { concurrency: 2 })
.then(results => {
console.log('All tasks completed', results);
});Error Handling
Offers a clean syntax for error handling in promise chains. The 'try' method is used to start a promise chain with error handling.
const Promise = require('bluebird');
Promise.try(() => {
throw new Error('Something failed');
}).catch(Error, e => {
console.error('Caught an error:', e.message);
});Q is an earlier promise library that provides similar features to Bluebird, such as promise creation, chaining, and advanced error handling. However, Bluebird is generally considered to be faster and more feature-rich.
When.js is another promise library with API methods for creating and working with promises. It is smaller and has a simpler API compared to Bluebird, but lacks some of the utilities and performance optimizations.
ES6-Promise is a polyfill for the ES6 Promise specification. It provides basic promise functionality but does not include the additional utilities and features that Bluebird offers.
This package is a simple implementation of Promises/A+. It is lightweight and doesn't have the extra features that Bluebird provides, focusing instead on a minimal API.
Readme
#Introduction
Bluebird is a full featured promise library with unmatched performance.
Features:
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");
##Browsers
Download the bluebird_debug.js file. And then use a script tag:
<script type="text/javascript" src="/scripts/bluebird_debug.js"></script>
The global variable Promise becomes available after the above script tag. The debug file has long stack traces and assertions enabled, which degrade performance substantially but not enough to matter for anything you could do with promises on the browser.
After quick start, see API Reference and examples
#What are promises and why should I use them?
You should use promises to make robust asynchronous programming a joy.
More info:
#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 done, 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. I will probably add a done method if it turns out people actually need to do this.
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. 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.
#Development
For development tasks such as running benchmarks or testing, you need to clone the repository and install dev-dependencies.
git clone git@github.com:petkaantonov/bluebird.git
cd bluebird
npm install
##Testing
To run all tests, run grunt test. Note that new process is created for each test file, which means 40 processes as of now. 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.
##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:
grunt bench --run=spion
The competing modules can be updated by:
cd benchmark/async-compare
npm update
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.
grunt bench --run=cujojs
The other benchmarks included are broken and misleading, I will remove them.
##What is the sync build?
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 deternism.
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(); //ES6 Map or DataStructures/Map or whatever...
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;
}
//The result of console.log is truly random without async guarantees
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.
FAQs
Full featured Promises/A+ implementation with exceptionally good performance
The npm package bluebird receives a total of 21,069,837 weekly downloads. As such, bluebird popularity was classified as popular.
We found that bluebird demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).
Security News
LDAPjs, an LDAP Client and Server API for Node.js, was decommissioned after its maintainer received an abusive email from a user, raising concerns about this form of abuse as a potential attack vector.
Security News
CISA launched a new project called Vulnrichment to enrich CVEs with details that help prioritize patching and mitigation efforts, as the NVD backlog of unenriched CVEs awaiting analysis surpasses 10,000.