add extjs 6.0.1 sources

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

/*\r
 Ext.promise.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
\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
 * 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
 * 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
 * @private\r
 * @since 6.0.0\r
 */\r
Ext.define('Ext.promise.Deferred', {\r
    requires: [\r
        'Ext.promise.Consequence'\r
    ],\r
\r
    /**\r
     * @property {Ext.promise.Promise} promise Promise of the future value of this Deferred.\r
     */\r
    promise: null,\r
\r
    /**\r
     * @property {Ext.promise.Consequence[]} consequences Pending Consequences chained to this Deferred.\r
     *\r
     * @private\r
     */\r
    consequences: [],\r
\r
    /**\r
     * @property {Boolean} completed Indicates whether this Deferred has been completed.\r
     *\r
     * @private\r
     */\r
    completed: false,\r
\r
    /**\r
     * @property {String} completeAction The completion action (i.e. 'fulfill' or 'reject').\r
     *\r
     * @private\r
     */\r
    completionAction: null,\r
\r
    /**\r
     * @property {Mixed} completionValue The completion value (i.e. resolution value or rejection error).\r
     *\r
     * @private\r
     */\r
    completionValue: null,\r
\r
    constructor: function() {\r
        var me = this;\r
\r
        me.promise = new Ext.promise.Promise(me);\r
        me.consequences = [];\r
        me.completed = false;\r
        me.completionAction = null;\r
        me.completionValue = null;\r
    },\r
\r
    /**\r
     * Used to specify onFulfilled and onRejected callbacks that will be\r
     * notified when the future value becomes available.\r
     *\r
     * Those callbacks can subsequently transform the value that was\r
     * fulfilled or the error that was rejected. Each call to `then`\r
     * returns a new Promise of that transformed value; i.e., a Promise\r
     * that is fulfilled with the callback return value or rejected with\r
     * any error thrown by the callback.\r
     *\r
     * @param {Function} [onFulfilled] Callback to execute to transform a fulfillment value.\r
     * @param {Function} [onRejected] Callback to execute to transform a rejection reason.\r
     * @param {Function} [onProgress] Callback to execute to transform a progress value.\r
     *\r
     * @return Promise that is fulfilled with the callback return value or rejected with\r
     * any error thrown by the callback.\r
     */\r
    then: function(onFulfilled, onRejected, onProgress) {\r
        var me = this,\r
            consequence = new Ext.promise.Consequence(onFulfilled, onRejected, onProgress);\r
\r
        if (me.completed) {\r
            consequence.trigger(me.completionAction, me.completionValue);\r
        }\r
        else {\r
            me.consequences.push(consequence);\r
        }\r
\r
        return consequence.promise;\r
    },\r
\r
    /**\r
     * Resolve this Deferred with the (optional) specified value.\r
     *\r
     * If 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\r
     * result; the Deferred provides its own `resolve` and `reject` methods\r
     * as the onFulfilled or onRejected arguments in a call to that\r
     * then-able's `then` function.  If an error is thrown while calling\r
     * the then-able's `then` function (prior to any call back to the\r
     * specified `resolve` or `reject` methods), the Deferred rejects with\r
     * that error. If a Deferred's `resolve` method is called with its own\r
     * Promise, it rejects with a TypeError.\r
     *\r
     * Once a Deferred has been fulfilled or rejected, it is considered to be complete\r
     * and subsequent calls to `resolve` or `reject` are ignored.\r
     *\r
     * @param {Mixed} value Value to resolve as either a fulfillment value or rejection\r
     * reason.\r
     */\r
    resolve: function(value) {\r
        var me = this,\r
            isHandled, thenFn;\r
\r
        if (me.completed) {\r
            return;\r
        }\r
\r
        try {\r
            if (value === me.promise) {\r
                throw new TypeError('A Promise cannot be resolved with itself.');\r
            }\r
\r
            if ((Ext.isObject(value) || Ext.isFunction(value)) &&\r
                        Ext.isFunction(thenFn = value.then)) {\r
                isHandled = false;\r
\r
                try {\r
                    thenFn.call(value, function(value) {\r
                        if (!isHandled) {\r
                            isHandled = true;\r
                            me.resolve(value);\r
                        }\r
                    }, function(error) {\r
                        if (!isHandled) {\r
                            isHandled = true;\r
                            me.reject(error);\r
                        }\r
                    });\r
                }\r
                catch (e) {\r
                    if (!isHandled) {\r
                        me.reject(e);\r
                    }\r
                }\r
            }\r
            else {\r
                me.complete('fulfill', value);\r
            }\r
        }\r
        catch (e) {\r
            me.reject(e);\r
        }\r
    },\r
\r
    /**\r
     * Reject this Deferred with the specified reason.\r
     *\r
     * Once a Deferred has been rejected, it is considered to be complete\r
     * and subsequent calls to `resolve` or `reject` are ignored.\r
     *\r
     * @param {Error} reason Rejection reason.\r
     */\r
    reject: function(reason) {\r
        if (this.completed) {\r
            return;\r
        }\r
        \r
        this.complete('reject', reason);\r
    },\r
\r
    /**\r
     * Updates progress for this Deferred, if it is still pending, triggering it to\r
     * execute the `onProgress` callback and propagate the resulting transformed progress\r
     * value to Deferreds that originate from this Deferred.\r
     *\r
     * @param {Mixed} progress The progress value.\r
     */\r
    update: function(progress) {\r
        var consequences = this.consequences,\r
            consequence, i, len;\r
        \r
        if (this.completed) {\r
            return;\r
        }\r
        \r
        for (i = 0, len = consequences.length; i < len; i++) {\r
            consequence = consequences[i];\r
            consequence.update(progress);\r
        }\r
    },\r
\r
    /**\r
     * Complete this Deferred with the specified action and value.\r
     *\r
     * @param {String} action Completion action (i.e. 'fufill' or 'reject').\r
     * @param {Mixed} value Fulfillment value or rejection reason.\r
     *\r
     * @private\r
     */\r
    complete: function(action, value) {\r
        var me = this,\r
            consequences = me.consequences,\r
            consequence, i, len;\r
\r
        me.completionAction = action;\r
        me.completionValue = value;\r
        me.completed = true;\r
\r
        for (i = 0, len = consequences.length; i < len; i++) {\r
            consequence = consequences[i];\r
            consequence.trigger(me.completionAction, me.completionValue);\r
        }\r
\r
        me.consequences = null;\r
    }\r
});\r