Bluebird-Core API(二)

.error

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

和catch同樣，可是catch捕獲了全部錯誤類型的異常，而error捕獲是操做異常

注：「errors」意爲錯誤，做爲對象能 夠instanceof Error，不是字符串、數字等。See a string is not an error.

下面例子跟.catch模式恆等的

// Assumes OperationalError has been made global
function isOperationalError(e) {
    if (e == null) return false;
    return (e instanceof OperationalError) || (e.isOperational === true);
}

// Now this bit:
.catch(isOperationalError, function(e) {
    // ...
})

// Is equivalent to:

.error(function(e) {
    // ...
});

For example, if a promisified function errbacks the node-style callback with an error, that could be caught with .error. However if the node-style callback throws an error, only .catch would catch that.

In the following example you might want to handle just the SyntaxError from JSON.parse and Filesystem errors from fs but let programmer errors bubble as unhandled rejections:

var fs = Promise.promisifyAll(require("fs"));

fs.readFileAsync("myfile.json").then(JSON.parse).then(function (json) {
    console.log("Successful json")
}).catch(SyntaxError, function (e) {
    console.error("file contains invalid json");
}).error(function (e) {
    console.error("unable to read file, because: ", e.message);
});

Now, because there is no catch-all handler, if you typed console.lag (causes an error you don't expect), you will see:

Possibly unhandled TypeError: Object #<Console> has no method 'lag'
    at application.js:8:13
From previous event:
    at Object.<anonymous> (application.js:7:4)
    at Module._compile (module.js:449:26)
    at Object.Module._extensions..js (module.js:467:10)
    at Module.load (module.js:349:32)
    at Function.Module._load (module.js:305:12)
    at Function.Module.runMain (module.js:490:10)
    at startup (node.js:121:16)
    at node.js:761:3

( If you don't get the above - you need to enable long stack traces )

And if the file contains invalid JSON:

file contains invalid json

And if the fs module causes an error like file not found:

unable to read file, because:  ENOENT, open 'not_there.txt'

.finally

.finally(function() handler) -> Promise

.lastly(function() handler) -> Promise

傳入一個句柄無論Promise結果若是都會執行，返回一個新的Promise，從.finally語義來講，這個句柄（handler）中最終值是不能修改的。

Note: using .finally for resource management has better alternatives, see resource management

Consider the example:

function anyway() {
    $("#ajax-loader-animation").hide();
}

function ajaxGetAsync(url) {
    return new Promise(function (resolve, reject) {
        var xhr = new XMLHttpRequest;
        xhr.addEventListener("error", reject);
        xhr.addEventListener("load", resolve);
        xhr.open("GET", url);
        xhr.send(null);
    }).then(anyway, anyway);
}

This example doesn't work as intended because the then handler actually swallows the exception and returns undefinedfor any further chainers.

The situation can be fixed with .finally:

function ajaxGetAsync(url) {
    return new Promise(function (resolve, reject) {
        var xhr = new XMLHttpRequest;
        xhr.addEventListener("error", reject);
        xhr.addEventListener("load", resolve);
        xhr.open("GET", url);
        xhr.send(null);
    }).finally(function() {
        $("#ajax-loader-animation").hide();
    });
}

Now the animation is hidden but, unless it throws an exception, the function has no effect on the fulfilled or rejected value of the returned promise. This is similar to how the synchronous finally keyword behaves.

If the handler function passed to .finally returns a promise, the promise returned by .finally will not be settled until the promise returned by the handler is settled. If the handler fulfills its promise, the returned promise will be fulfilled or rejected with the original value. If the handler rejects its promise, the returned promise will be rejected with the handler's value. This is similar to throwing an exception in a synchronous finally block, causing the original value or exception to be forgotten. This delay can be useful if the actions performed by the handler are done asynchronously. For example:

function ajaxGetAsync(url) {
    return new Promise(function (resolve, reject) {
        var xhr = new XMLHttpRequest;
        xhr.addEventListener("error", reject);
        xhr.addEventListener("load", resolve);
        xhr.open("GET", url);
        xhr.send(null);
    }).finally(function() {
        return Promise.fromCallback(function(callback) {
            $("#ajax-loader-animation").fadeOut(1000, callback);
        });
    });
}

If the fade out completes successfully, the returned promise will be fulfilled or rejected with the value from xhr. If .fadeOutthrows an exception or passes an error to the callback, the returned promise will be rejected with the error from .fadeOut.

For compatibility with earlier ECMAScript version, an alias .lastly is provided for .finally.

 

.bind

.bind(any|Promise<any> thisArg) -> BoundPromise

Same as calling Promise.bind(thisArg, thisPromise).