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
.catch
是Promise
链式处理中的用于异常处理的便捷方法。这个方法有两个变体:一个用于捕获所有错误,类似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
链,并将所有同步异常封装到promise
的reject
处理中:
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
数组中任何一个promise
为reject
的话,则整个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
输入数组中promise
的resolved
值。
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
、.catch
等Promise
方法代替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
评论