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

晚安～～