2016年12月10日 星期六

Promise

Promises/A+

An open standard for sound, interoperable JavaScript promises—by implementers, for implementers.
A promise represents the eventual result of an asynchronous operation. The primary way of interacting with a promise is through its then method, which registers callbacks to receive either a promise's eventual value or the reason why the promise cannot be fulfilled.
This specification details the behavior of the then method, providing an interoperable base which all Promises/A+ conformant promise implementations can be depended on to provide. As such, the specification should be considered very stable. Although the Promises/A+ organization may occasionally revise this specification with minor backward-compatible changes to address newly-discovered corner cases, we will integrate large or backward-incompatible changes only after careful consideration, discussion, and testing.
Historically, Promises/A+ clarifies the behavioral clauses of the earlier Promises/A proposal, extending it to cover de facto behaviors and omitting parts that are underspecified or problematic.
Finally, the core Promises/A+ specification does not deal with how to create, fulfill, or reject promises, choosing instead to focus on providing an interoperable then method. Future work in companion specifications may touch on these subjects.

Terminology

  1. "promise" is an object or function with a then method whose behavior conforms to this specification.
  2. "thenable" is an object or function that defines a then method.
  3. "value" is any legal JavaScript value (including undefined, a thenable, or a promise).
  4. "exception" is a value that is thrown using the throw statement.
  5. "reason" is a value that indicates why a promise was rejected.

Requirements

Promise States

A promise must be in one of three states: pending, fulfilled, or rejected.
  1. When pending, a promise:
    1. may transition to either the fulfilled or rejected state.
  2. When fulfilled, a promise:
    1. must not transition to any other state.
    2. must have a value, which must not change.
  3. When rejected, a promise:
    1. must not transition to any other state.
    2. must have a reason, which must not change.
Here, "must not change" means immutable identity (i.e. ===), but does not imply deep immutability.

The then Method

A promise must provide a then method to access its current or eventual value or reason.
A promise's then method accepts two arguments:
promise.then(onFulfilled, onRejected)
  1. Both onFulfilled and onRejected are optional arguments:
    1. If onFulfilled is not a function, it must be ignored.
    2. If onRejected is not a function, it must be ignored.
  2. If onFulfilled is a function:
    1. it must be called after promise is fulfilled, with promise's value as its first argument.
    2. it must not be called before promise is fulfilled.
    3. it must not be called more than once.
  3. If onRejected is a function,
    1. it must be called after promise is rejected, with promise's reason as its first argument.
    2. it must not be called before promise is rejected.
    3. it must not be called more than once.
  4. onFulfilled or onRejected must not be called until the execution context stack contains only platform code. [3.1].
  5. onFulfilled and onRejected must be called as functions (i.e. with no this value). [3.2]
  6. then may be called multiple times on the same promise.
    1. If/when promise is fulfilled, all respective onFulfilled callbacks must execute in the order of their originating calls to then.
    2. If/when promise is rejected, all respective onRejected callbacks must execute in the order of their originating calls to then.
  7. then must return a promise [3.3].
    promise2 = promise1.then(onFulfilled, onRejected);
    1. If either onFulfilled or onRejected returns a value x, run the Promise Resolution Procedure [[Resolve]](promise2, x).
    2. If either onFulfilled or onRejected throws an exception e, promise2 must be rejected with e as the reason.
    3. If onFulfilled is not a function and promise1 is fulfilled, promise2 must be fulfilled with the same value as promise1.
    4. If onRejected is not a function and promise1 is rejected, promise2 must be rejected with the same reason as promise1.

The Promise Resolution Procedure

