bluebird & promise 中文文档

bluebird & promise 中文文档

bluebird是一个第三方Promise规范实现库,它不仅完全兼容原生Promise对象,且比原生对象功能更强大。

安装

npm install bluebird

引入

const Promise = require('bluebird');

核心方法

new Promise - 创建实例

new Promise(function(function resolve, function reject) resolver) -> Promise

在使用Promise进行处理时,要确保每一步都要返回一个Promise实例,并进行链式处理。如果不能立即开始一个Promise链式处理,可以使用new Promise来构造一个实例:

function getConnection(urlString) {
  return new Promise(function(resolve) {
    // 不使用 new Promise时,这里会显式的抛出一个异常
    const params = parse(urlString);
    resolve(getAdapter(params).getConnection());
  });
}

.then - 实例的then()方法

.then(
  [function(any value) fulfilledHandler],
  [function(any error) rejectedHandler]
) -> Promise

Promise A+ 规范中的.then()方法,该方法可以同时传入用于操作成功后调用的fulfilledHandler回调函数和用于操作失败后调用的rejectedHandler回调函数,也可以只传入其中的一个。

.spread - 展开实例返回的结果数组

.spread(
  [function(any values...) fulfilledHandler]
) -> Promise

类似调用.then方法,但执行成功后的值(fulfillment值)必须是一个数组,它会将参数扁平化并分别调用fulfilledHandler处理函数。

.catch - 实例异常处理方法

.catch(function(any error) handler) -> Promise
.caught(function(any error) handler) -> Promise

