add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / promise / Promise.js

/*\r
 Ext.promise.Deferred adapted from:\r
 [DeftJS](https://github.com/deftjs/deftjs5)\r
 Copyright (c) 2012-2014 [DeftJS Framework Contributors](http://deftjs.org)\r
 Open source under the [MIT License](http://en.wikipedia.org/wiki/MIT_License).\r
 */\r
\r
/**\r
 * Promises represent a future value; i.e., a value that may not yet be available.\r
 *\r
 * Users should **not** create instances of this class directly. Instead user code should\r
 * use `new {@link Ext.Promise}()` or `new {@link Ext.Deferred}()` to create and manage\r
 * promises. If the browser supports the standard `Promise` constructor, this class will\r
 * not be used by `Ext.Promise`. This class will always be used by `Ext.Deferred` in order\r
 * to provide enhanced capabilities beyond standard promises.\r
 *\r
 * A Promise's `{@link #then then()}` method is used to specify onFulfilled and onRejected\r
 * callbacks that will be notified when the future value becomes available. Those callbacks\r
 * can subsequently transform the value that was resolved or the reason that was rejected.\r
 * Each call to `then` returns a new Promise of that transformed value; i.e., a Promise\r
 * that is resolved with the callback return value or rejected with any error thrown by\r
 * the callback.\r
 *\r
 * ## Basic Usage\r
 *\r
 *      this.companyService.loadCompanies().then(\r
 *          function (records) {\r
 *              // Do something with result.\r
 *          },\r
 *          function (error) {\r
 *              // Do something on failure.\r
 *          }).\r
 *      always(function () {\r
 *          // Do something whether call succeeded or failed\r
 *      });\r
 *\r
 * The above code uses the `Promise` returned from the `companyService.loadCompanies()`\r
 * method and uses `then()` to attach success and failure handlers. Finally, an `always()`\r
 * method call is chained onto the returned promise. This specifies a callback function\r
 * that will run whether the underlying call succeeded or failed.\r
 *\r
 * See `{@link Ext.Deferred}` for an example of using the returned Promise.\r
 *\r
 * [1]: http://wiki.ecmascript.org/doku.php?id=harmony:specification_drafts#april_14_2015_rev_38_final_draft\r
 *\r
 * @since 6.0.0\r
 */\r
