Bluebird

Bluebird

相关链接

用bluebird实现更加强大的Promise
bluebird中常用的Promise API
官方API
bluebird与原生Promise对象及bluebird模块的中文API文档

Promise API

NodeJs中fs.readFile方法的基本使用方式：

const fs = require('fs'),
path = require('path');

fs.readFile(path.join(__dirname, 'sample.txt'), 'utf-8', (err, data) => {
    if(err){
        console.error(err);
    }else{
        console.log(data);
    }
});

1. Promise.promisifyAll

函数Promise化是指将一个不符合promise规范的API改造成返回promise的API。Bluebird 的 Promise.promisifyAll 方法可以为一个对象的属性中的所有方法创建一个对应的使用Promise的版本。这些新创建方法的名称在已有方法的名称后加上"Async"后缀。
使用 Bluebird的Promise.promisifyAll来转换上面的方法：

const Promise = require('bluebird')
fs = require('fs')
path = require('path')
Promise.promisifyAll(fs);
//新方法名后面加了‘Async’后缀， 返回一个Promise对象
fs.readFileAsync(path.join(__dirname, 'sample.txt'), 'utf-8')
  .then(data => console.log(data))
  .catch(err => console.error(err));

2. Promise.promisify

如果不希望把一个对象的所有方法都转换成使用Promise方式，可以使用Promise.promisify来转换单个方法,比如：

Promise.promisify(require("fs").readFile)

3. Promise.fromCallback

对于一个 NodeJS 格式的回调方法，可以使用 Promise.fromCallback 将其转换成一个 Promise。回调方法的结果决定了 Promise 的状态。

4. .spread

spread方法与then方法类似，当Promise的结果为数组时，可以使用spread方法把数组的元素打平(flatten)为回调方法的不同参数：

Promise.resolve([1,2,3])
  .spread((v1, v2, v3) => console.log(v1 + v2 + v3));

5. .catch

catch 方法用来添加已回绝状态时的回调方法，从.then()调用链中产生的任何异常都会被传送到最近的.catch()函数中。
两种使用方式：
捕获所有异常
只添加回调方法，会捕获所有的错误情况

.catch(e => {

})

捕获部分异常
使用错误对象类型或断言来对错误进行过滤

.then(() => {
    ...
}).catch(TypeError, e => {

}).catch(ReferenceError, e => {

}).catch(e => {

})

6. .error

error方法和catch类似，但是error只会处理真正的Error对象。Js中throw语句会抛出任何值，不一定是Error对象。throw抛出的任何值都会被catch处理，但是只有Error对象才会被error处理。

Promise.reject('not an error')
  .error(err => conosle.log('wrong la'))

7. .finally

无论promise调用链的情况如何，.finally都会在最后被调用。最后的返回值不能在句柄中被改变。

Promise.reject(new TypeError('type error'))
  .catch(TypeError, console.error)
  .finally(() => console.log('done'));

catch 只会捕获 TypeError，而 finally 中的逻辑始终会被调用

8. .bind

创建一个promise对象，这个对象与给定的thisArg绑定，对象内部的this将会指向被绑定的值。这个被绑定对象所产生的promise对象也会被绑定到thisArg。Example

9. 状态相关

对于一个Promise对象，可以使用如下方法查看其内部状态：

API	Promise状态
isPending	进行中
isFulfilled	已满足
isPending	已拒绝
isPending	已取消
value	获取Promise满足后的结果
reason	获取Promise被拒后的结果

可以使用 cancel 方法来取消一个 Promise，取消 Promise 只是表示 Promise 的回调方法不被调用，并不会自动取消正在进行的异步操作，取消功能默认是禁用的，需要使用 Promise.config 来启用该功能；如要添加自定义取消逻辑，Promise构造方法参数中可以添加onCancel参数，用来注册Promise取消时的回调方法：

Promise.config({
    cancellation: true
});
new Promise((resolve, reject, onCancel) => {
    //
    onCancel(() => {
        //
    });

}).then(console.log).cancel();

10. Promise.join

用于协调多个并行的promise。当需要处理一个不定数量但是规格一致的多个promise时,.all()是较好的选择。但是当我们需要协调固定数量的离散的promise实例时，Promise.join()是一种更加简单（以及更加优雅）的方法。

let Promise = require('bluebird');
Promise.join(getPic(), getComment(), getTweets(), function(pics, comments, tweets){

});

11. Promise.try

通过Promise.try启动一个promise链，并将所有同步异常封装到promise的reject处理中。
Example

12. Promise.method

Promise.method 用来封装一个方法，使其返回 Promise。

13. 定时器

Promise.delay 返回的 Promise 会在指定的时间之后转换到已满足状态，并使用指定的值作为结果。Promise.timeout 用来为一个已有的 Promise 添加超时功能。

Promise.delay(1000, 'hello').then(console.log);
Promise.delay(1000, 'hello')
 .timeout(500, 'timed out')
 .then(console.log)
 .catch(console.error);

集合操作

1. Promise.all

