【原创】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); });

晚安～～