Ext.define('Ext.promise.Promise', function (ExtPromise) {\r
    var Deferred;\r
\r
return {\r
    requires: [\r
        'Ext.promise.Deferred'\r
    ],\r
\r
    statics: {\r
        /**\r
         * @property CancellationError\r
         * @static\r
         * The type of `Error` propagated by the `{@link #method-cancel}` method. If\r
         * the browser provides a native `CancellationError` then that type is used. If\r
         * not, a basic `Error` type is used.\r
         */\r
        CancellationError: Ext.global.CancellationError || Error,\r
\r
        _ready: function () {\r
            // Our requires are met, so we can cache Ext.promise.Deferred\r
            Deferred = Ext.promise.Deferred;\r
        },\r
\r
        /**\r
         * Returns a new Promise that will only resolve once all the specified\r
         * `promisesOrValues` have resolved.\r
         *\r
         * The resolution value will be an Array containing the resolution value of each\r
         * of the `promisesOrValues`.\r
         *\r
         * The public API's to use instead of this method are `{@link Ext.Promise#all}`\r
         * and `{@link Ext.Deferred#all}`.\r
         *\r
         * @param {Mixed[]/Ext.promise.Promise[]/Ext.promise.Promise} promisesOrValues An\r
         * Array of values or Promises, or a Promise of an Array of values or Promises.\r
         * @return {Ext.promise.Promise} A Promise of an Array of the resolved values.\r
         *\r
         * @static\r
         * @private\r
         */\r
        all: function (promisesOrValues) {\r
            //<debug>\r
            if (!(Ext.isArray(promisesOrValues) || ExtPromise.is(promisesOrValues))) {\r
                Ext.raise('Invalid parameter: expected an Array or Promise of an Array.');\r
            }\r
            //</debug>\r
\r
            return ExtPromise.when(promisesOrValues).then(function (promisesOrValues) {\r
                var deferred = new Deferred(),\r
                    remainingToResolve = promisesOrValues.length,\r
                    results = new Array(remainingToResolve),\r
                    index, promiseOrValue, resolve, i, len;\r
\r
                if (!remainingToResolve) {\r
                    deferred.resolve(results);\r
                }\r
                else {\r
                    resolve = function (item, index) {\r
                        return ExtPromise.when(item).then (function (value) {\r
                            results[index] = value;\r
\r
                            if (!--remainingToResolve) {\r
                                deferred.resolve(results);\r
                            }\r
\r
                            return value;\r
                        }, function (reason) {\r
                            return deferred.reject(reason);\r
                        });\r
                    };\r
\r
                    for (index = i = 0, len = promisesOrValues.length; i < len; index = ++i) {\r
                        promiseOrValue = promisesOrValues[index];\r
\r
                        if (index in promisesOrValues) {\r
                            resolve(promiseOrValue, index);\r
                        }\r
                        else {\r
                            remainingToResolve--;\r
                        }\r
                    }\r
                }\r
\r
                return deferred.promise;\r
            });\r
        },\r
\r
        /**\r
         * Determines whether the specified value is a Promise (including third-party\r
         * untrusted Promises or then()-ables), based on the Promises/A specification\r
         * feature test.\r
         *\r
         * @param {Mixed} value A potential Promise.\r
         * @return {Boolean} `true` if the given value is a Promise, otherwise `false`.\r
         * @static\r
         * @private\r
         */\r
        is: function (value) {\r
            return (Ext.isObject(value) || Ext.isFunction(value)) &&\r
                Ext.isFunction(value.then);\r
        },\r
\r
        /**\r
         * Rethrows the specified Error on the next turn of the event loop.\r
         * @static\r
         * @private\r
         */\r
        rethrowError: function (error) {\r
            Ext.asap(function () {\r
                throw error;\r
            });\r
        },\r
\r
        /**\r
         * Returns a new Promise that either\r
         *\r
         *  * Resolves immediately for the specified value, or\r
         *  * Resolves or rejects when the specified promise (or third-party Promise or\r
         *    then()-able) is resolved or rejected.\r
         *\r
         * The public API's to use instead of this method are `{@link Ext.Promise#resolve}`\r
         * and `{@link Ext.Deferred#resolved}`.\r
         *\r
         * @param {Mixed} promiseOrValue A Promise (or third-party Promise or then()-able)\r
         * or value.\r
         * @return {Ext.Promise} A Promise of the specified Promise or value.\r
         *\r
         * @static\r
         * @private\r
         */\r
        when: function (value) {\r
            var deferred = new Ext.promise.Deferred();\r
\r
            deferred.resolve(value);\r
\r
            return deferred.promise;\r
        }\r
    },\r
\r
    /**\r
     * @property {Ext.promise.Deferred} Reference to this promise's\r
     * `{@link Ext.promise.Deferred Deferred}` instance.\r
     *\r
     * @readonly\r
     * @private\r
     */\r
    owner: null,\r
\r
    /**\r
     * NOTE: {@link Ext.promise.Deferred Deferreds} are the mechanism used to create new\r
     * Promises.\r
     * @param {Ext.promise.Deferred} owner The owning `Deferred` instance.\r
     *\r
     * @private\r
     */\r
    constructor: function (owner) {\r
        this.owner = owner;\r
    },\r
\r
    /**\r
     * Attaches onFulfilled and onRejected callbacks that will be notified when the future\r
     * value becomes available.\r
     *\r
     * Those callbacks can subsequently transform the value that was fulfilled or the error\r
     * that was rejected. Each call to `then` returns a new Promise of that transformed\r
     * value; i.e., a Promise that is fulfilled with the callback return value or rejected\r
     * with any error thrown by the callback.\r
     *\r
     * @param {Function} onFulfilled Optional callback to execute to transform a\r
     * fulfillment value.\r
     * @param {Function} onRejected Optional callback to execute to transform a rejection\r
     * reason.\r
     * @param {Function} onProgress Optional callback function to be called with progress\r
     * updates.\r
     * @param {Object} scope Optional scope for the callback(s).\r
     * @return {Ext.promise.Promise} Promise that is fulfilled with the callback return\r
     * value or rejected with any error thrown by the callback.\r
     */\r
    then: function (onFulfilled, onRejected, onProgress, scope) {\r
        var ref;\r
\r
        if (arguments.length === 1 && Ext.isObject(arguments[0])) {\r
            ref = arguments[0];\r
            onFulfilled = ref.success;\r
            onRejected = ref.failure;\r
            onProgress = ref.progress;\r
            scope = ref.scope;\r
        }\r
\r
        if (scope) {\r
            if (onFulfilled) {\r
                onFulfilled = Ext.Function.bind(onFulfilled, scope);\r
            }\r
            \r
            if (onRejected) {\r
                onRejected = Ext.Function.bind(onRejected, scope);\r
            }\r
            \r
            if (onProgress) {\r
                onProgress = Ext.Function.bind(onProgress, scope);\r
            }\r
        }\r
\r
        return this.owner.then(onFulfilled, onRejected, onProgress);\r
    },\r
\r
    /**\r
     * Attaches an onRejected callback that will be notified if this Promise is rejected.\r
     *\r
     * The callback can subsequently transform the reason that was rejected. Each call to\r
     * `otherwise` returns a new Promise of that transformed value; i.e., a Promise that\r
     * is resolved with the original resolved value, or resolved with the callback return\r
     * value or rejected with any error thrown by the callback.\r
     *\r
     * @param {Function} onRejected Callback to execute to transform a rejection reason.\r
     * @param {Object} scope Optional scope for the callback.\r
     * @return {Ext.promise.Promise} Promise of the transformed future value.\r
     */\r
    otherwise: function (onRejected, scope) {\r
        var ref;\r
\r
        if (arguments.length === 1 && Ext.isObject(arguments[0])) {\r
            ref = arguments[0];\r
            onRejected = ref.fn;\r
            scope = ref.scope;\r
        }\r
\r
        if (scope != null) {\r
            onRejected = Ext.Function.bind(onRejected, scope);\r
        }\r
\r
        return this.owner.then(null, onRejected);\r
    },\r
\r
    /**\r
     * Attaches an onCompleted callback that will be notified when this Promise is completed.\r
     *\r
     * Similar to `finally` in `try... catch... finally`.\r
     *\r
     * NOTE: The specified callback does not affect the resulting Promise's outcome; any\r
     * return value is ignored and any Error is rethrown.\r
     *\r
     * @param {Function} onCompleted Callback to execute when the Promise is resolved or\r
     * rejected.\r
     * @param {Object} scope Optional scope for the callback.\r
     * @return {Ext.promise.Promise} A new "pass-through" Promise that is resolved with\r
     * the original value or rejected with the original reason.\r
     */\r
    always: function (onCompleted, scope) {\r
        var ref;\r
\r
        if (arguments.length === 1 && Ext.isObject(arguments[0])) {\r
            ref = arguments[0];\r
            onCompleted = ref.fn;\r
            scope = ref.scope;\r
        }\r
\r
        if (scope != null) {\r
            onCompleted = Ext.Function.bind(onCompleted, scope);\r
        }\r
\r
        return this.owner.then(function (value) {\r
            try {\r
                onCompleted();\r
            }\r
            catch (e) {\r
                ExtPromise.rethrowError(e);\r
            }\r
            \r
            return value;\r
        }, function (reason) {\r
            try {\r
                onCompleted();\r
            }\r
            catch (e) {\r
                ExtPromise.rethrowError(e);\r
            }\r
            \r
            throw reason;\r
        });\r
    },\r
\r
    /**\r
     * Terminates a Promise chain, ensuring that unhandled rejections will be rethrown as\r
     * Errors.\r
     *\r
     * One of the pitfalls of interacting with Promise-based APIs is the tendency for\r
     * important errors to be silently swallowed unless an explicit rejection handler is\r
     * specified.\r
     *\r
     * For example:\r
     *\r
     *      promise.then(function () {\r
     *          // logic in your callback throws an error and it is interpreted as a\r
     *          // rejection. throw new Error("Boom!");\r
     *      });\r
     *\r
     *      // The Error was not handled by the Promise chain and is silently swallowed.\r
     *\r
     * This problem can be addressed by terminating the Promise chain with the done()\r
     * method:\r
     *\r
     *      promise.then(function () {\r
     *          // logic in your callback throws an error and it is interpreted as a\r
     *          // rejection. throw new Error("Boom!");\r
     *      }).done();\r
     *\r
     *     // The Error was not handled by the Promise chain and is rethrown by done() on\r
     *     // the next tick.\r
     *\r
     * The `done()` method ensures that any unhandled rejections are rethrown as Errors.\r
     */\r
    done: function () {\r
        this.owner.then(null, ExtPromise.rethrowError);\r
    },\r
\r
    /**\r
     * Cancels this Promise if it is still pending, triggering a rejection with a\r
     * `{@link #CancellationError}` that will propagate to any Promises originating from\r
     * this Promise.\r
     *\r
     * NOTE: Cancellation only propagates to Promises that branch from the target Promise.\r
     * It does not traverse back up to parent branches, as this would reject nodes from\r
     * which other Promises may have branched, causing unintended side-effects.\r
     *\r
     * @param {Error} reason Cancellation reason.\r
     */\r
    cancel: function (reason) {\r
        if (reason == null) {\r
            reason = null;\r
        }\r
        \r
        this.owner.reject(new this.self.CancellationError(reason));\r
    },\r
\r
    /**\r
     * Logs the resolution or rejection of this Promise with the specified category and\r
     * optional identifier. Messages are logged via all registered custom logger functions.\r
     *\r
     * @param {String} identifier An optional identifier to incorporate into the\r
     * resulting log entry.\r
     *\r
     * @return {Ext.promise.Promise} A new "pass-through" Promise that is resolved with\r
     * the original value or rejected with the original reason.\r
     */\r
    log: function (identifier) {\r
        if (identifier == null) {\r
            identifier = '';\r
        }\r
        \r
        return this._owner.then(function (value) {\r
            Ext.log("" + (identifier || 'Promise') + " resolved with value: " + value);\r
            \r
            return value;\r
        }, function (reason) {\r
            Ext.log("" + (identifier || 'Promise') + " rejected with reason: " + reason);\r
            \r
            throw reason;\r
        });\r
    }\r
}},\r
function (ExtPromise) {\r
    ExtPromise._ready();\r
});\r