bluebird

What is bluebird?

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.

What are bluebird's main functionalities?

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

Other packages similar to bluebird

q

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

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

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.

promise

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

Got a question? Join us on stackoverflow, the mailing list or chat on IRC

Introduction

Bluebird is a fully featured promise library with focus on innovative features and performance

See the bluebird website for further documentation, references and instructions. See the API reference here.

For bluebird 2.x documentation and files, see the 2.x tree.

Note

Promises in Node.js 10 are significantly faster than before. Bluebird still includes a lot of features like cancellation, iteration methods and warnings that native promises don't. If you are using Bluebird for performance rather than for those - please consider giving native promises a shot and running the benchmarks yourself.

Questions and issues

The github issue tracker is only for bug reports and feature requests. Anything else, such as questions for help in using the library, should be posted in StackOverflow under tags promise and bluebird.

Thanks

Thanks to BrowserStack for providing us with a free account which lets us support old browsers like IE8.

License

The MIT License (MIT)

Copyright (c) 2013-2019 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.