Promise.all 接受一个 Iterable 参数，返回值：一个新的 Promise。结果 Promise 只有在 Iterable 中全部 Promise 对象都变为resolve时，才会返回resolve的Promise实例；任何 Promise 出现错误会导致结果 Promise 被拒绝。新的 Promise 的最终结果是一个包含 Iterable 中 Promise 的结果的数组。该 Iterable 中可以包含任何值。如果值不是 Promise，则其值会直接出现在结果中，并不需要等待 Promise 完成。

var files = [];
for(var i = 0; i < 10; i++){
    files.push(fs.writeFileAsync('file-' + i + ‘.txt’, '', 'utf-8'));
}
Promise.all(files).then(result => {
    //
})

Promise.props，类似于.all,但是针对对象属性的，而不是数组。

2. Promise.map

很多情况下需要把Iterable中对象转为Promise后再等待这些Promise完成。可以使用Promise.map方法：
Promise.map(iterable, mapper, concurrency):
参数：

• iterable: Iterable对象
• mapper: 转化为Promise的方法
• concurrency： 可选参数，控制同时运行的Promise的数量，默认值为Infinity，不限制并发数

//以下代码使用map代替array.push+Promise.all方法
Promise.map(['1.txt', '2.txt', '3.txt'],
   name => fs.readFileAsync(path.join(__dirname, name), 'utf-8')
).then(results => console.log(results.join(', '))).catch(console.error);

如果任何一个promise实例执行失败，则返回状态为reject的Promise实例。
，即当数组的元素对应的promise被解决时，mapper函数会尽快被调用。这意味着由最终解决组成的元素顺序不一定和输入时一样。
Promise.mapSeries 的作用与 Promise.map 相同，只不过 mapSeries 按照 Iterable 中的顺序依次遍历每个元素。

3. Promise.some

在有多个 Promise 时，如果只需要等待其中部分 Promise 完成，可以使用 Promise.some 并指定完成的 Promise 数量。

Promise.some([
 fs.readFileAsync(path.join(__dirname, '1.txt'), 'utf-8'),
 fs.readFileAsync(path.join(__dirname, '2.txt'), 'utf-8'),
 fs.readFileAsync(path.join(__dirname, '3.txt'), 'utf-8')
], 2).then(results => console.log(results.join(', '))).catch(console.error);

Promise.any: 相当于Promise.some并把数量设为1，返回值为单个值(不是长度为1的数组)。
Promise.race： 与any类似，不过 race 的结果有可能是被拒绝的 Promise，因此推荐的做法是使用 any。

4. .filter和.each

Promise.filter 可以等待多个 Promise 的完成，并对结果进行过滤。它实际上的效果相当于在 Promise.map 之后使用 Array 的 filter 方法来进行过滤。

Promise.filter([
 fs.readFileAsync('1.txt', 'utf-8'),
 fs.readFileAsync('2.txt', 'utf-8'),
 fs.readFileAsync('3.txt', 'utf-8')
], value => value.length > 1).then(results => console.log(results.join(', '))).catch(console.error);

.each依次遍历一个数组或者一个数组的promise。遍历函数会被传入四个参数：（total, item, index, arrayLength）。
如果任何一个promise实例执行失败，则返回状态为reject的Promise实例。
如果遍历函数返回了一个promise或者其他含有.then()方法的对象，那么在继续下一个循环之前，这个promise的结果会被延迟。
官网例子(过滤当前目录下可访问的文件夹)：

var Promise = require("bluebird");
var E = require("core-error-predicates");
var fs = Promise.promisifyAll(require("fs"));

fs.readdirAsync(process.cwd()).filter(function(fileName) {
    return fs.statAsync(fileName)
        .then(function(stat) {
            return stat.isDirectory();
        })
        .catch(E.FileAccessError, function() {
            return false;
        });
}).each(function(directoryName) {
    console.log(directoryName, " is an accessible directory");
});

5. Promise.reduce

Promise.reduce 把多个 Promise 的结果缩减成单个值。其作用类似 Array 的 reduce 方法，但是可以处理 Promise 对象。

Promise.reduce(['1.txt', '2.txt', '3.txt'],
 (total, name) => {
   return fs.readFileAsync(path.join(__dirname, name), 'utf-8').then(data => total + data.length);
 }, 0)
 .then(result => console.log(`Total size: ${result}`)).catch(console.error);

资源使用

资源释放逻辑一般在finally中添加，但是当Promise相互嵌套时，很容易产生资源没有被释放的情况。Bluebird 提供了更加健壮的资源管理方式，即使用资源释放器（disposer）和 Promise.using 方法。
资源释放器以 Disposer 对象表示，通过 Promise 的 disposer 方法来创建。创建时的参数是一个用来释放资源的方法。该方法的第一个参数是资源对象，第二个参数是 Promise.using 产生的 Promise 对象。Disposer 对象可以传递给 Promise.using 来保证其资源释放逻辑被执行。

class Connection {
 query() {
   return Promise.resolve('query');
 }
 close() {
   console.log('close');
 }
}
class DB {
 connect() {
   return Promise.resolve(new Connection());
 }
}
const disposer = new DB().connect().disposer(connection => connection.close());
Promise.using(disposer, connection => connection.query())
 .then(console.log).catch(console.error);