<commit_before><a href="http://promisesaplus.com/">
    <img src="http://promisesaplus.com/assets/logo-small.png" alt="Promises/A+ logo"
         title="Promises/A+ 1.0 compliant" align="right" />
</a>

#Introduction

Bluebird is a full featured [promise](#what-are-promises-and-why-should-i-use-them) library with unmatched performance.

Features:

- [Promises A+ 3.x.x](https://github.com/promises-aplus/promises-spec)
- [Promises A+ 2.x.x](https://github.com/domenic/promises-unwrapping)
- [Cancellation](https://github.com/promises-aplus)
- [Progression](https://github.com/promises-aplus/progress-spec)
- [Synchronous inspection](https://github.com/promises-aplus/synchronous-inspection-spec)
- All, any, some, settle, map, reduce, spread, join...
- [Unhandled rejections and long, relevant stack traces](#error-handling)
- [Sick performance](https://github.com/petkaantonov/bluebird/tree/master/benchmark/stats)

Passes [AP2](https://github.com/petkaantonov/bluebird/tree/master/test/mocha), [AP3](https://github.com/petkaantonov/bluebird/tree/master/test/mocha), [Cancellation](https://github.com/petkaantonov/bluebird/blob/master/test/mocha/cancel.js), [Progress](https://github.com/petkaantonov/bluebird/blob/master/test/mocha/q_progress.js), [promises_unwrapping](https://github.com/petkaantonov/bluebird/blob/master/test/mocha/promises_unwrapping.js) (Just in time thenables), [Q](https://github.com/petkaantonov/bluebird/tree/master/test/mocha) and [When.js](https://github.com/petkaantonov/bluebird/tree/master/test) tests. See [testing](#testing).

#Topics

- [Quick start](#quick-start)
- [API Reference and examples](https://github.com/petkaantonov/bluebird/blob/master/API.md)
- [What are promises and why should I use them?](#what-are-promises-and-why-should-i-use-them)
- [Error handling](#error-handling)
- [Development](#development)
    - [Testing](#testing)
    - [Benchmarking](#benchmarks)
- [What is the sync build?](#what-is-the-sync-build)
- [License](#license)
- [Snippets for common problems](https://github.com/petkaantonov/bluebird/wiki/Snippets)
- [Promise anti-patterns](https://github.com/petkaantonov/bluebird/wiki/Promise-anti-patterns)
- [Changelog](https://github.com/petkaantonov/bluebird/blob/master/changelog.md)

#Quick start

##Node.js

    npm install bluebird


Then:

```js
var Promise = require("bluebird");
```

If you want to ensure you get your own fresh copy of bluebird, do instead:

```js
                                        //Note the extra function call
var Promise = require("bluebird/js/main/promise")();
```

##Browsers

Download the [bluebird.js](https://github.com/petkaantonov/bluebird/tree/master/js/browser) file. And then use a script tag:

```html
<script type="text/javascript" src="/scripts/bluebird.js"></script>
```

The global variable `Promise` becomes available after the above script tag.

After quick start, see [API Reference and examples](https://github.com/petkaantonov/bluebird/blob/master/API.md)

###Browser support

Browsers that [implement ECMA-262, edition 5](http://en.wikipedia.org/wiki/Ecmascript#Implementations) and later are supported.

IE8 (ECMAS-262, edition 3) is supported if you include [es5-shim.js](https://github.com/kriskowal/es5-shim/blob/master/es5-shim.js) and [es5-sham.js](https://github.com/kriskowal/es5-shim/blob/master/es5-sham.js).

#What are promises and why should I use them?

You should use promises to turn this:

```js
readFile("file.json", function(err, val) {
    if( err ) {
        console.error("unable to read file");
    }
    else {
        try {
            val = JSON.parse(val);
            console.log(val.success);
        }
        catch( e ) {
            console.error("invalid json in file");
        }
    }
});
```

Into this:

```js
readFile("file.json").then(JSON.parse).then(function(val) {
    console.log(val.success);
})
.catch(SyntaxError, function(e) {
    console.error("invalid json in file");
})
.catch(function(e){
    console.error("unable to read file")
});
```

Actually you might notice the latter has a lot of in common with code that would do the same using synchronous I/O:

```js
try {
    var val = JSON.parse(readFile("file.json"));
    console.log(val.success);
}
//Syntax actually not supported in JS but drives the point
catch(SyntaxError e) {
    console.error("invalid json in file");
}
catch(Error e) {
    console.error("unable to read file")
}
```

And that is the point - being able to have something that is a lot like `return` and `throw` in synchronous code.

You can also use promises to improve code that was written with callback helpers:


```js
//Copyright Plato http://stackoverflow.com/a/19385911/995876
//CC BY-SA 2.5
mapSeries(URLs, function (URL, done) {
    var options = {};
    needle.get(URL, options, function (error, response, body) {
        if (error) {
            return done(error)
        }
        try {
            var ret = JSON.parse(body);
            return done(null, ret);
        }
        catch (e) {
            done(e);
        }
    });
}, function (err, results) {
    if (err) {
        console.log(err)
    } else {
        console.log('All Needle requests successful');
        // results is a 1 to 1 mapping in order of URLs > needle.body
        processAndSaveAllInDB(results, function (err) {
            if (err) {
                return done(err)
            }
            console.log('All Needle requests saved');
            done(null);
        });
    }
});
```

Is more pleasant to the eys when done with promises:

```js
Promise.promisifyAll(needle);
var options = {};

var current = Promise.fulfilled();
Promise.map(URLs, function(URL) {
    current = current.then(function () {
        return needle.getAsync(URL, options);
    });
    return current;<commit_msg>typos<commit_after><a href="http://promisesaplus.com/">
    <img src="http://promisesaplus.com/assets/logo-small.png" alt="Promises/A+ logo"
         title="Promises/A+ 1.0 compliant" align="right" />
</a>

#Introduction

Bluebird is a full featured [promise](#what-are-promises-and-why-should-i-use-them) library with unmatched performance.

Features:

- [Promises A+ 3.x.x](https://github.com/promises-aplus/promises-spec)
- [Promises A+ 2.x.x](https://github.com/domenic/promises-unwrapping)
- [Cancellation](https://github.com/promises-aplus)
- [Progression](https://github.com/promises-aplus/progress-spec)
- [Synchronous inspection](https://github.com/promises-aplus/synchronous-inspection-spec)
- All, any, some, settle, map, reduce, spread, join...
- [Unhandled rejections and long, relevant stack traces](#error-handling)
- [Sick performance](https://github.com/petkaantonov/bluebird/tree/master/benchmark/stats)

Passes [AP2](https://github.com/petkaantonov/bluebird/tree/master/test/mocha), [AP3](https://github.com/petkaantonov/bluebird/tree/master/test/mocha), [Cancellation](https://github.com/petkaantonov/bluebird/blob/master/test/mocha/cancel.js), [Progress](https://github.com/petkaantonov/bluebird/blob/master/test/mocha/q_progress.js), [promises_unwrapping](https://github.com/petkaantonov/bluebird/blob/master/test/mocha/promises_unwrapping.js) (Just in time thenables), [Q](https://github.com/petkaantonov/bluebird/tree/master/test/mocha) and [When.js](https://github.com/petkaantonov/bluebird/tree/master/test) tests. See [testing](#testing).

#Topics

- [Quick start](#quick-start)
- [API Reference and examples](https://github.com/petkaantonov/bluebird/blob/master/API.md)
- [What are promises and why should I use them?](#what-are-promises-and-why-should-i-use-them)
- [Error handling](#error-handling)
- [Development](#development)
    - [Testing](#testing)
    - [Benchmarking](#benchmarks)
- [What is the sync build?](#what-is-the-sync-build)
- [License](#license)
- [Snippets for common problems](https://github.com/petkaantonov/bluebird/wiki/Snippets)
- [Promise anti-patterns](https://github.com/petkaantonov/bluebird/wiki/Promise-anti-patterns)
- [Changelog](https://github.com/petkaantonov/bluebird/blob/master/changelog.md)

#Quick start

##Node.js

    npm install bluebird


Then:

```js
var Promise = require("bluebird");
```

If you want to ensure you get your own fresh copy of bluebird, do instead:

```js
                                        //Note the extra function call
var Promise = require("bluebird/js/main/promise")();
```

##Browsers

Download the [bluebird.js](https://github.com/petkaantonov/bluebird/tree/master/js/browser) file. And then use a script tag:

```html
<script type="text/javascript" src="/scripts/bluebird.js"></script>
```

The global variable `Promise` becomes available after the above script tag.

After quick start, see [API Reference and examples](https://github.com/petkaantonov/bluebird/blob/master/API.md)

###Browser support

Browsers that [implement ECMA-262, edition 5](http://en.wikipedia.org/wiki/Ecmascript#Implementations) and later are supported.

IE8 (ECMAS-262, edition 3) is supported if you include [es5-shim.js](https://github.com/kriskowal/es5-shim/blob/master/es5-shim.js) and [es5-sham.js](https://github.com/kriskowal/es5-shim/blob/master/es5-sham.js).

#What are promises and why should I use them?

You should use promises to turn this:

```js
readFile("file.json", function(err, val) {
    if( err ) {
        console.error("unable to read file");
    }
    else {
        try {
            val = JSON.parse(val);
            console.log(val.success);
        }
        catch( e ) {
            console.error("invalid json in file");
        }
    }
});
```

Into this:

```js
readFile("file.json").then(JSON.parse).then(function(val) {
    console.log(val.success);
})
.catch(SyntaxError, function(e) {
    console.error("invalid json in file");
})
.catch(function(e){
    console.error("unable to read file")
});
```

Actually you might notice the latter has a lot in common with code that would do the same using synchronous I/O:

```js
try {
    var val = JSON.parse(readFile("file.json"));
    console.log(val.success);
}
//Syntax actually not supported in JS but drives the point
catch(SyntaxError e) {
    console.error("invalid json in file");
}
catch(Error e) {
    console.error("unable to read file")
}
```

And that is the point - being able to have something that is a lot like `return` and `throw` in synchronous code.

You can also use promises to improve code that was written with callback helpers:


```js
//Copyright Plato http://stackoverflow.com/a/19385911/995876
//CC BY-SA 2.5
mapSeries(URLs, function (URL, done) {
    var options = {};
    needle.get(URL, options, function (error, response, body) {
        if (error) {
            return done(error)
        }
        try {
            var ret = JSON.parse(body);
            return done(null, ret);
        }
        catch (e) {
            done(e);
        }
    });
}, function (err, results) {
    if (err) {
        console.log(err)
    } else {
        console.log('All Needle requests successful');
        // results is a 1 to 1 mapping in order of URLs > needle.body
        processAndSaveAllInDB(results, function (err) {
            if (err) {
                return done(err)
            }
            console.log('All Needle requests saved');
            done(null);
        });
    }
});
```

Is more pleasing to the eye when done with promises:

```js
Promise.promisifyAll(needle);
var options = {};

var current = Promise.fulfilled();
Promise.map(URLs, function(URL) {
    current = current.then(function () {
        return needle.getAsync(URL, options);
    });
    return current;
{'fraction_non_alphanumeric': 0.15171697950004326, 'fraction_numerical': 0.006746821209237955, 'mean_word_length': 3.3995433789954337, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 15, 'https://': 42, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2783684', 'n_tokens_mistral': 3865, 'n_tokens_neox': 3712, 'n_words': 848}