【原創】when.js2.7.1源碼解析

現在，用回調處理一些復雜的邏輯，顯得代碼臃腫，難於閱讀，特別是異步，嵌套。

解決這樣的問題，可以是之前所說的Backbone.Events的pubsub，或者是今天要說的when.js所實現的promise。

在前端，jQuery的ajax全面改寫就是為了引入promise這一套，為了使代碼更流暢，更易於維護，事實上更容易實現復雜的需求。

jQuery Deferred所實現的promise並不是那么的規范，功能也並不能么全，在前端可以很方便的使用就是了，那么在后端（nodejs），我推薦

使用when.js，它的接口清晰，功能強大，架構更是很精妙，並且它在實現了完整的Promise A＋后，又添加了好多擴展功能，使得在實際應用中，

能夠很方便的寫出優秀的代碼。

所以對於這樣強大的代碼，當然是要去讀一遍，學學作者的架構思路，花了幾天時間閱讀，對源代碼進行了中文注釋講解（其中有放一些例子），

就貼在下面了，可能會有點長（看源代碼都需要耐心嘛），如果有錯誤還望指證出來，多謝啦～

 

/** @license MIT License (c) copyright 2011-2013 original author or authors */

/**
 * A lightweight CommonJS Promises/A and when() implementation
 * when is part of the cujo.js family of libraries (http://cujojs.com/)
 *
 * Licensed under the MIT License at:
 * http://www.opensource.org/licenses/mit-license.php
 *
 * @author Brian Cavalier
 * @author John Hann
 * @version 2.7.1
 */
 // 首先是規范的兼容AMD（比如requirejs）和CMD（比如nodejs）
