add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / Deferred.js

/*\r
 Ext.Deferred adapted from:\r
 [DeftJS](https://github.com/deftjs/deftjs5)\r
 Copyright (c) 2012-2013 [DeftJS Framework Contributors](http://deftjs.org)\r
 Open source under the [MIT License](http://en.wikipedia.org/wiki/MIT_License).\r
\r
 when(), all(), any(), some(), map(), reduce(), delay() and timeout()\r
 sequence(), parallel(), pipeline()\r
 methods adapted from: [when.js](https://github.com/cujojs/when)\r
 Copyright (c) B Cavalier & J Hann\r
 Open source under the [MIT License](http://en.wikipedia.org/wiki/MIT_License).\r
 */\r
\r
/**\r
 * Deferreds are the mechanism used to create new Promises. A Deferred has a single\r
 * associated Promise that can be safely returned to external consumers to ensure they do\r
 * not interfere with the resolution or rejection of the deferred operation.\r
 *\r
 * This implementation of Promises is an extension of the ECMAScript 6 Promises API as\r
 * detailed [here][1]. For a compatible, though less full featured, API see `{@link Ext.Promise}`.\r
 *\r
 * A Deferred is typically used within the body of a function that performs an asynchronous\r
 * operation. When that operation succeeds, the Deferred should be resolved; if that\r
 * operation fails, the Deferred should be rejected.\r
 *\r
 * Each Deferred has an associated Promise. A Promise delegates `then` calls to its\r
 * Deferred's `then` method. In this way, access to Deferred operations are divided between\r
 * producer (Deferred) and consumer (Promise) roles.\r
 *\r
 * ## Basic Usage\r
 *\r
 * In it's most common form, a method will create and return a Promise like this:\r
 *\r
 *      // A method in a service class which uses a Store and returns a Promise\r
 *      //\r
 *      loadCompanies: function () {\r
 *          var deferred = new Ext.Deferred(); // create the Ext.Deferred object\r
 *\r
 *          this.companyStore.load({\r
 *              callback: function (records, operation, success) {\r
 *                  if (success) {\r
 *                      // Use "deferred" to drive the promise:\r
 *                      deferred.resolve(records);\r
 *                  }\r
 *                  else {\r
 *                      // Use "deferred" to drive the promise:\r
 *                      deferred.reject("Error loading Companies.");\r
 *                  }\r
 *              }\r
 *          });\r
 *\r
 *          return deferred.promise;  // return the Promise to the caller\r
 *      }\r
 *\r
 * You can see this method first creates a `{@link Ext.Deferred Deferred}` object. It then\r
 * returns its `Promise` object for use by the caller. Finally, in the asynchronous\r
 * callback, it resolves the `deferred` object if the call was successful, and rejects the\r
 * `deferred` if the call failed.\r
 *\r
 * When a Deferred's `resolve` method is called, it fulfills with the optionally specified\r
 * value. If `resolve` is called with a then-able (i.e.a Function or Object with a `then`\r
 * function, such as another Promise) it assimilates the then-able's result; the Deferred\r
 * provides its own `resolve` and `reject` methods as the onFulfilled or onRejected\r
 * arguments in a call to that then-able's `then` function. If an error is thrown while\r
 * calling the then-able's `then` function (prior to any call back to the specified\r
 * `resolve` or `reject` methods), the Deferred rejects with that error. If a Deferred's\r
 * `resolve` method is called with its own Promise, it rejects with a TypeError.\r
 *\r
 * When a Deferred's `reject` method is called, it rejects with the optionally specified\r
 * reason.\r
 *\r
 * Each time a Deferred's `then` method is called, it captures a pair of optional\r
 * onFulfilled and onRejected callbacks and returns a Promise of the Deferred's future\r
 * value as transformed by those callbacks.\r
 *\r
 * See `{@link Ext.promise.Promise}` for an example of using the returned Promise.\r
 *\r
 * @since 6.0.0\r
 */\r
