Bluebird is a promise library I’ve used for almost every project. I remember when I was learning promise a few years ago, it took me a while to understand it.
One day, I was searching for some related materials, I found Bluebird. I was wondering what’s the reason for using a third party library when Node.js already has native Promise support at that point? Well, it turns out there are plenty. Although some of its features can be achieved with today’s Node.js, bluebird still can give you a lot of benefits.
Performance is one of the reasons I choose Bluebird at the very beginning. It’s very performant since…forever?
However, thanks to V8, Node 10 can now provide faster promise performance as well.
The following are the benchmark results on my laptop. You can try it yourself:
1
2
3
| $ git clone https://github.com/petkaantonov/bluebird/
$ nvs use <node_version> # or nvm if you like
$ ./bench doxbee # or ./bench parallel depends on what you want to test
|
Node 10.16.0 doxbee
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
| file time(ms) memory(MB)
callbacks-baseline.js 132 24.89
callbacks-suguru03-neo-async-waterfall.js 159 40.16
callbacks-caolan-async-waterfall.js 203 45.71
promises-bluebird-generator.js 211 35.49
promises-bluebird.js 245 45.41
promises-cujojs-when.js 306 61.96
generators-tj-co.js 323 60.97
promises-lvivski-davy.js 389 85.11
promises-native-async-await.js 405 67.00
promises-then-promise.js 444 68.84
promises-calvinmetcalf-lie.js 489 125.57
promises-tildeio-rsvp.js 538 77.93
promises-dfilatov-vow.js 560 128.28
promises-ecmascript6-native.js 594 79.71
streamline-generators.js 799 89.75
observables-pozadi-kefir.js 856 155.93
promises-obvious-kew.js 882 107.42
promises-medikoo-deferred.js 900 136.11
streamline-callbacks.js 1350 106.45
observables-Reactive-Extensions-RxJS.js 1357 226.14
observables-caolan-highland.js 3467 473.56
promises-kriskowal-q.js 5242 289.95
observables-baconjs-bacon.js.js 5811 551.76
Platform info:
Darwin 18.6.0 x64
Node.JS 10.16.0
V8 6.8.275.32-node.52
Intel(R) Core(TM) i5-7360U CPU @ 2.30GHz × 4
|
Node 10.16.0 Parallel
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
| file time(ms) memory(MB)
callbacks-baseline.js 290 84.93
callbacks-suguru03-neo-async-parallel.js 361 84.98
callbacks-caolan-async-parallel.js 450 113.71
promises-bluebird.js 454 104.64
promises-bluebird-generator.js 480 97.86
promises-lvivski-davy.js 578 159.97
promises-cujojs-when.js 668 170.84
generators-tj-co.js 998 240.93
promises-native-async-await.js 1030 231.30
promises-ecmascript6-native.js 1072 223.22
promises-tildeio-rsvp.js 1282 329.29
promises-then-promise.js 1373 288.88
promises-medikoo-deferred.js 1643 357.35
promises-calvinmetcalf-lie.js 1924 371.12
promises-dfilatov-vow.js 2483 535.41
promises-obvious-kew.js 3352 552.88
streamline-generators.js 6911 780.16
streamline-callbacks.js 11767 1134.09
Platform info:
Darwin 18.6.0 x64
Node.JS 10.16.0
V8 6.8.275.32-node.52
Intel(R) Core(TM) i5-7360U CPU @ 2.30GHz × 4
|
Useful APIs
Promise.map is something like Promise.all but more concise and has the capability of currency control.
Let’s take a look at the examples:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| const Promise = require("bluebird");
const getNameAfter5Seconds = name => {
return new Promise(resolve => {
setTimeout(() => {
resolve(`Name: ${name} (${new Date})`)
}, 5 * 1000);
});
};
(async () => {
const names = [ "John Doe", "Jane Doe", "Anonymous" ];
const tasks = names.map(getNameAfter5Seconds);
const results = await Promise.all(tasks);
results.forEach(r => console.log(r));
})();
|
And the output will be:
1
2
3
| Name: John Doe (Sun Jul 21 2019 17:04:37 GMT+0800 (GMT+08:00))
Name: Jane Doe (Sun Jul 21 2019 17:04:37 GMT+0800 (GMT+08:00))
Name: Anonymous (Sun Jul 21 2019 17:04:37 GMT+0800 (GMT+08:00))
|
You see, normally when we use Promise.all we would need an array of promises first. It’s not painful but still an extra step.
With Promise.map you can achieve the same by:
1
2
3
4
5
| (async () => {
const names = [ "John Doe", "Jane Doe", "Anonymous" ];
const results = await Promise.map(names, getNameAfter5Seconds);
results.forEach(r => console.log(r));
})();
|
Additionally, you can even chain it:
1
2
3
4
5
6
7
8
| (async () => {
const names = [ "John Doe", "Jane Doe", "Anonymous" ];
return Promise.map(names, getNameAfter5Seconds) // or use Promise.all here
.map(r => {
console.log(r);
return r;
})
})();
|
By chaining this you are just using the previously resolved results as input of Promise.map.
Last, let’s take a look at the currency control of Promise.map, which can’t be achieved with Promise.all.
It’s very straightforward, that means there won’t be more than the number of promises you specified running at the same time.
1
2
3
4
5
6
7
8
| (async () => {
const names = [ "John Doe", "Jane Doe", "Anonymous" ];
return Promise.map(names, getNameAfter5Seconds, { concurrency: 2 })
.map(r => {
console.log(r);
return r;
})
})();
|
And the output is, yes, just like you expected:
1
2
3
| Name: John Doe (Sun Jul 21 2019 17:20:04 GMT+0800 (GMT+08:00))
Name: Jane Doe (Sun Jul 21 2019 17:20:04 GMT+0800 (GMT+08:00))
Name: Anonymous (Sun Jul 21 2019 17:20:09 GMT+0800 (GMT+08:00))
|
It’s useful when you are doing something that might go wrong if the speed is too fast, like sending a bunch of HTTP requests. You can also combine this with a rate limit mechanism to properly manage your speed control.
When we looked at this example:
1
2
3
4
5
6
7
8
| (async () => {
const names = [ "John Doe", "Jane Doe", "Anonymous" ];
return Promise.map(names, getNameAfter5Seconds, { concurrency: 2 })
.map(r => {
console.log(r);
return r;
})
})();
|
Don’t you think it’s really redundant to just print something?
Yes, apparently everyone thinks so.
What if we want to take a look what’ was returned without taking the risk of forgetting to pass it back?
1
2
3
| Promise.resolve(1000)
.then(n => console.log(`The value is: ${n}`)); // We didn't return anything!
.then(number => console.log(`I got: ${number}`)); // number is now undefined
|
That’s where .tap can be useful. We can literally “tap” on the promise without worrying about forgetting to return value.
1
2
3
| Promise.resolve(1000)
.tap(n => console.log(`The value is: ${n}`)); // We didn't return anything!
.then(number => console.log(`I got: ${number}`)); // number is 1000
|
You might wonder, what if we return something else in the .tap’s callback?
1
2
3
| Promise.resolve(1000)
.tap(() => 2000)
.then(number => console.log(`I got: ${number}`)); // number is still 1000
|
Of course, you can do anything shady with .tap if you like. But most of the time you might just want to print something, you can use a simple technique like:
1
2
3
| Promise.resolve(1000)
.then(n => console.log(n) || n)
.then(number => console.log(`I got: ${number}`)); // number is still 1000
|
Or, just use VSCode’s logpoint?
We often deal with objects with one-liners, like:
1
2
| Promise.resolve([ 1, 2 ,3 ,4 ,5 ])
.then(arr => arr.sort((a, b) => b - a));
|
While can be done with:
1
2
| Promise.resolve([ 1, 2 ,3 ,4 ,5 ])
.call("sort", (a, b) => b - a);
|
For more examples, see .call.
When we do something to a collection, we need to make sure when some of them got rejected, the remaining promises won’t be affected.
1
2
3
4
5
6
7
8
9
10
11
| const Promise = require("bluebird");
const rejectOnEven = number => new Promise((resolve, reject) => {
return number % 2 !== 0? resolve(number) : reject(`${number} is rejected because it's even`);
});
(async () => {
const tasks = [ 1, 2, 3 ,4 ].map(rejectOnEven);
const results = await Promise.all(tasks);
console.log(results);
})()
|
And the output will be:
1
2
3
| (node:66335) UnhandledPromiseRejectionWarning: 2
(node:66335) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:66335) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.
|
As you expected, the remaining promises won’t have the chance to finish. Of course, we can handle it in the rejectOnEven function, but can we deal with these later, and just let all promises settled?
If you are using Q, there is an .allSettled for you.
As for bluebird, we have .reflect.
Let’s modify the example:
1
2
3
4
5
6
7
8
9
10
11
| (async () => {
const tasks = [ 1, 2, 3 ,4 ].map(rejectOnEven);
const results = await Promise.all(tasks.map(t => t.reflect()));
results.forEach(r => {
if (r.isFulfilled()) {
console.log(`Resolved value: ${r.value()}`);
} else {
console.log(`Rejected reason: ${r.reason()}`);
}
})
})();
|
And the output:
1
2
3
4
| Resolved value: 1
Rejected reason: 2 is rejected because it's even
Resolved value: 3
Rejected reason: 4 is rejected because it's even
|
One thing to notice is, it seems you can’t replace the Promise.all here with Promise.map.
…and others
The examples above are just something I used frequently. There are more. I believe you will find others useful as well.
When your dependencies are still using callback style, you can easily transform it to promise-based style
For example:
1
2
| const Promise = require("bluebird");
const fs = Promise.promisifyAll(require("fs"));
|
Then you have something like fs.readFileAsync, fs.writeFileAsync now! You can also change the Async postfix if you are not satisfied.
You can then change your code from
1
2
3
| fs.readFile("/path/to/somefile", (err, data) => {
// ...
})
|
to:
1
2
3
4
5
6
7
8
9
10
11
| fs.readFileAsync("/path/to/somefile")
.then(/*...*/)
.catch(/*...*/)
//or
try {
const data = await fs.readFileAsync("/path/to/somefile");
// ...
} catch (e) {
// ...
}
|
If you are using Node version >= 8, you can have promisify from core module util. See util.promisify.
Developer-friendly
How is bluebird more developer-friendly than others? To explain this, I strongly encourage you to read this excellent blog post: We have a problem with promises.
Plug into other libraries
AWS SDK
1
2
3
| const AWS = require("aws-sdk");
const Promise = require("bluebird");
AWS.config.setPromisesDependency(Promise);
|
IOREDIS
1
2
3
| const Redis = require("ioredis");
const Promise = require("bluebird");
Redis.Promise = Promise;
|
In-place Q replacement
If you are using Q 1.x as promise library and still want to give bluebird a try, check bluebird-q.
W.T. Chang
included in dev