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

這類方法略簡單，不說了。。。