Ext.define('Ext.Deferred', function (Deferred) {\r
    var ExtPromise,\r
        when;\r
\r
return {\r
    extend: 'Ext.promise.Deferred',\r
\r
    requires: [\r
        'Ext.Promise'\r
    ],\r
\r
    statics: {\r
        _ready: function () {\r
            // Our requires are met, so we can cache Ext.promise.Deferred\r
            ExtPromise = Ext.promise.Promise;\r
            when = Ext.Promise.resolve;\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
         * @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
         * @static\r
         */\r
        all: function () {\r
            return ExtPromise.all.apply(ExtPromise, arguments);\r
        },\r
\r
        /**\r
         * Initiates a competitive race, returning a new Promise that will resolve when\r
         * any one of the specified `promisesOrValues` have resolved, or will reject when\r
         * all `promisesOrValues` have rejected or cancelled.\r
         *\r
         * The resolution value will the first value of `promisesOrValues` to resolve.\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 the first resolved value.\r
         * @static\r
         */\r
        any: 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 Deferred.some(promisesOrValues, 1).then(function (array) {\r
                return array[0];\r
            }, function (error) {\r
                if (error instanceof Error &&\r
                    error.message === 'Too few Promises were resolved.') {\r
                    Ext.raise('No Promises were resolved.');\r
                }\r
                else {\r
                    throw error;\r
                }\r
            });\r
        },\r
\r
        /**\r
         * Returns a new Promise that will automatically resolve with the specified\r
         * Promise or value after the specified delay (in milliseconds).\r
         *\r
         * @param {Mixed} promiseOrValue A Promise or value.\r
         * @param {Number} milliseconds A delay duration (in milliseconds).\r
         * @return {Ext.promise.Promise} A Promise of the specified Promise or value that\r
         * will resolve after the specified delay.\r
         * @static\r
         */\r
        delay: function (promiseOrValue, milliseconds) {\r
            var deferred;\r
\r
            if (arguments.length === 1) {\r
                milliseconds = promiseOrValue;\r
                promiseOrValue = undefined;\r
            }\r
\r
            milliseconds = Math.max(milliseconds, 0);\r
\r
            deferred = new Deferred();\r
\r
            setTimeout(function () {\r
                deferred.resolve(promiseOrValue);\r
            }, milliseconds);\r
\r
            return deferred.promise;\r
        },\r
\r
        /**\r
         * Traditional map function, similar to `Array.prototype.map()`, that allows\r
         * input to contain promises and/or values.\r
         *\r
         * The specified map function may return either a value or a promise.\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
         * @param {Function} mapFn A Function to call to transform each resolved value in\r
         * the Array.\r
         * @return {Ext.promise.Promise} A Promise of an Array of the mapped resolved\r
         * values.\r
         * @static\r
         */\r
        map: function (promisesOrValues, mapFn) {\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
\r
            if (!Ext.isFunction(mapFn)) {\r
                Ext.raise('Invalid parameter: expected a function.');\r
            }\r
            //</debug>\r
\r
            return Deferred.resolved(promisesOrValues).then(function (promisesOrValues) {\r
                var deferred, index, promiseOrValue, remainingToResolve, resolve, results, i, len;\r
\r
                remainingToResolve = promisesOrValues.length;\r
                results = new Array(promisesOrValues.length);\r
                deferred = new Deferred();\r
\r
                if (!remainingToResolve) {\r
                    deferred.resolve(results);\r
                }\r
                else {\r
                    resolve = function (item, index) {\r
                        return Deferred.resolved(item).then(function (value) {\r
                            return mapFn(value, index, results);\r
                        }).then(function (value) {\r
                            results[index] = value;\r
                            if (!--remainingToResolve) {\r
                                deferred.resolve(results);\r
                            }\r
                            return value;\r
                        }, function (reason) {\r
                            return deferred.reject(reason);\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
         * Returns a new function that wraps the specified function and caches the\r
         * results for previously processed inputs.\r
         *\r
         * Similar to {@link Ext.Function#memoize Ext.Function.memoize()}, except it\r
         * allows for parameters that are Promises and/or values.\r
         *\r
         * @param {Function} fn A Function to wrap.\r
         * @param {Object} scope An optional scope in which to execute the wrapped function.\r
         * @param {Function} hashFn An optional function used to compute a hash key for\r
         * storing the result, based on the arguments to the original function.\r
         * @return {Function} The new wrapper function.\r
         * @static\r
         */\r
        memoize: function (fn, scope, hashFn) {\r
            var memoizedFn = Ext.Function.memoize(fn, scope, hashFn);\r
\r
            return function () {\r
                return Deferred.all(Ext.Array.slice(arguments)).then(function (values) {\r
                    return memoizedFn.apply(scope, values);\r
                });\r
            };\r
        },\r
\r
        /**\r
         * Execute an Array (or {@link Ext.promise.Promise Promise} of an Array) of\r
         * functions in parallel.\r
         *\r
         * The specified functions may optionally return their results as\r
         * {@link Ext.promise.Promise Promises}.\r
         *\r
         * @param {Function[]/Ext.promise.Promise} fns The Array (or Promise of an Array)\r
         * of functions to execute.\r
         * @param {Object} scope Optional scope in which to execute the specified functions.\r
         * @return {Ext.promise.Promise} Promise of an Array of results for each function\r
         * call (in the same order).\r
         * @static\r
         */\r
        parallel: function (fns, scope) {\r
            if (scope == null) {\r
                scope = null;\r
            }\r
\r
            var args = Ext.Array.slice(arguments, 2);\r
\r
            return Deferred.map(fns, function (fn) {\r
                if (!Ext.isFunction(fn)) {\r
                    throw new Error('Invalid parameter: expected a function.');\r
                }\r
\r
                return fn.apply(scope, args);\r
            });\r
        },\r
\r
        /**\r
         * Execute an Array (or {@link Ext.promise.Promise Promise} of an Array) of\r
         * functions as a pipeline, where each function's result is passed to the\r
         * subsequent function as input.\r
         *\r
         * The specified functions may optionally return their results as\r
         * {@link Ext.promise.Promise Promises}.\r
         *\r
         * @param {Function[]/Ext.promise.Promise} fns The Array (or Promise of an Array)\r
         * of functions to execute.\r
         * @param {Object} initialValue Initial value to be passed to the first function\r
         * in the pipeline.\r
         * @param {Object} scope Optional scope in which to execute the specified functions.\r
         * @return {Ext.promise.Promise} Promise of the result value for the final\r
         * function in the pipeline.\r
         * @static\r
         */\r
        pipeline: function (fns, initialValue, scope) {\r
            if (scope == null) {\r
                scope = null;\r
            }\r
\r
            return Deferred.reduce(fns, function (value, fn) {\r
                if (!Ext.isFunction(fn)) {\r
                    throw new Error('Invalid parameter: expected a function.');\r
                }\r
\r
                return fn.call(scope, value);\r
            }, initialValue);\r
        },\r
\r
        /**\r
         * Traditional reduce function, similar to `Array.reduce()`, that allows input to\r
         * contain promises and/or values.\r
         *\r
         * @param {Mixed[]/Ext.promise.Promise[]/Ext.promise.Promise} values An\r
         * Array of values or Promises, or a Promise of an Array of values or Promises.\r
         * @param {Function} reduceFn A Function to call to transform each successive\r
         * item in the Array into the final reduced value.\r
         * @param {Mixed} initialValue An initial Promise or value.\r
         * @return {Ext.promise.Promise} A Promise of the reduced value.\r
         * @static\r
         */\r
        reduce: function (values, reduceFn, initialValue) {\r
            //<debug>\r
            if (!(Ext.isArray(values) || ExtPromise.is(values))) {\r
                Ext.raise('Invalid parameter: expected an Array or Promise of an Array.');\r
            }\r
\r
            if (!Ext.isFunction(reduceFn)) {\r
                Ext.raise('Invalid parameter: expected a function.');\r
            }\r
            //</debug>\r
\r
            var initialValueSpecified = arguments.length === 3;\r
\r
            return Deferred.resolved(values).then(function (promisesOrValues) {\r
                var reduceArguments = [\r
                    promisesOrValues,\r
                    function (previousValueOrPromise, currentValueOrPromise, currentIndex) {\r
                        return Deferred.resolved(previousValueOrPromise).then(function (previousValue) {\r
                            return Deferred.resolved(currentValueOrPromise).then(function (currentValue) {\r
                                return reduceFn(previousValue, currentValue, currentIndex, promisesOrValues);\r
                            });\r
                        });\r
                    }\r
                ];\r
\r
                if (initialValueSpecified) {\r
                    reduceArguments.push(initialValue);\r
                }\r
\r
                return Ext.Array.reduce.apply(Ext.Array, reduceArguments);\r
            });\r
        },\r
\r
        /**\r
         * Convenience method that returns a new Promise rejected with the specified\r
         * reason.\r
         *\r
         * @param {Error} reason Rejection reason.\r
         * @return {Ext.promise.Promise} The rejected Promise.\r
         * @static\r
         */\r
        rejected: function (reason) {\r
            var deferred = new Ext.Deferred();\r
\r
            deferred.reject(reason);\r
\r
            return deferred.promise;\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
         * @param {Mixed} promiseOrValue A Promise (or third-party Promise or then()-able)\r
         * or value.\r
         * @return {Ext.promise.Promise} A Promise of the specified Promise or value.\r
         * @static\r
         */\r
        resolved: function (value) {\r
            var deferred = new Ext.Deferred();\r
\r
            deferred.resolve(value);\r
\r
            return deferred.promise;\r
        },\r
\r
        /**\r
         * Execute an Array (or {@link Ext.promise.Promise Promise} of an Array) of\r
         * functions sequentially.\r
         *\r
         * The specified functions may optionally return their results as {@link\r
         * Ext.promise.Promise Promises}.\r
         *\r
         * @param {Function[]/Ext.promise.Promise} fns The Array (or Promise of an Array)\r
         * of functions to execute.\r
         * @param {Object} scope Optional scope in which to execute the specified functions.\r
         * @return {Ext.promise.Promise} Promise of an Array of results for each function\r
         * call (in the same order).\r
         * @static\r
         */\r
        sequence: function (fns, scope) {\r
            if (scope == null) {\r
                scope = null;\r
            }\r
\r
            var args = Ext.Array.slice(arguments, 2);\r
\r
            return Deferred.reduce(fns, function (results, fn) {\r
                if (!Ext.isFunction(fn)) {\r
                    throw new Error('Invalid parameter: expected a function.');\r
                }\r
\r
                return Deferred.resolved(fn.apply(scope, args)).then(function (result) {\r
                    results.push(result);\r
\r
                    return results;\r
                });\r
            }, []);\r
        },\r
\r
        /**\r
         * Initiates a competitive race, returning a new Promise that will resolve when\r
         * `howMany` of the specified `promisesOrValues` have resolved, or will reject\r
         * when it becomes impossible for `howMany` to resolve.\r
         *\r
         * The resolution value will be an Array of the first `howMany` values of\r
         * `promisesOrValues` to resolve.\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
         * @param {Number} howMany The expected number of resolved values.\r
         * @return {Ext.promise.Promise} A Promise of the expected number of resolved\r
         * values.\r
         * @static\r
         */\r
        some: function (promisesOrValues, howMany) {\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
\r
            if (!Ext.isNumeric(howMany) || howMany <= 0) {\r
                Ext.raise('Invalid parameter: expected a positive integer.');\r
            }\r
            //</debug>\r
\r
            return Deferred.resolved(promisesOrValues).then(function (promisesOrValues) {\r
                var deferred, index, onReject, onResolve, promiseOrValue,\r
                    remainingToReject, remainingToResolve, values, i, len;\r
\r
                values = [];\r
                remainingToResolve = howMany;\r
                remainingToReject = (promisesOrValues.length - remainingToResolve) + 1;\r
                deferred = new Deferred();\r
\r
                if (promisesOrValues.length < howMany) {\r
                    deferred.reject(new Error('Too few Promises were resolved.'));\r
                }\r
                else {\r
                    onResolve = function (value) {\r
                        if (remainingToResolve > 0) {\r
                            values.push(value);\r
                        }\r
\r
                        remainingToResolve--;\r
\r
                        if (remainingToResolve === 0) {\r
                            deferred.resolve(values);\r
                        }\r
\r
                        return value;\r
                    };\r
\r
                    onReject = function (reason) {\r
                        remainingToReject--;\r
\r
                        if (remainingToReject === 0) {\r
                            deferred.reject(new Error('Too few Promises were resolved.'));\r
                        }\r
\r
                        return reason;\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
                            Deferred.resolved(promiseOrValue).then(onResolve, onReject);\r
                        }\r
                    }\r
                }\r
\r
                return deferred.promise;\r
            });\r
        },\r
\r
        /**\r
         * Returns a new Promise that will automatically reject after the specified\r
         * timeout (in milliseconds) if the specified promise has not resolved or\r
         * rejected.\r
         *\r
         * @param {Mixed} promiseOrValue A Promise or value.\r
         * @param {Number} milliseconds A timeout duration (in milliseconds).\r
         * @return {Ext.promise.Promise} A Promise of the specified Promise or value that\r
         * enforces the specified timeout.\r
         * @static\r
         */\r
        timeout: function (promiseOrValue, milliseconds) {\r
            var deferred = new Deferred(),\r
                timeoutId;\r
\r
            timeoutId = setTimeout(function () {\r
                if (timeoutId) {\r
                    deferred.reject(new Error('Promise timed out.'));\r
                }\r
            }, milliseconds);\r
\r
            Deferred.resolved(promiseOrValue).then(function (value) {\r
                clearTimeout(timeoutId);\r
                timeoutId = null;\r
                deferred.resolve(value);\r
            }, function (reason) {\r
                clearTimeout(timeoutId);\r
                timeoutId = null;\r
                deferred.reject(reason);\r
            });\r
\r
            return deferred.promise;\r
        }\r
    }\r
}},\r
function (Deferred) {\r
    Deferred._ready();\r
});\r