Socket
Socket
Sign inDemoInstall

bluebird

Package Overview
Dependencies
2
Maintainers
1
Versions
223
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

    bluebird

Full featured Promises/A+ implementation with exceptionally good performance


Version published
Maintainers
1
Install size
9.71 MB
Created

Package description

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

Readme

Source

#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.

API Reference and examples

#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.

Install node, npm, and grunt.

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.

Keywords

FAQs

Last updated on 24 Sep 2013

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.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc