Bluebird JavaScript Library – BbPromise Complete Guide

Hello friends, in this tutorial, we will learn about the Bluebird (BbPromise) javascript library with the help of some examples of functions.

Bluebird.js is a very popular javascript library to handle promises. Bluebird is a replacement for native javascript promise because it is a fully featured promises library with great performance.

Bluebird has lots of advanced features that do not come with native javascript promises. Its features like promisification, cancellation, iteration methods, etc.

Let’s see what is promise and why BbPromise better than a native promise.

What is Promise?

A Promise is an object that may return a single value. The value could be fulfilled state or failure state of the reason for not resolved (e.g. a syntax error).

A Promise has 3 states fulfilled, rejected, and pending. The fulfilled state is when the promise is resolved and the rejected state is when the promise is rejected and the pending state is when the promise is in progress.

You can also give the callback functions in Promise to handle the fulfilled state or rejected state. So when the promise is resolved or rejected the callback functions will trigger.

Why Bluebird Promise?

To handle the promises base operation, there are many third-party libraries for javascript. Even the new version of browsers and nodejs also has a standard library that contains a promise implementation.

So here we will see some points why you should use Bluebird (BbPromise) javascript library instead of native promise or any other third-party libraries.

Easy to handle asynchronous operation: using the bluebird js library, you can handle the asynchronous operation in a very easy way. You can also pass a callback function in the bluebird promise operation.

Easy to debug: bluebird give you long stack traces along with the basic warnings and this helps you to recognize the errors. It does not swallow the unhandled errors when you forget to declare the .catch().

Promisification: this is the strongest feature of a bluebird to allow “promisify” the other node modules in order to use them asynchronously. It means that it can convert the whole package to a promise-based operation.

Concurrency coordination: It gives you power to define the concurrency in iteration methods like .map() method. Concurrency means you can set the limit of threads in the loop.

Cancellation operation: bluebird allows the cancellation feature to cancel the promise operation to avoid throwing errors when the user is away (navigate to another page) when an operation is in progress.

Install and Import Bluebird

To install the Bluebird javascript library using the script, you have to add the following script tag to your project’s head tag and then you can use it.

<script src="//cdn.jsdelivr.net/npm/bluebird@3.7.2/js/browser/bluebird.min.js"></script>

var Bluebird = Promise.noConflict();

To install the Bluebird javascript library in your React or NodeJS project, you have to install this pacakge using the npm and then you can import it as a BbPromise constant into your project.

npm install bluebird

// NodeJS
const BbPromise = require("bluebird");

//ReactJS
import { BbPromise } from "bluebird";

Bluebird Promise Functions

Let’s now see some most commonly used functions of Bluebird with the help of examples and how they work. It has many functions for different purposes, you can check here.

BbPromise.all()

Syntax:

BbPromise.all(Iterable)

The BbPromise.all() method is useful when we want to call multiple promises at the same time and wait for them to complete all. The fulfilled promises value will be on respective position to same as the original array.

If any promise in the array rejects then the whole operation will be rejected and show a rejection reason. It doesn’t matter which array of promise position failed, it only sees that the promise is failed then stop the further execution and throw the rejection message.

BbPromise.all() Fulfilled

BbPromise.all() Rejected

BbPromise.map()

Syntax:

BbPromise.map(Iterable, function, { concurrency })

The BbPromise.map() function is very useful. It iterates all over the promises and map the array into another array using the given mapper function.

The returned promises don’t fulfill until all the promises are fulfilled as well. Because this method has a very good feature “concurrency” to wait for the mapper function all promises are fulfilled.

Using concurrency, you can set the limit of threads at one time to execute. If you have 2000 items in the array and then you can set the concurrency limit as 3 then the .map() method will go through the first 3 items. And it will wait to fulfill the promise and then take another 3 items.

BbPromise.race()

Syntax:

BbPromise.race(Iterable)

The BbPromise.race() method takes an array of promises and returns a new promise that is the value of fulfillment or reason of rejection as soon as the promise is rejected or fulfilled.

We used this method when we have to return the first occurrence of the promise either resolved or rejected. As we can also guess from the name of the function BbPromise.race() that all the promises have a race against each other and the winner will be one, either fulfilled or rejected.

BbPromise.race() Fulfilled

BbPromise.race() Rejected

BbPromise.any()

Syntax:

BbPromise.any(Iterable)

The BbPromise.any() method is used to return a single resolved promise. This means that if one of the promises is fulfilled then it will return the value of the promise immediately.

If any promises will reject then BbPromise.any() will ignore the rejected promises and will return the first single resolved promise. It will return the direct value of the promise instead of an array of 1 promise count.

BbPromise.any() Fulfilled

BbPromise.any() Rejected

BbPromise.some()

Syntax:

BbPromise.some(Iterable)

The BbPromise.some() method is the same as BbPromise.any() method, just the difference is the return value based on the count.

The BbPromise.some() method iterates over all the values and returns a promise that is fulfilled as soon as count promises are fulfilled in the array.

So then, we used this method when we want to return resolved promises based on the count value that we passed in the method.

BbPromise.some() Fulfilled

BbPromise.some() Rejected

BbPromise.finally()

Syntax:

.finally(handler)

The BbPromise.finally() method is used when we have to execute any other operation whether the promise is resolved or rejected. Or you can say that this method will trigger when the promise is settled.

Using this method, you can avoid the duplicate code in the .then() and .catch() methods, you can call directly the .finally() method and write that duplicate code once inside this method.

BbPromise.spread()

The .spread() method is same like .then() method, but the fulfilled value must be an array. In the promise chain, if we are using the .spread() method then it will also work if the returned values are promises.

For example, you can see in the above BbPromise.all() method. We used the .spread() method with .all() method because we have pass the array in the .all() method.

BbPromise.catch() and error()

Both methods .catch() and .error() are used in the promise chain to handle the errors.

The .catch() method handle all types of exceptions in the catch block. The .catch() method returns a promise and it only looks for the rejected case of promise.

Syntax:

.catch(handler)

The .error() method is the same as .catch() but instead of catching all the exceptions, it only throws the operational errors. It returns the instance of Error not the string for errors.

Syntax:

.error(function(e))

BbPromise.tap()

Syntax:

.tap(handler)

The BbPromise.tap() method is also the same as .then() except that the value that you pass in this method will be the same value for the next chain.

So we used this method when we have to do other stuff in the promise chain, so you can use the .tap() method into the .then() chain of promise without affecting the original chain.

p = new BbPromise()

p.then(...)
    .then(...)
        .tap(console.log)
             .then(...)
                 .then(...)

What is Promise Chaining?

Promise chaining means when we have to execute two or more asynchronous operations and the next operation is depend on the previous result value.

I will make example tutorials for each of the bluebird functions, accept the browser notification, so you don’t miss those tutorials.

See Also: JavaScript For Loop – With Examples