(function(define) { 'use strict';
define(function (require) {

    // Public API
    // 接口很明確就是以下這些
    // 首先promise對象擁有的三個狀態：pending, resolved(fulfilled), rejected
    // 再然后需要理解promise對象和defer對象的關系
    // 可以簡單的理解為：defer對象內置了一個promise對象
    // 它擁有兩個接口resolve和reject來控制promise對象的最終的狀態，從而進行異步操作的處理
    when.promise   = promise;    // Create a pending promise（創建一個狀態還是pending的promise對象）
    when.resolve   = resolve;    // Create a resolved promise （創建一個狀態已經是resolved的promise對象）
    when.reject    = reject;     // Create a rejected promise（創建一個狀態已經是resolved的promise對象）
    when.defer     = defer;      // Create a {promise, resolver} pair（創建一個defer對象）

    when.join      = join;       // Join 2 or more promises（解決多個promiseOrValue對象，與all想死）

    when.all       = all;        // Resolve a list of promises（等待所有promise都resolve，新的promise才resolve）
    when.map       = map;        // Array.map() for promises （類似數組的map）
    when.reduce    = reduce;     // Array.reduce() for promises（類似數組的reduce）
    when.settle    = settle;     // Settle a list of promises（處理promiseOrValue數組，返回state數組）

    when.any       = any;        // One-winner race（一個promiseOrValue resolve，新的promiseresolve）
    when.some      = some;       // Multi-winner race（some個promiseOrValue resolve，新的promiseresolve）

    when.isPromise = isPromiseLike;  // DEPRECATED: use isPromiseLike
    when.isPromiseLike = isPromiseLike; // Is something promise-like, aka thenable 

    /**
     * Register an observer for a promise or immediate value.
     *
     * @param {*} promiseOrValue
     * @param {function?} [onFulfilled] callback to be called when promiseOrValue is
     *   successfully fulfilled.  If promiseOrValue is an immediate value, callback
     *   will be invoked immediately.
     * @param {function?} [onRejected] callback to be called when promiseOrValue is
     *   rejected.
     * @param {function?} [onProgress] callback to be called when progress updates
     *   are issued for promiseOrValue.
     * @returns {Promise} a new {@link Promise} that will complete with the return
     *   value of callback or errback or the completion value of promiseOrValue if
     *   callback and/or errback is not supplied.
     */

    // 官方的解釋是：為一個promise對象或者立即數注冊一個觀察者
    // 其實簡單點就是
    // 當promiseOrValue為resolved狀態時，onRejected回調被調用
    // 1. 當promiseOrValue被resolve時，onFulfilled回調被調用
    // 2. 當promise為reject狀態時，onRejected回調被調用
    // 3. 當promise為notify狀態時，onProgress回調被調用
    // 注意：
    // 上述的第一點用的promiseOrValue，這里的value指的是立即數，立即數使得生成promise對象開始就是resolved狀態
    // 另外這里的promiseOrValue也可以是一個數組（即[promiseOrValue1, promiseOrValue2, ...]）
    function when(promiseOrValue, onFulfilled, onRejected, onProgress) {
        // Get a trusted promise for the input promiseOrValue, and then
        // register promise handlers
        // 首先這里先對promiseOrValue進行轉換（cast方法），將其轉變為promise對象
        // 然后調用promise對象的then方法，並將用戶提供的參數傳遞給then方法，等待被調用
        // 最后返回then方法創建的新的promise對象，這樣來維持鏈式
        // 而且onFulfilled一般是函數，返回的值將作為形參傳遞給下一個onFulfilled，
        // 但如果不是函數那么onFulfilled的理應接受的參數將繼續傳遞給下一個onFulfilled，
        // 也就是說可以繼續這樣調用：
        // when('hello', 'notFunction').then(function (v) {
        //     console.log(v);// 這里的v就是hello
        // });
        return cast(promiseOrValue).then(onFulfilled, onRejected, onProgress);
    }

    /**
     * Creates a new promise whose fate is determined by resolver.
     * @param {function} resolver function(resolve, reject, notify)
     * @returns {Promise} promise whose fate is determine by resolver
     */
     // 創建一個promise對象，它的最終狀態又resolver函數決定，為什么？
     // 因為resovler函數作為用戶自定義函數會被傳遞三個形參，就是promise對象的三個內置改變狀態的接口
     // when.promise(function (reslove, reject, notify) {
     //    resolve('xxx'); // fn1 被調用
     //    //reject('xxx');  // fn2 被調用
     //    //notify('xxx');  // fn3 被調用

     // }).then(fn1, fn2, fn3);
    function promise(resolver) {
        // 實質是調用Promise構造函數
        // 這里的PromiseStatus不是很清楚，好像是when/monitor下的文件，應該是輔助文件吧，
        // 可以先不用管
        return new Promise(resolver,
            monitorApi.PromiseStatus && monitorApi.PromiseStatus());
    }

    /**
     * Trusted Promise constructor.  A Promise created from this constructor is
     * a trusted when.js promise.  Any other duck-typed promise is considered
     * untrusted.
     * @constructor
     * @returns {Promise} promise whose fate is determine by resolver
     * @name Promise
     */
     // Promise構造器
     // resolver上面已經說過，是一個函數
     // status暫時先不管，跟程序主體關系不大
    function Promise(resolver, status) {
        var self, value, consumers = [];

        self = this;
        this._status = status;
        this.inspect = inspect;
        this._when = _when;

        // Call the provider resolver to seal the promise's fate
        // 調用使用者提供的resolver函數，並將操作該promise對象“命運”的三個接口函數傳遞給resolver函數
        // 利用try catch 捕獲異常，畢竟resolver函數是使用者自定義的
        // 如果異常將該promise對象reject
        // 其實這里是有些疑問的？如果該異常出現在promise對象resolve或者reject之后，
        // 這里catch里的reject就毫無用處了（畢竟promise的最終狀態是不可以改變的）
        try {
            resolver(promiseResolve, promiseReject, promiseNotify);
        } catch(e) {
            promiseReject(e);
        }

        /**
         * Returns a snapshot of this promise's current status at the instant of call
         * @returns {{state:String}}
         */
         // inspect函數用來查看當前promise對象的狀態以及相關的值
        function inspect() {
            //這里的value有三種情況：
            // pending時，為undefined
            // resolved時，是FulfilledPromise的實例
            // rejected時，是FulfilledPromise的實例
            // 所以在非空時這才有了對應的inspect方法
            return value ? value.inspect() : toPendingState();
        }

        /**
         * Private message delivery. Queues and delivers messages to
         * the promise's ultimate fulfillment value or rejection reason.
         * @private
         */
         // 這里的_when私有函數起到至關重要的作用。
         // 這里它利用consumers和enqueue數組存儲經過封裝后的callback，不同的是：
         // consumers里的callback是等待該promise對象resolve或者reject后執行
         // enqueue里的callback是等待下個tick執行，或者說是延時執行（此時該promise對象已經resolved或者rejected了）
         // 另外巧妙通過閉包實現了對onFulfilled，onRejected，onProgress的訪問，
         // 而無需像jQuery Deferrred那樣通過創建維護三個隊列存儲callback
        function _when(resolve, notify, onFulfilled, onRejected, onProgress) {
            // 通過consumers參數判斷該promise對象是否已經有了最終狀態（即resolved或者rejected）
            // resloved(rejected)了，加入隊列在下一個時間周期等待執行
            // pending狀態，存儲起來在，等待適當的時候被執行（reslove或者reject的時候）
            consumers ? consumers.push(deliver) : enqueue(function() { deliver(value); });

            function deliver(p) {
                // 這里的p依然有三種值
                // 1. 處於pending狀態的promise對象
                //    這種情苦發生在onFulfilled返回一個處於pending狀態的promie對象，
                //   利用p._when關聯之后的promise對象從而繼續完成同步操作
                // 如：（雖然異步，但是卻是同步的寫法，免去了callback的嵌套）
                // when.promise(function () {
                //     var defer = when.defer();
                //     setTimout(function () {
                //         defer.resolve('xx');
                //     }, 50)
                // }).then(function (val) {
                //         console.log(val); // xx
                // });
                // 2. FulfilledPromise對象
                // 3. RejectedPromise對象
                // 所以這里的p._when調用的方法出處各有不同
                p._when(resolve, notify, onFulfilled, onRejected, onProgress);
            }
        }

        /**
         * Transition from pre-resolution state to post-resolution state, notifying
         * all listeners of the ultimate fulfillment or rejection
         * @param {*} val resolution value
         */
        // 當前promise對象的resolve接口
        function promiseResolve(val) {
            // val的值可以是有四種值
            // 1. 立即數（經過coerce處理最終變為FulfilledPromise對象）
            // 2. promise對象
            // 3. RejectedPromise對象（僅供內部傳遞，因為RejectedPromise是未暴露的函數類）
            // 3. FulfilledPromise對象（僅供內部傳遞）
            // 同樣給出一個例子：
            // when.promise(function (resolve) {

            //     // resolve('hello'); // 情況一立即數

            //     var defer = when.defer();

            //     setTimeout(function () { // 情況二promise對象，同樣可以將setTimeout去掉試試
            //         defer.resolve('hello');
            //         // defer.reject('hello');
            //     }, 200);

            //     resolve(defer.promise);
            // }).then(function (value) {
            //      console.log(value); // hello
            // });

            // consumers用來判斷promise對象是否有了最終狀態（即pending->resolved/rejected）
            // 因為根據Promises/A+規范規定，prmoise對象的最終狀態是不可變的
            // 也就是說resolve和reject只會被執行一次
            if(!consumers) {
                return;
            }

            // 將consumers置為undefined表示promise對象已經resolve或者reject了
            var queue = consumers;
            consumers = undef;

            // 將當前要執行的任務入隊列，等待下一個時刻執行，將異步進行到底
            enqueue(function () {
                // coerce進行val的轉換
                // 轉換為promise對象或者promise的子類RejectedPromise/FulfilledPromise的實例
                // 傳遞給value，value很重要，作為最終的值，之后回通過必包傳遞給一個關聯回調
                value = coerce(self, val);
                if(status) {
                    updateStatus(value, status);
                }
                // 運行consumers里傳遞過來的函數隊列
                runHandlers(queue, value);
            });
        }

        /**
         * Reject this promise with the supplied reason, which will be used verbatim.
         * @param {*} reason reason for the rejection
         */
         // 當前promise對象的reject接口
         // 實質還是利用resolve的接口，只不過是主動傳遞RejectedPromise的實例
        function promiseReject(reason) {
            promiseResolve(new RejectedPromise(reason));
        }

        /**
         * Issue a progress event, notifying all progress listeners
         * @param {*} update progress event payload to pass to all listeners
         */
         // notify就是一個進度提示，這在做一些進度方面的組件是很有用戶體驗的，比如flash uploader
         // 顯然既然是進度，那么首先promise對象是必須還處於pending狀態，notify才會有效
         // 所以consumers必須不為空
         // 給個例子：
        // when.promise(function (resolve, reject, notify) {

        //     var counter = 0;
        //     var timer = setInterval(function () {
        //         counter++;
        //         notify(counter);

        //         if (counter === 10) {
        //             resolve('over');
        //             clearInterval(timer);
        //         }
        //     }, 1);
        // }).then(function (value) {
        //     console.log(value);
        // }, undefined, function (update) {
        //     console.log(update);
        // });
        // 結果是 1 2 3 4 5 6 7 8 9 10 over
        function promiseNotify(update) {
            if(consumers) {
                var queue = consumers;
                enqueue(function () {
                    runHandlers(queue, new ProgressingPromise(update));
                });
            }
        }
    }

    // 接下來是Promise的原型方法，最重要的就是then方法
    promisePrototype = Promise.prototype;

    /**
     * Register handlers for this promise.
     * @param [onFulfilled] {Function} fulfillment handler
     * @param [onRejected] {Function} rejection handler
     * @param [onProgress] {Function} progress handler
     * @return {Promise} new Promise
     */
     // then方法是Promises/A+的核心，也是鏈式的關鍵，用來注冊三種回調
     // 通過調用_when的私有方法能做到以下幾點：
     // 1. 進行callback的注冊
     // 2. 創建新的promise對象（newPromise）並返回，繼續鏈式下去
     // 3. 將newPromise對象的決定權（即三個內置接口）交付給調用then方法的promise對象（即與之關聯在一起）
    promisePrototype.then = function(onFulfilled, onRejected, onProgress) {
        var self = this;

        return new Promise(function(resolve, reject, notify) {
            self._when(resolve, notify, onFulfilled, onRejected, onProgress);
        }, this._status && this._status.observed());
    };

    /**
     * Register a rejection handler.  Shortcut for .then(undefined, onRejected)
     * @param {function?} onRejected
     * @return {Promise}
     */
     // 很明顯內部調用了then方法，只傳遞了onRejected函數
     // 其實相當於promise.then(undef, onRejected)的快捷鍵
    promisePrototype['catch'] = promisePrototype.otherwise = function(onRejected) {
        return this.then(undef, onRejected);
    };

    /**
     * Ensures that onFulfilledOrRejected will be called regardless of whether
     * this promise is fulfilled or rejected.  onFulfilledOrRejected WILL NOT
     * receive the promises' value or reason.  Any returned value will be disregarded.
     * onFulfilledOrRejected may throw or return a rejected promise to signal
     * an additional error.
     * @param {function} onFulfilledOrRejected handler to be called regardless of
     *  fulfillment or rejection
     * @returns {Promise}
     */
     // finally和ensure方法保證promise對象無論什么狀態的情況下，最終都會執行onFulfilledOrRejected
     // 但是onFulfilledOrRejected是不帶任何參數的
     // 另外，finally(ensure)方法如果后面繼續鏈式，添加then方法，最終執行是與該promise對象相關的，並且接受
     // promise對象的resolve的value值和reject的reason值（與finally的返回值無關，除非onFulfilledOrRejected
     // 回調報出異常或者返回rejected的promise對象）
     // 舉個例子：
    // var when = require('when');
    // var defer = when.defer();

    // defer.promise.finally(function () {
    //     console.log(arguments);     // {}

    //     var defer2 = when.defer();
    //     defer2.reject('xxx');

    //     return defer2.promise;
    // }).then(function (value) {
    //     console.log('value: ' + value);
    // }, function (reason) {
    //     console.log('reason: ' + reason); // reason: xxx
    // });
    // defer.resolve('hello');
    promisePrototype['finally'] = promisePrototype.ensure = function(onFulfilledOrRejected) {
        // 這里利用yield(this)，試圖將接下來的newPromise對象的控制權交給當前的promise對象
        return typeof onFulfilledOrRejected === 'function'
            ? this.then(injectHandler, injectHandler)['yield'](this)
            : this;

        function injectHandler() {
            // 這里是為了配合yield方法，試圖想返回一個resolved的promise對象
            // 但是onFulfilledOrRejected()，如果發生異常，或者返回rejectedpromise對象
            // 將會使得結果與當前promise對象的狀態無關了，就像上面代碼沒有輸出hello一樣
            return resolve(onFulfilledOrRejected());
        }
    };

    /**
     * Terminate a promise chain by handling the ultimate fulfillment value or
     * rejection reason, and assuming responsibility for all errors.  if an
     * error propagates out of handleResult or handleFatalError, it will be
     * rethrown to the host, resulting in a loud stack track on most platforms
     * and a crash on some.
     * @param {function?} handleResult
     * @param {function?} handleError
     * @returns {undefined}
     */
     // done方法有兩個作用：
     // 1. 結束鏈式
     // 2. 異常處理
     // 如下：
    // var when = require('when');
    // var defer = when.defer();

    // defer.promise.done(function () {
    //     console.log(arguments)
    // }, function (value) {
    //     var defer = when.defer();
    //     defer.reject(value)
    //     return defer.promise();
    // });
    // defer.reject('world');
    // 將會報出程序異常，結束程序執行
    promisePrototype.done = function(handleResult, handleError) {
        this.then(handleResult, handleError)['catch'](crash);
    };

    /**
     * Shortcut for .then(function() { return value; })
     * @param  {*} value
     * @return {Promise} a promise that:
     *  - is fulfilled if value is not a promise, or
     *  - if value is a promise, will fulfill with its value, or reject
     *    with its reason.
     */
     // 該方法傳遞了value參數（用於閉包訪問），內部調用了then方法，只傳遞了onFulfilled回調
     // value值可以是立即數也是是promise對象
     // 當調用yield方法的originalPromise被rejected，返回的newPromise對象也會因為同樣的reason被rejected
     // 而當originalPromise被resolved時，要分為兩種情況：
     // 1. 當value為立即數，那么newPromise對象將被resolved，且被傳遞value值
     // 2. 當value為promise對象，那么返回的newPromise的命運（最后狀態）將由value的狀態決定，且被傳遞promise對象
     // resolved的value值，或者rejected的reason值
     // 總結，清楚then方法就可以很容易看清，yield內部通過只傳遞了onFulfilled回調，這個是關鍵因素
     // 來個例子：
    // var defer = when.defer();
    // var defer2 = when.defer();

    // defer.promise.yield(defer2.promise).then(function (value) {
    //     console.log('value: ' + value);
    // }, function (reason) {
    //     console.log('reason: ' + reason);
    // });

    // defer.reject('hello');
    // // defer.resolve('hello');

    // defer2.resolve('world');
    // // defer2.reject('world');

    // 結果：當defer->resolve&&defer2->resolve，輸出value: world
    //      當defer->resolve&&defer2->rejected，輸出reason: world
    //      當defer->rejected(跟defer2無關)，輸出reason: hello

    promisePrototype['yield'] = function(value) {
        return this.then(function() {
            return value;
        });
    };

    /**
     * Runs a side effect when this promise fulfills, without changing the
     * fulfillment value.
     * @param {function} onFulfilledSideEffect
     * @returns {Promise}
     */
     // 1. 當promise對象resolved時，onFulfilledSideEffect被執行，對於onFulfilledSideEffect的返回值
     // 沒有任何意義，會被無視原因時因為['yield'](this)這句，迫使后面的promise對象與當前promise對象關聯
     // 在一起，傳入后面callback的值也是當前promise對象resovle的value，或者reject的reason，但是如果
     // onFulfilledSideEffect拋出異常或者返回rejected的promise對象，那么將會觸發之后promise對象
     // 的onRejected回調，並傳入異常信息
     // 2. 當promise對象rejected時，onFulfilledSideEffect不會被執行，之后的promise對象的onRejected回調
     // 會被觸發，並被傳入當前promise對象reject的reason
     // 例如：
    // var defer = when.defer();

    // defer.promise.tap(function (value) {

    //     return 'good';
    // }).then(function (value) {
    //     console.log('value: ' + value); // value: hello
    // }, function (reason) {
    //     console.log('reason: ' + reason);
    // });
    // defer.resolve('hello');
    // 總結：上述的輸出並不會因為我return了good而改變接下來輸出的value值
    promisePrototype.tap = function(onFulfilledSideEffect) {
        return this.then(onFulfilledSideEffect)['yield'](this);
    };

    /**
     * Assumes that this promise will fulfill with an array, and arranges
     * for the onFulfilled to be called with the array as its argument list
     * i.e. onFulfilled.apply(undefined, array).
     * @param {function} onFulfilled function to receive spread arguments
     * @return {Promise}
     */
    promisePrototype.spread = function(onFulfilled) {
        return this.then(function(array) {
            // array may contain promises, so resolve its contents.
            return all(array, function(array) {
                return onFulfilled.apply(undef, array);
            });
        });
    };

    /**
     * Shortcut for .then(onFulfilledOrRejected, onFulfilledOrRejected)
     * @deprecated
     */
     // 即將被廢棄，可用finally（ensure）代替
    promisePrototype.always = function(onFulfilledOrRejected, onProgress) {
        return this.then(onFulfilledOrRejected, onFulfilledOrRejected, onProgress);
    };

    /**
     * Casts x to a trusted promise. If x is already a trusted promise, it is
     * returned, otherwise a new trusted Promise which follows x is returned.
     * @param {*} x
     * @returns {Promise}
     */
    function cast(x) {
        return x instanceof Promise ? x : resolve(x);
    }

    /**
     * Returns a resolved promise. The returned promise will be
     *  - fulfilled with promiseOrValue if it is a value, or
     *  - if promiseOrValue is a promise
     *    - fulfilled with promiseOrValue's value after it is fulfilled
     *    - rejected with promiseOrValue's reason after it is rejected
     * In contract to cast(x), this always creates a new Promise
     * @param  {*} value
     * @return {Promise}
     */
     // 內部調用when.promise方法，創建一個狀態為resolved的promise對象
     // 值得注意的是這里的value可以是一個promise對象
     // 像這樣：
     // var defer = when.defer();
     // when.resolve(defer.promise).then(function (val) {
     //     console.log(val); // hello
     // });
     // defer.resolve('hello');
    function resolve(value) {
        return promise(function(resolve) {
            resolve(value);
        });
    }

    /**
     * Returns a rejected promise for the supplied promiseOrValue.  The returned
     * promise will be rejected with:
     * - promiseOrValue, if it is a value, or
     * - if promiseOrValue is a promise
     *   - promiseOrValue's value after it is fulfilled
     *   - promiseOrValue's reason after it is rejected
     * @param {*} promiseOrValue the rejected value of the returned {@link Promise}
     * @return {Promise} rejected {@link Promise}
     */
     // 看到這里，可能會疑惑為什么代碼是這樣的？而不是這樣的：
     // function reject(promiseOrValue) {
     //     return promise(function(resolve, reject) {
     //         reject(value);
     //     });
     // }
     // 問題在與reject方法只能接受字符串reason，然后構造成RejectedPromise實例，
     // 不想resolve方法那樣能夠接受promise對象
     // 為了滿足同樣能將promise對象作為參數，利用when內部處理promiseOrValue
     // 例如：
     // var defer = when.defer();

     // when.reject(defer.promise).then(function (value) {
     //     console.log('value: ' + value);
     // }, function (reason) {
     //     console.log('reason: ' + reason); // reason: bad/good
     // });

     // // defer.reject('bad');
     // defer.resolve('good');
     // 無論你的promise最終resolve還是reject，最終都是執行onRejected回調。
     // 這里有個巧妙的地方就是
     // 當resolve的時候，會利用下面的new RejectedPromise(e)來生成RejectedPromise對象
     // 傳遞給下promise對象的resolve接口，進而執行onRejected
     // 當reject時，會自動生成RejectedPromise對象，下面的new RejectedPromise(e)並不會被調用
    function reject(promiseOrValue) {
        return when(promiseOrValue, function(e) {
            return new RejectedPromise(e);
        });
    }

    /**
     * Creates a {promise, resolver} pair, either or both of which
     * may be given out safely to consumers.
     * The resolver has resolve, reject, and progress.  The promise
     * has then plus extended promise API.
     *
     * @return {{
     * promise: Promise,
     * resolve: function:Promise,
     * reject: function:Promise,
     * notify: function:Promise
     * resolver: {
     *    resolve: function:Promise,
     *    reject: function:Promise,
     *    notify: function:Promise
     * }}}
     */
     // defer函數用來返回一個deferred對象
     // 內部包含promise對象以及操縱promise對象狀態的三個接口
     // 所以說deferred對象會改變promise的狀態，而promise（defer.promise）對象時不可以改變自身的狀態,
     // 這就相當於jQuery Deferred中所謂的“受限制的deferred對象”
    function defer() {
        // deferred表示即將返回給用戶的deferred對象
        // pending可以理解為deferred.promise的別名，簡單高效
        // resolved表示該deferred是否已經reject或者resolve了
        var deferred, pending, resolved;

        // Optimize object shape
        // 包裝一下
        deferred = {
            promise: undef, resolve: undef, reject: undef, notify: undef,
            resolver: { resolve: undef, reject: undef, notify: undef }
        };

        // 創建promise對象，將控制權交給makeDeferred函數
        deferred.promise = pending = promise(makeDeferred);

        return deferred;

        // 給deferred對象添加三個控制promise對象的接口
        function makeDeferred(resolvePending, rejectPending, notifyPending) {
            deferred.resolve = deferred.resolver.resolve = function(value) {
                // 對於已經resolved的情況
                // 根據傳遞進來的value創建已經新的resolved的promise對象
                // 可以說已經與當前的promise對象已經沒關系了
                if(resolved) {
                    return resolve(value);
                }
                resolved = true;
                // 執行promise對象的resolve
                resolvePending(value);
                // 返回resolved的promise對象，保持鏈式，被傳遞的值resolve時的只
                return pending;
            };

            // reject同上
            deferred.reject  = deferred.resolver.reject  = function(reason) {
                if(resolved) {
                    return resolve(new RejectedPromise(reason));
                }
                resolved = true;
                rejectPending(reason);
                return pending;
            };

            deferred.notify  = deferred.resolver.notify  = function(update) {
                notifyPending(update);
                return update;
            };
        }
    }

    /**
     * Run a queue of functions as quickly as possible, passing
     * value to each.
     */
     // 簡單的遍歷隊列，執行函數
    function runHandlers(queue, value) {
        for (var i = 0; i < queue.length; i++) {
            queue[i](value);
        }
    }

    /**
     * Coerces x to a trusted Promise
     * @param {*} x thing to coerce
     * @returns {*} Guaranteed to return a trusted Promise.  If x
     *   is trusted, returns x, otherwise, returns a new, trusted, already-resolved
     *   Promise whose resolution value is:
     *   * the resolution value of x if it's a foreign promise, or
     *   * x if it's a value
     */
     // 將x轉換為對應的可信任的promise對象
    function coerce(self, x) {
        if (x === self) {
            return new RejectedPromise(new TypeError());
        }

        // 已經是promise對象，直接返回
        // 比如:promise的對象或者它的三個子類實例
        if (x instanceof Promise) {
            return x;
        }

        try {
            var untrustedThen = x === Object(x) && x.then;

            return typeof untrustedThen === 'function'
                ? assimilate(untrustedThen, x)
                : new FulfilledPromise(x);
        } catch(e) {
            return new RejectedPromise(e);
        }
    }

    /**
     * Safely assimilates a foreign thenable by wrapping it in a trusted promise
     * @param {function} untrustedThen x's then() method
     * @param {object|function} x thenable
     * @returns {Promise}
     */
     // 將x為obj且帶有then的函數進行封裝並傳遞resolve和reject接口
     // 返回promise對象
    function assimilate(untrustedThen, x) {
        return promise(function (resolve, reject) {
            fcall(untrustedThen, x, resolve, reject);
        });
    }

    // 對Promise的原型繼承（原生方法優先）
    makePromisePrototype = Object.create ||
        function(o) {
            function PromisePrototype() {}
            PromisePrototype.prototype = o;
            return new PromisePrototype();
        };

    /**
     * Creates a fulfilled, local promise as a proxy for a value
     * NOTE: must never be exposed
     * @private
     * @param {*} value fulfillment value
     * @returns {Promise}
     */
     // FulfilledPromise用於，當deferred.relove(value)時,對value的封裝
    function FulfilledPromise(value) {
        this.value = value;
    }

    // 原型繼承
    FulfilledPromise.prototype = makePromisePrototype(promisePrototype);

    // 返回promise的狀態
    FulfilledPromise.prototype.inspect = function() {
        return toFulfilledState(this.value);
    };

    FulfilledPromise.prototype._when = function(resolve, _, onFulfilled) {
        // 這里的resolve適用於控制下一個關聯的promise對象的
        // 並且onFulfilled會被傳遞reslove(value)中的value值
        // 如果onFulfilled有返回值，那么返回值會傳遞給下一個promise對象的回調函數
        // 另外onFulfilled也可以不是對象，那么將此時的value傳遞給下一個promise對象的回調函數
        // 對於用戶自定義的函數onFulfilled采用try catch
        try {
            resolve(typeof onFulfilled === 'function' ? onFulfilled(this.value) : this.value);
        } catch(e) {
            resolve(new RejectedPromise(e));
        }
    };

    /**
     * Creates a rejected, local promise as a proxy for a value
     * NOTE: must never be exposed
     * @private
     * @param {*} reason rejection reason
     * @returns {Promise}
     */
     // RejectedPromise用於，當deferred.reject(value)時,對value的封裝
    function RejectedPromise(reason) {
        this.value = reason;
    }

    RejectedPromise.prototype = makePromisePrototype(promisePrototype);

    RejectedPromise.prototype.inspect = function() {
        return toRejectedState(this.value);
    };

    RejectedPromise.prototype._when = function(resolve, _, __, onRejected) {
        // 這里值得注意的是在onRejected不存在時，會將this對象作為一下promise對象的回調函數
        // 保證RejectedPromise對象傳遞給下一個onRejected回調
        // 而且注意這里也是用的resolve函數，而不是想像中的reject，所以在進行then方法的
        // 鏈式調用下，如果一個promise對象resolved或rejected，它下一個promise對象會執行onFulfilled
        // 除非你當時返回的一個rejected對象
        try {
            resolve(typeof onRejected === 'function' ? onRejected(this.value) : this);
        } catch(e) {
            resolve(new RejectedPromise(e));
        }
    };

    /**
     * Create a progress promise with the supplied update.
     * @private
     * @param {*} value progress update value
     * @return {Promise} progress promise
     */
     // ProgressingPromise用於，當deferred.notify(value)時,對value的封裝
    function ProgressingPromise(value) {
        this.value = value;
    }

    ProgressingPromise.prototype = makePromisePrototype(promisePrototype);

    ProgressingPromise.prototype._when = function(_, notify, f, r, u) {
        try {
            notify(typeof u === 'function' ? u(this.value) : this.value);
        } catch(e) {
            notify(e);
        }
    };

    /**
     * Update a PromiseStatus monitor object with the outcome
     * of the supplied value promise.
     * @param {Promise} value
     * @param {PromiseStatus} status
     */
    function updateStatus(value, status) {
        value.then(statusFulfilled, statusRejected);

        function statusFulfilled() { status.fulfilled(); }
        function statusRejected(r) { status.rejected(r); }
    }

    /**
     * Determines if x is promise-like, i.e. a thenable object
     * NOTE: Will return true for *any thenable object*, and isn't truly
     * safe, since it may attempt to access the `then` property of x (i.e.
     *  clever/malicious getters may do weird things)
     * @param {*} x anything
     * @returns {boolean} true if x is promise-like
     */
     // 判斷一個對象是否like promise對象，很簡單，即判斷是否有then方法
    function isPromiseLike(x) {
        return x && typeof x.then === 'function';
    }

    /**
     * Initiates a competitive race, returning a promise that will resolve when
     * howMany of the supplied promisesOrValues have resolved, or will reject when
     * it becomes impossible for howMany to resolve, for example, when
     * (promisesOrValues.length - howMany) + 1 input promises reject.
     *
     * @param {Array} promisesOrValues array of anything, may contain a mix
     *      of promises and values
     * @param howMany {number} number of promisesOrValues to resolve
     * @param {function?} [onFulfilled] DEPRECATED, use returnedPromise.then()
     * @param {function?} [onRejected] DEPRECATED, use returnedPromise.then()
     * @param {function?} [onProgress] DEPRECATED, use returnedPromise.then()
     * @returns {Promise} promise that will resolve to an array of howMany values that
     *  resolved first, or will reject with an array of
     *  (promisesOrValues.length - howMany) + 1 rejection reasons.
     */
     // some是用來解決5個promise對象當有3個resolve時，就去執行onFulfilled
     // 如果超過3個reject時，就去執行onRejected
    function some(promisesOrValues, howMany, onFulfilled, onRejected, onProgress) {

        // 注意：之前就有說過when方法時可以傳遞promisesOrValues數組的
        return when(promisesOrValues, function(promisesOrValues) {

            return promise(resolveSome).then(onFulfilled, onRejected, onProgress);

            function resolveSome(resolve, reject, notify) {
                var toResolve, toReject, values, reasons, fulfillOne, rejectOne, len, i;

                len = promisesOrValues.length >>> 0;
                // resolve的條件
                toResolve = Math.max(0, Math.min(howMany, len));
                values = [];
                // reject的條件
                toReject = (len - toResolve) + 1;
                reasons = [];

                // No items in the input, resolve immediately
                // 空數組，直接resolve
                if (!toResolve) {
                    resolve(values);

                } else {
                    rejectOne = function(reason) {
                        // 保存reject的元素的reason信息
                        reasons.push(reason);
                        // 達到reject條件時
                        // 重置fulfillOne和rejectOne函數，不再保存接下來的數據
                        // 並reject返回的新創建的promise對象，以便執行onRejected回調
                        if(!--toReject) {
                            fulfillOne = rejectOne = identity;
                            reject(reasons);
                        }
                    };

                    fulfillOne = function(val) {
                        // This orders the values based on promise resolution order
                        // 保存resolve的元素的reason信息，順序取決於各個promise對象的resolve的先后順序
                        // 接下來與rejectOne差不多
                        values.push(val);
                        if (!--toResolve) {
                            fulfillOne = rejectOne = identity;
                            resolve(values);
                        }
                    };
                    // 遍歷promisesOrValues數組
                    for(i = 0; i < len; ++i) {
                        if(i in promisesOrValues) {
                            when(promisesOrValues[i], fulfiller, rejecter, notify);
                        }
                    }
                }

                function rejecter(reason) {
                    rejectOne(reason);
                }

                function fulfiller(val) {
                    fulfillOne(val);
                }
            }
        });
    }

    /**
     * Initiates a competitive race, returning a promise that will resolve when
     * any one of the supplied promisesOrValues has resolved or will reject when
     * *all* promisesOrValues have rejected.
     *
     * @param {Array|Promise} promisesOrValues array of anything, may contain a mix
     *      of {@link Promise}s and values
     * @param {function?} [onFulfilled] DEPRECATED, use returnedPromise.then()
     * @param {function?} [onRejected] DEPRECATED, use returnedPromise.then()
     * @param {function?} [onProgress] DEPRECATED, use returnedPromise.then()
     * @returns {Promise} promise that will resolve to the value that resolved first, or
     * will reject with an array of all rejected inputs.
     */
     // promisesOrValues數組中一個元素resolve那么執行onFulfilled，否則執行onRejected
     // 內部調用some函數，將參數howMany置為1
    function any(promisesOrValues, onFulfilled, onRejected, onProgress) {

        function unwrapSingleResult(val) {
            return onFulfilled ? onFulfilled(val[0]) : val[0];
        }

        return some(promisesOrValues, 1, unwrapSingleResult, onRejected, onProgress);
    }

    /**
     * Return a promise that will resolve only once all the supplied promisesOrValues
     * have resolved. The resolution value of the returned promise will be an array
     * containing the resolution values of each of the promisesOrValues.
     * @memberOf when
     *
     * @param {Array|Promise} promisesOrValues array of anything, may contain a mix
     *      of {@link Promise}s and values
     * @param {function?} [onFulfilled] DEPRECATED, use returnedPromise.then()
     * @param {function?} [onRejected] DEPRECATED, use returnedPromise.then()
     * @param {function?} [onProgress] DEPRECATED, use returnedPromise.then()
     * @returns {Promise}
     */
     // 與when.join功能幾乎一樣，就是傳遞參數的區別了，相見when.join
    function all(promisesOrValues, onFulfilled, onRejected, onProgress) {
        return _map(promisesOrValues, identity).then(onFulfilled, onRejected, onProgress);
    }

    /**
     * Joins multiple promises into a single returned promise.
     * @return {Promise} a promise that will fulfill when *all* the input promises
     * have fulfilled, or will reject when *any one* of the input promises rejects.
     */
     // when.join與when.map很想，都是調用_map，只不過它傳遞的時一個一個的promiseOrValue，
     // 內部通過arguments偽數組傳遞給_map
     // 而且指定函數為identity（返回每個resolve的value）
    function join(/* ...promises */) {
        return _map(arguments, identity);
    }

    /**
     * Settles all input promises such that they are guaranteed not to
     * be pending once the returned promise fulfills. The returned promise
     * will always fulfill, except in the case where `array` is a promise
     * that rejects.
     * @param {Array|Promise} array or promise for array of promises to settle
     * @returns {Promise} promise that always fulfills with an array of
     *  outcome snapshots for each input promise.
     */
     // 遍歷promiseOrValue數組，返回的新promise對象一定會resolve，除非array本身就是rejected的promise對象
     // 且不會因為其中一個promise對象reject，而導致返回的新promise對象reject，而只會記錄reject state的信息
     // 這與when.all方法時不同的
     // 可以看見內部調用了toFulfilledState和toRejectedState作為回調
     // 那么返回的promise對象在onFulfilled將得到數組所有promiseOrValue的state信息
    function settle(array) {
        return _map(array, toFulfilledState, toRejectedState);
    }

    /**
     * Promise-aware array map function, similar to `Array.prototype.map()`,
     * but input array may contain promises or values.
     * @param {Array|Promise} array array of anything, may contain promises and values
     * @param {function} mapFunc map function which may return a promise or value
     * @returns {Promise} promise that will fulfill with an array of mapped values
     *  or reject if any input promise rejects.
     */
     // 遍歷promiseOrValue數組，如果數組每個元素都resolve，那么會將每個元素在調用mapFunc時的返回值
     // 保存在一個數組內，傳遞給返回的新的promise對象的onFulfilled方法，但是，如果有一個元素reject，
     // 那么返回的那個promise對象的onRejected被調用，並接受這個元素的reason
     // 如下：
    // when.map([defer.promise, defer2.promise, 'three'], function (value) {
    //     return value;
    // }).then(function (value) {
    //     console.log(value); // [ 'first', 'second', 'three' ]
    // }, function (reason) {
    //     console.log(reason);
    // });
    // defer.resolve('first');
    // defer2.resolve('second');
    function map(array, mapFunc) {
        return _map(array, mapFunc);
    }

    /**
     * Internal map that allows a fallback to handle rejections
     * @param {Array|Promise} array array of anything, may contain promises and values
     * @param {function} mapFunc map function which may return a promise or value
     * @param {function?} fallback function to handle rejected promises
     * @returns {Promise} promise that will fulfill with an array of mapped values
     *  or reject if any input promise rejects.
     */
    function _map(array, mapFunc, fallback) {
        // 這里array是一個promiseOrValue數組
        return when(array, function(array) {
            // 返回新的promise對象
            return new Promise(resolveMap);

            function resolveMap(resolve, reject, notify) {
                var results, len, toResolve, i;

                // Since we know the resulting length, we can preallocate the results
                // array to avoid array expansions.
                toResolve = len = array.length >>> 0;
                results = [];
                // 空數組直接返回
                if(!toResolve) {
                    resolve(results);
                    return;
                }

                // Since mapFunc may be async, get all invocations of it into flight
                // 遍歷數組內的promiseOrValue
                for(i = 0; i < len; i++) {
                    // 數組元素驗證，確保元素在數組內（數組也可以是偽數組）
                    if(i in array) {

                        resolveOne(array[i], i);
                    } else {
                        --toResolve;
                    }
                }

                function resolveOne(item, i) {
                    // 通過調用when方法將mapFunc（用戶定義）函數的返回值存在results里，
                    // 等最后toResolve為0時，一起傳遞給返回的新promise對象
                    // 如果其中一個promise對象reject，那么reject返回的新promise對象
                    // 返回值將是rejected的拿個promise對象的reason
                    when(item, mapFunc, fallback).then(function(mapped) {
                        // 保存每個promise對象的結果值
                        results[i] = mapped;
                        // 當所有promise對象都處理完了，resolve返回的新promise對象
                        // 傳遞results數組
                        if(!--toResolve) {
                            resolve(results);
                        }
                    }, reject, notify);
                }
            }
        });
    }

    /**
     * Traditional reduce function, similar to `Array.prototype.reduce()`, but
     * input may contain promises and/or values, and reduceFunc
     * may return either a value or a promise, *and* initialValue may
     * be a promise for the starting value.
     *
     * @param {Array|Promise} promise array or promise for an array of anything,
     *      may contain a mix of promises and values.
     * @param {function} reduceFunc reduce function reduce(currentValue, nextValue, index, total),
     *      where total is the total number of items being reduced, and will be the same
     *      in each call to reduceFunc.
     * @returns {Promise} that will resolve to the final reduced value
     */
    function reduce(promise, reduceFunc /*, initialValue */) {
        var args = fcall(slice, arguments, 1);

        return when(promise, function(array) {
            var total;

            total = array.length;

            // Wrap the supplied reduceFunc with one that handles promises and then
            // delegates to the supplied.
            args[0] = function (current, val, i) {
                return when(current, function (c) {
                    return when(val, function (value) {
                        return reduceFunc(c, value, i, total);
                    });
                });
            };

            return reduceArray.apply(array, args);
        });
    }

    // Snapshot states

    /**
     * Creates a fulfilled state snapshot
     * @private
     * @param {*} x any value
     * @returns {{state:'fulfilled',value:*}}
     */
    function toFulfilledState(x) {
        return { state: 'fulfilled', value: x };
    }

    /**
     * Creates a rejected state snapshot
     * @private
     * @param {*} x any reason
     * @returns {{state:'rejected',reason:*}}
     */
    function toRejectedState(x) {
        return { state: 'rejected', reason: x };
    }

    /**
     * Creates a pending state snapshot
     * @private
     * @returns {{state:'pending'}}
     */
    function toPendingState() {
        return { state: 'pending' };
    }

    //
    // Internals, utilities, etc.
    //

    var promisePrototype, makePromisePrototype, reduceArray, slice, fcall, nextTick, handlerQueue,
        funcProto, call, arrayProto, monitorApi,
        capturedSetTimeout, cjsRequire, MutationObs, undef;

    cjsRequire = require;

    //
    // Shared handler queue processing
    //
    // Credit to Twisol (https://github.com/Twisol) for suggesting
    // this type of extensible queue + trampoline approach for
    // next-tick conflation.
    // task隊列
    handlerQueue = [];

    /**
     * Enqueue a task. If the queue is not currently scheduled to be
     * drained, schedule it.
     * @param {function} task
     */
     // 入隊列，這里的進行了條件判斷
     // 原因在於在異步情況下可能出現很多次enqueue調用，那么我們只對第一次入隊調用nextTick
     // 下次時間周期自然會都被調用到
    function enqueue(task) {
        if(handlerQueue.push(task) === 1) {
            nextTick(drainQueue);
        }
    }

    /**
     * Drain the handler queue entirely, being careful to allow the
     * queue to be extended while it is being processed, and to continue
     * processing until it is truly empty.
     */
     // 出隊列， 執行回調
    function drainQueue() {
        runHandlers(handlerQueue);
        handlerQueue = [];
    }

    // Allow attaching the monitor to when() if env has no console
    monitorApi = typeof console !== 'undefined' ? console : when;

    // Sniff "best" async scheduling option
    // Prefer process.nextTick or MutationObserver, then check for
    // vertx and finally fall back to setTimeout
    /*global process,document,setTimeout,MutationObserver,WebKitMutationObserver*/
    // 以下是根據宿主環境采用不同的方式到達異步
    // 優先是nodejs的process.nextTick
    // 然后是MutationObserver
    // 最后是setTimeout
    // 這里異步的好處在於什么？為什么在reslove或者reject后，沒有立即執行，而是加入隊列，
    // 這是因為中途的task還有可能加入，在下一個時間周期統一處理，會很方便，提高性能，而且這樣充分利用
    // javascript的單線程異步的特性，不會帶來任何代碼的阻塞問題
    if (typeof process === 'object' && process.nextTick) {
        nextTick = process.nextTick;
    } else if(MutationObs =
        (typeof MutationObserver === 'function' && MutationObserver) ||
            (typeof WebKitMutationObserver === 'function' && WebKitMutationObserver)) {
        nextTick = (function(document, MutationObserver, drainQueue) {
            var el = document.createElement('div');
            new MutationObserver(drainQueue).observe(el, { attributes: true });

            return function() {
                el.setAttribute('x', 'x');
            };
        }(document, MutationObs, drainQueue));
    } else {
        try {
            // vert.x 1.x || 2.x
            nextTick = cjsRequire('vertx').runOnLoop || cjsRequire('vertx').runOnContext;
        } catch(ignore) {
            // capture setTimeout to avoid being caught by fake timers
            // used in time based tests
            capturedSetTimeout = setTimeout;
            nextTick = function(t) { capturedSetTimeout(t, 0); };
        }
    }

    //
    // Capture/polyfill function and array utils
    //

    // Safe function calls
    funcProto = Function.prototype;
    call = funcProto.call;
    // 這里fcal的組合方式很有意思
    // 看下兼容代碼就能明白了
    fcall = funcProto.bind
        ? call.bind(call)
        : function(f, context) {
            return f.apply(context, slice.call(arguments, 2));
        };

    // Safe array ops
    arrayProto = [];
    slice = arrayProto.slice;

    // ES5 reduce implementation if native not available
    // See: http://es5.github.com/#x15.4.4.21 as there are many
    // specifics and edge cases.  ES5 dictates that reduce.length === 1
    // This implementation deviates from ES5 spec in the following ways:
    // 1. It does not check if reduceFunc is a Callable
    // 對[].reduce的兼容性處理
    reduceArray = arrayProto.reduce ||
        function(reduceFunc /*, initialValue */) {
            /*jshint maxcomplexity: 7*/
            var arr, args, reduced, len, i;

            i = 0;
            arr = Object(this);
            len = arr.length >>> 0;
            args = arguments;

            // If no initialValue, use first item of array (we know length !== 0 here)
            // and adjust i to start at second item
            if(args.length <= 1) {
                // Skip to the first real element in the array
                for(;;) {
                    if(i in arr) {
                        reduced = arr[i++];
                        break;
                    }

                    // If we reached the end of the array without finding any real
                    // elements, it's a TypeError
                    if(++i >= len) {
                        throw new TypeError();
                    }
                }
            } else {
                // If initialValue provided, use it
                reduced = args[1];
            }

            // Do the actual reduce
            for(;i < len; ++i) {
                if(i in arr) {
                    reduced = reduceFunc(reduced, arr[i], i, arr);
                }
            }

            return reduced;
        };

    function identity(x) {
        return x;
    }

    function crash(fatalError) {
        if(typeof monitorApi.reportUnhandled === 'function') {
            monitorApi.reportUnhandled();
        } else {
            enqueue(function() {
                throw fatalError;
            });
        }

        throw fatalError;
    }

    return when;
});
})(typeof define === 'function' && define.amd ? define : function (factory) { module.exports = factory(require); });

晚安～～