The promise resolution procedure is an abstract operation taking as input a promise and a value, which we denote as [[Resolve]](promise, x). If x is a thenable, it attempts to make promise adopt the state of x, under the assumption that x behaves at least somewhat like a promise. Otherwise, it fulfills promise with the value x.
This treatment of thenables allows promise implementations to interoperate, as long as they expose a Promises/A+-compliant then method. It also allows Promises/A+ implementations to "assimilate" nonconformant implementations with reasonable then methods.
To run [[Resolve]](promise, x), perform the following steps:
  1. If promise and x refer to the same object, reject promise with a TypeError as the reason.
  2. If x is a promise, adopt its state [3.4]:
    1. If x is pending, promise must remain pending until x is fulfilled or rejected.
    2. If/when x is fulfilled, fulfill promise with the same value.
    3. If/when x is rejected, reject promise with the same reason.
  3. Otherwise, if x is an object or function,
    1. Let then be x.then. [3.5]
    2. If retrieving the property x.then results in a thrown exception e, reject promise with e as the reason.
    3. If then is a function, call it with x as this, first argument resolvePromise, and second argument rejectPromise, where:
      1. If/when resolvePromise is called with a value y, run [[Resolve]](promise, y).
      2. If/when rejectPromise is called with a reason r, reject promise with r.
      3. If both resolvePromise and rejectPromise are called, or multiple calls to the same argument are made, the first call takes precedence, and any further calls are ignored.
      4. If calling then throws an exception e,
        1. If resolvePromise or rejectPromise have been called, ignore it.
        2. Otherwise, reject promise with e as the reason.
    4. If then is not a function, fulfill promise with x.
  4. If x is not an object or function, fulfill promise with x.
If a promise is resolved with a thenable that participates in a circular thenable chain, such that the recursive nature of [[Resolve]](promise, thenable) eventually causes [[Resolve]](promise, thenable) to be called again, following the above algorithm will lead to infinite recursion. Implementations are encouraged, but not required, to detect such recursion and reject promise with an informative TypeError as the reason. [3.6]

Notes

  1. Here "platform code" means engine, environment, and promise implementation code. In practice, this requirement ensures that onFulfilled and onRejected execute asynchronously, after the event loop turn in which then is called, and with a fresh stack. This can be implemented with either a "macro-task" mechanism such as setTimeout or setImmediate, or with a "micro-task" mechanism such as MutationObserver or process.nextTick. Since the promise implementation is considered platform code, it may itself contain a task-scheduling queue or "trampoline" in which the handlers are called.
  2. That is, in strict mode this will be undefined inside of them; in sloppy mode, it will be the global object.
  3. Implementations may allow promise2 === promise1, provided the implementation meets all requirements. Each implementation should document whether it can produce promise2 === promise1 and under what conditions.
  4. Generally, it will only be known that x is a true promise if it comes from the current implementation. This clause allows the use of implementation-specific means to adopt the state of known-conformant promises.
  5. This procedure of first storing a reference to x.then, then testing that reference, and then calling that reference, avoids multiple accesses to the x.then property. Such precautions are important for ensuring consistency in the face of an accessor property, whose value could change between retrievals.
  6. Implementations should not set arbitrary limits on the depth of thenable chains, and assume that beyond that arbitrary limit the recursion will be infinite. Only true cycles should lead to a TypeError; if an infinite chain of distinct thenables is encountered, recursing forever is the correct behavior.

 /* ====================================================================== */
/**
 * promise
 */

