Q promise API简单翻译

详细API：https://github.com/kriskowal/q/wiki/API-Reference

　　Q提供了promise的一种实现方式，如今在node中用的已经比较多了。由于没有中文的api，我就简单翻译下吧。鄙人不才，欢迎拍砖。。。

1、Core Promise Methods

一、promise.then(onFulfilled, onRejected, onProgress)

 这个就不说了吧。

二、promise.catch(onRejected)

 其等同于：promise.then(undefined, onRejected)意思是当catch到异常时的执行。

三、promise.progress(onProgress)

等同于：promise.then(undefined, undefined, onProgress)？？？

四、promise.finally(callback)

相似与trycatch中的finally，无论成功与否都会执行callback，主要用在关闭数据库、关闭服务，删除一个无用的键等。finally后会返回这个promise执行完彻底同样的promise（包括失败和成功），可是若是callback也返回promise，那么前者会等到后者出现后才进行解析。

五、promise.done(onFulfilled, onRejected, onProgress)

这个方法很像痛恨，可是若是有一个未处理的rejection或者其onrejected未定义，这个方法就有用了。官方的解释是，这个方法能够用于终结promise链，以防止promise的继续传递。

2、Promise-for-Object Methods

这类方法较简单：

一、promise.get(propertyName)

等价以下，不解释：

promise.then(function (o) { return o[propertyName]; });

 二、promise.post(methodName, args)

等价以下：不解释：

promise.then(function (o) { return o[methodName].apply(o, args); });


三、promise.invoke(methodName, ...args)

 与上一个相似，不解释，区别就是参数不是数组，而是直接赋值进去。

四、promise.keys()

 等价以下：不解释：

promise.then(function (o) { return Object.keys(o); });

 3、Promise-for-Function Methods

一、promise.fbind(...args) (deprecated)

 没看明白啥意思，

二、promise.fapply(args)

等价于：

promise.then(function (f) { return f.apply(undefined, args); });

 意思就是promise返回的是函数，而后调用它。

三、promise.fcall(...args)

4、Promise-for-Array Methods

一、promise.all()

 这个方法颇有用，其接受一个promise数组，只有当数组中的每一个promise都执行成功，才会成功并将结果以数组的形式返回。当有一个promise失败，即失败。总之是为了确保数组中的promise都成功。典型例子：

Q.all([getFromDisk(), getFromCloud()]).done(function (values) { assert(values[0] === values[1]); // values[0] is fromDisk and values[1] is fromCloud });

二、promise.allSettled()

啊啊啊啊。。。不彻底懂！

三、promise.spread(onFulfilled, onRejected)

 这个方法和then相似，可是，当一个数组的promise有一个失败时，其将会以第一个失败的promise的reject缘由来执行onRejected。。。因此其与all配合使用较多，如：

Q.all([getFromDisk(), getFromCloud()]).spread(function (diskVal, cloudVal) { assert(diskVal === cloudVal); }).done();

5、Utility Methods

一、promise.thenResolve(value)

等价于：promise.then(function () { return value; }).

 二、promise.thenReject(reason)

等价于：promise.then(function () { throw reason; }).

三、promise.timeout(ms, message)

 正常状况下 会正常返回promise结果，可是若是promise在ms毫秒前没有执行完，就会返回一个message的rejection，若是message没有给，就返回："Timed out after " + ms + " ms".如：

promise.timeout(10000).then(
  function (result) { // will be called if the promise resolves normally console.log(result); }, function (err) { // will be called if the promise is rejected, or the 10 second timeout occurs console.log(err); } );
四、promise.delay(ms)
注意，这里是，只有当ms毫秒后promise才执行完时才会正常的返回正常的值。
五、Q.delay(ms)

Q.delay(150).then(doSomething);等价于settimeout

6、Promise Creation
一、Q.defer()

Returns a "deferred" object with a:

• promise property                   //返回promise
• resolve(value) method          //若是promise未执行完，就等待它执行完（完成或失败）；总之，就是让其执行完，而后若是执行完其没有rejection或者fulfillment ，就以参数value来代替。
• reject(reason) method          //手动以reason来使promise失败
• notify(value) method           //多用于回调
• makeNodeResolver() method     

返回了一个拥有上述属性和方法的对象。

这个方法须要详细说下，其通常用来手动构建promise，来举个例子：

function fs_readFile (file, encoding, callback) { var deferred = Q.defer() fs.readFile(function (err, data) { if (err) deferred.reject(err) // rejects the promise with `er` as the reason else deferred.resolve(data) // fulfills the promise with `data` as the value }) return deferred.promise.nodeify(callback) // the promise is returned }

上面的函数，经过Q.defer手动来定义了promise。自行理解

 

4、Q object

这类方法略简单，不说了。。。