.catchPromise链式处理中的用于异常处理的便捷方法。这个方法有两个变体:一个用于捕获所有错误,类似catch(e) {的同步方法;一个是用于捕获指定错误的变体方法。

function getItems(param) {
  return getItemsAsync().then(items => {
    if(!items) throw new InvalidItemsError(); 
    return items;
  }).catch(e => {
    // 从 getItemsAsync 中返回一个 rejects 或 假值时,可以从这里解决和恢复错误
    throw e; 
    // Need to rethrow unless we actually recovered, just like in the synchronous version
  }).then(process);
}

.error - 实例操作异常处理

.error([function(any error) rejectedHandler]) -> Promise

类似.catch,但它只捕获和处理操作错误。

.finally - 实例最终调用方法

.finally(function() handler) -> Promise
.lastly(function() handler) -> Promise

这个方法不会考虑Promise实例的执行状态,而始终会调用并返回一个新promise链。

Promise.join - 关联多个不相关的实例

Promise.join(
  Promise<any>|any values...,
  function handler
) -> Promise

关联多个不相关的Promise实例。.all很适合处理统一处理动态大小的列表,而.join使处理多个离散的Promise实例处理更加容易。

在这个方法,方法的最后一个参数是一个回调函数,其中包含所有的处理成功的结果:

const Promise = require("bluebird");
const join = Promise.join;

join(getPictures(), getComments(), getTweets(),
  function(pictures, comments, tweets) {
    console.log("in total: " + pictures.length + comments.length + tweets.length);
});

Promise.try - 包装为Promise实例

Promise.try(function() fn) -> Promise
Promise.attempt(function() fn) -> Promise

通过Promise.try启动一个promise链,并将所有同步异常封装到promisereject处理中:

function getUserById(id) {
  return Promise.try(function() {
    if (typeof id !== "number") {
      throw new Error("id must be a number");
    }
    return db.getUserById(id);
  });
}

Promise.method - 将函数包装为返回Promise实例的函数

Promise.method(function(...arguments) fn) -> function

包装指定的函数fn,包装后函数会返回一个Promise实例。

Promise.resolve - 包装值为Promise resolved实例

Promise.resolve(Promise<any>|any value) -> Promise

通过指定值创建Promise resolved实例。如果值已使用Promise,那会返回它。如果值不是thenable对象,会将其包装成一个会执行成功的Promise实例,该值将会做为fulfillment值返回。

Promise.reject - 包装值为Promise reject实例

Promise.reject(any error) -> Promise

将指定的值包装为一个rejected状态的Promise实例。

集合操作

Promise.all - 执行多个Promise实例

Promise.all(Iterable<any>|Promise<Iterable<any>> input) -> Promise

参数是一个Iterable(可迭代)对象(如:promise数组)。在这个方法中,promise数组中所有的promise实例都变为resolve的时候,该方法才会返回,并将所有结果传递到结果数组中。promise数组中任何一个promisereject的话,则整个Promise.all调用会立即终止,并返回一个状态为reject的新的promise对象。

const files = [];
for (var i = 0; i < 100; ++i) {
  files.push(fs.writeFileAsync("file-" + i + ".txt", "", "utf-8"));
}
Promise.all(files).then(function() {
  console.log("all the files were created");
});

Promise.props - 对象属性包装成Promise实例

Promise.props(Object|Map|Promise<Object|Map> input) -> Promise

Promise.props功能与Promise.all功能类型,不同的是访方法用于对象属性或Map实体而不是可迭代值,即把对象或Map实体的函数属性键变为Promise实例。对象属性或Map实体全部执行通过后返回一个promise,这个promise对象的fulfillment值是一个拥有原对象或Map键值的对象或Map

Promise.props({
  pictures: getPictures(),
  comments: getComments(),
  tweets: getTweets()
}).then(function(result) {
  console.log(result.tweets, result.pictures, result.comments);
});

Promise.any - 执行成1个即返回

Promise.any(Iterable<any>|Promise<Iterable<any>> input) -> Promise

promise执行成功后,实现值不是数组而是1个直接值。

Promise.some - 成功指定次数后返回

Promise.some(
  Iterable<any>|Promise<Iterable<any>> input,
  int count
 ) -> Promise

指定的Iterable数组或Iterable promise,执行成功指定次数count后即返回,实现值是一个数组。

Promise.map - Map操作

Promise.map(
  Iterable<any>|Promise<Iterable<,
  function(any item, int index, int length) mapper,
  [Object {concurrency: int=Infinity} options]
 ) -> Promise

为指定的Iterable数组或Iterable promise,执行一个处理函数mapper并返回执行后的数组或Iterable promise

Promises会等待mapper全部执行完成后返回,如果数组中的promise执行全部分成功则Promises中是执行成功值。如果任何一个promise执行失败,Promises对应的也是拒绝值。

Promise.reduce - Reduce操作

Promise.reduce(
  Iterable<any>|Promise<Iterable<,
  function(any accumulator, any item, int index, int length) reducer,
  [any initialValue]
) -> Promise

为指定的Iterable数组或Iterable promise,执行一个处理函数reducer,并返回一个经过Reduce处理后promise

reducer函数会最终返回一个promise。数组中的所有promise处理成功后,会返回一个成功状态的promise,任何一个执行失败都会返回一个拒绝状态的promise

Promise.filter - filter过滤

Promise.filter(
  Iterable<any>|Promise<Iterable<,
  function(any item, int index, int length) filterer,
  [Object {concurrency: int=Infinity} options]
) -> Promise

为指定的Iterable数组或Iterable promise,执行一个过滤函数filterer,并返回经过筛选后promises数组。

Promise.each - 依次执行

Promise.each(
  Iterable<any>|Promise<Iterable>,
  function(any item, int index, int length) iterator
) -> Promise

为指定的Iterable数组或Iterable promise,执行一个函数iterator,该函数参数为(value, index, length)value输入数组中promiseresolved值。

iterator函数会最终返回一个promise。数组中的所有promise处理成功后,会返回一个成功状态的promise,任何一个执行失败都会返回一个拒绝状态的promise

Promise.mapSeries - 顺序执行的Map操作

Promise.mapSeries(
  Iterable<any>|Promise<Iterable<,
  function(any item, int index, int length) mapper
) -> Promise

Promise.map,但会按数组顺序依次执行mapper

Promise.race - 非Promise对象包成Promise对象

Promise.race(Iterable<any>|Promise<Iterable<) -> Promise

将数组中的非Promise对象,包装成Promise对象。

Promise包装器

Promise.promisify - 单个函数对象的Promise

Promise.promisify(
  function(any arguments..., function callback) nodeFunction,
  [Object {
    multiArgs: boolean=false,
    context: any=this
  } options]
) -> function

Node.js对象nodeFunction包装为Promise对象,包装后将使用.then.catchPromise方法代替Node.js中的回调。

Promise.promisifyAll - 对象属性的Promise

Promise.promisifyAll(
  Object target,
  [Object {
    suffix: String="Async",
    multiArgs: boolean=false,
    filter: boolean function(String name, function func, Object target, boolean passesDefaultFilter),
    promisifier: function(function originalFunction, function defaultPromisifier)
  } options]
) -> Object

将传入的对象实体的属性包装成Promise对象。

定时器

Promise.delay - 延时执行

Promise.delay(
  int ms,
  [any|Promise<any> value=undefined]
) -> Promise

将指定的Promise对象value延时ms毫秒后执行。

.timeout - 实例超时

.timeout(
  int ms,
  [String message="operation timed out"]
) -> Promise
.timeout(
  int ms,
  [Error error]
) -> Promise

参考

内容摘自