(function(root) {
    debugger;

    // Store setTimeout reference so promise-polyfill will be unaffected by
    // other code modifying setTimeout (like sinon.useFakeTimers())
    var setTimeoutFunc = setTimeout;

    // 空函式
    function noop() {};

    // Polyfill for Function.prototype.bind
    function bind(fn, thisArg) {
        debugger;
        return function() {
            debugger;
            fn.apply(thisArg, arguments);
        };
    }
    /* ====================================================================== */
    /**
     * (Promise)類別
     */
    function Promise(fn) {
        'use strict';

        debugger;

        if (typeof this !== 'object') throw new TypeError('Promises must be constructed via new');
        if (typeof fn !== 'function') throw new TypeError('not a function');


        /**
         * _state = 0: 初始狀態
         * _state = 1: 正執行完
         * _state = 2: reject
         */
        this._state = 0;
        this._handled = false;
        this._value = undefined;

        this._deferreds = []; // 隊列(放置then.fn)

        doResolve(fn, this);
    };
    /* ====================================================================== */
    /**
     * 執行(Promise.fn)
     *
     * Take a potentially misbehaving resolver function and make sure
     * onFulfilled and onRejected are only called once.
     *
     * Makes no guarantees about asynchrony.
     *
     * fn => (promise)被指定要做的事
     */
    function doResolve(fn, self) {
        debugger;

        var done = false;
        /* ---------------------------------- */
        // 傳給(promise)要做的(fn)兩個參數函式(resolve, reject)
        function _resolve(value) {
            debugger;

            if (done) {
                return;
            }
            done = true;

            // 通知(promise)正卻結束
            resolve(self, value);
        };
        /* ---------------------------------- */
        function _reject(reason) {
            debugger;

            if (done) {
                return;
            }
            done = true;

            // 錯誤的下一步
            reject(self, reason);
        };
        /* ---------------------------------- */
        debugger;
        try {
            // 執行(promise)的函式
            fn(_resolve, _reject);

        } catch (ex) {
            if (done) return;
            done = true;
            reject(self, ex);
        }
    };
    /* ====================================================================== */
    /**
     * (promise)執行成功後的呼叫
     *
     * @param self => promise
     * @param newValue => (promise)正確執行後傳遞的數值
     *
     */
    function resolve(self, newValue) {
        debugger;

        try {
            // Promise Resolution Procedure: https://github.com/promises-aplus/promises-spec#the-promise-resolution-procedure
            if (newValue === self) throw new TypeError('A promise cannot be resolved with itself.');

            if (newValue && (typeof newValue === 'object' || typeof newValue === 'function')) {
                // 為了隊列而設
             
                var then = newValue.then;
                if (newValue instanceof Promise) {
                    self._state = 3;
                    self._value = newValue;

                    // here
                    finale(self);
                    return;
                } else if (typeof then === 'function') {
                    doResolve(bind(then, newValue), self);
                    return;
                }
            }
            /* ---------------------------------- */
            /**
             * important
             *
             * self = promise
             *
             * self._value => 要傳遞下去的參數
             */
            self._state = 1;
            self._value = newValue;

            // here
            finale(self);
        } catch (e) {

            // here
            reject(self, e);
        }
    };
    /* ====================================================================== */
    function reject(self, newValue) {
        debugger;

        self._state = 2;
        self._value = newValue;
        finale(self);
    };
    /* ====================================================================== */
    /**
     * 由(resolve)(reject)呼叫
     *
     * 檢查是否有待辦事項，若有交給(handle)
     *
     * @param {any} self
     */
    function finale(self) {
        debugger;

        if (self._state === 2 && self._deferreds.length === 0) {
            Promise._immediateFn(function() {
                if (!self._handled) {
                    Promise._unhandledRejectionFn(self._value);
                }
            });
        }
        // 是否有(then)隊列，等待執行
        for (var i = 0, len = self._deferreds.length; i < len; i++) {
            handle(self, self._deferreds[i]);
        }
        self._deferreds = null;
    };
    /* ====================================================================== */
    /**
     * 攜帶資料的包包
     *
     * @param onFulfilled => (then)正確執行後，onFulfilled
     * @param onRejected => (then)錯誤執行後，onRejected
     * @param promise => promise
     */
    function Handler(onFulfilled, onRejected, promise) {
        // debugger;

        this.onFulfilled = (typeof onFulfilled === 'function') ? onFulfilled : null;
        this.onRejected = (typeof onRejected === 'function') ? onRejected : null;
        this.promise = promise;
    };
    /* ====================================================================== */

    Promise.prototype['catch'] = function(onRejected) {
        debugger;

        return this.then(null, onRejected);
    };
    /* ====================================================================== */
    /**
     * API
     */
    Promise.prototype.then = function(onFulfilled, onRejected) {
        debugger;

        // promise = new Promice(function noop(){})
        var promise = new(this.constructor)(noop);

        // 攜帶資料的包包
        var _handler = new Handler(onFulfilled, onRejected, promise);

        // 執行(onFulfilled, onRejected)
        handle(this, _handler);

        return promise;
    };
    /* ====================================================================== */
    /**
     * 由(then)呼叫，執行(then)的任務
     *
     * 執行(then)指定的函式
     *
     * @param deferred => Handler(包含then要執行的事，與對象)
     */
    function handle(self, deferred) {
        debugger;

        while (self._state === 3) {
            /**
             * self._value = promise(上一個(then)的返回值)
             *
             *  原本下一個(then.fn)隸屬於上一個(then)
             *
             * 但現在改把下一個(then.fn)交給上一個(then.fn)的返回值
             */
            self = self._value;
        }

        /* ---------------------------------- */
        // 若(promise)尚未執行，把(then.fn)放入隊列
        if (self._state === 0) {
            self._deferreds.push(deferred);
            return;
        }
        /* ---------------------------------- */
        self._handled = true;

        Promise._immediateFn(function() {
            debugger;

            var do_fun = (self._state === 1) ? deferred.onFulfilled : deferred.onRejected;
            if (do_fun === null) {
                (self._state === 1 ? resolve : reject)(deferred.promise, self._value);
                return;
            }
            var ret;
            try {

                // 執行(then.fn)
                ret = do_fun(self._value);
            } catch (e) {
                reject(deferred.promise, e);
                return;
            }
            /* -----------------------------------*/
            debugger;
            resolve(deferred.promise, ret);
        });
    };
    /* ====================================================================== */
    /**
     * arr => promise
     */
    Promise.all = function(arr) {
        debugger;
        // 要執行的(promise)
        var args = Array.prototype.slice.call(arr);

        var promise = new Promise(function(resolve, reject) {
            debugger;

            if (args.length === 0) {
                // 若沒有指定任務
                return resolve([]);
            }
            // 有幾個任務
            var remaining = args.length;

            for (var i = 0; i < args.length; i++) {
                debugger;

                // 為每一個(promise)分配一個then(function res())
                res(i, args[i]);
            }
            /* -------------------------------------------- */
            /**
             * i => index
             * val => 通常是(promise)
             */
            function res(i, val) {
                debugger;

                try {
                    if (val && (typeof val === 'object' || typeof val === 'function')) {
                        var then_fun = val.then;
                        if (typeof then_fun === 'function') {
                            debugger;

                            // val = promise
                            // promise.then()
                            // (promise)處理完後呼叫(res(i, val))，告知已完成事項，並傳送結果

                            then_fun.call(val, function(value) {
                                debugger;
                                res(i, value);
                            }, reject);
                            return;
                        }
                    }
                    debugger;

                    args[i] = val;
                    if (--remaining === 0) {
                        resolve(args);
                    }
                } catch (ex) {
                    reject(ex);
                }
            };
            /* -------------------------------------------- */

        });

        return promise;
    };
    /* ====================================================================== */

    Promise.resolve = function(value) {
        debugger;

        if (value && typeof value === 'object' && value.constructor === Promise) {
            return value;
        }

        var promise = new Promise(function(__resolve) {
            debugger;
            __resolve(value);
        });

        return promise;
    };
    /* ====================================================================== */

    Promise.reject = function(value) {
        debugger;

        return new Promise(function(resolve, reject) {
            reject(value);
        });
    };
    /* ====================================================================== */

    Promise.race = function(values) {
        debugger;

        return new Promise(function(resolve, reject) {
            for (var i = 0, len = values.length; i < len; i++) {
                values[i].then(resolve, reject);
            }
        });
    };
    /* ====================================================================== */

    // Use polyfill for setImmediate for performance gains
    Promise._immediateFn = (typeof setImmediate === 'function') ?
        function(fn) {
            debugger;
            setImmediate(fn);
        } :
        function(fn) {
            debugger;
            setTimeoutFunc(fn, 0);
        };
    /* ====================================================================== */

    Promise._unhandledRejectionFn = function _unhandledRejectionFn(err) {
        debugger;
        if (typeof console !== 'undefined' && console) {
            console.warn('Possible Unhandled Promise Rejection:', err); // eslint-disable-line no-console
        }
    };
    /* ====================================================================== */

    /**
     * Set the immediate function to execute callbacks
     * @param fn {function} Function to execute
     * @deprecated
     */
    Promise._setImmediateFn = function _setImmediateFn(fn) {
        debugger;
        Promise._immediateFn = fn;
    };
    /* ====================================================================== */

    /**
     * Change the function to execute on unhandled rejection
     * @param {function} fn Function to execute on unhandled rejection
     * @deprecated
     */
    Promise._setUnhandledRejectionFn = function _setUnhandledRejectionFn(fn) {
        debugger;
        Promise._unhandledRejectionFn = fn;
    };
    /* ====================================================================== */
    debugger;

    if (typeof module !== 'undefined' && module.exports) {
        module.exports = Promise;
    } else if (!root.Promise) {
        // 若瀏覽器不支援(Promise)
        root.Promise = Promise;
    }
    // for test
    root.Promise = Promise;
})(this);




於
標籤：