co模块源码学习笔记

// Sorrow.X --- 添加注释,注释纯属个人理解
/**
 * slice变量 引用 数组的 slice方法
 */
var slice = Array.prototype.slice;

/**
 * 抛出 `co`.
 */
// module.exports = co['default'] = co.co = co;

/**
 * Wrap the given generator `fn` into a
 * function that returns a promise.
 * This is a separate function so that
 * every `co()` call doesn't create a new,
 * unnecessary closure.
 *
 * @param {GeneratorFunction} fn
 * @return {Function}
 * @api public
 */
co.wrap = function (fn) {
    createPromise.__generatorFunction__ = fn;
    return createPromise;
    function createPromise() {
        return co.call(this, fn.apply(this, arguments));
    };
};

/**
 * 执行 generator 函数 且返回一个promise对象
 * @param {Function} fn
 * @return {Promise}
 * @api public
 */
function co(gen) {
    var ctx = this;    // 存储上下文环境
    var args = slice.call(arguments, 1);    // 提取除了第一个参数的其他参数值(数组)
    var count = 0;

    // 我们用 promise 把参数转成 promise实例 来 避免 promise链,
    // 这会导致内存泄漏错误.
    // see https://github.com/tj/co/issues/180
    return new Promise(function(resolve, reject) {
        if (typeof gen === 'function') gen = gen.apply(ctx, args);    // 判断gen是否为函数, 是的话执行一下
        if (!gen || typeof gen.next !== 'function') return resolve(gen);    // 如果gen不是generator函数, 则直接返回gen函数的执行结果

        onFulfilled();    // 首次执行gen.next()方法

        /**
         * 执行gen遍历器对象 的next方法
         * @param {Mixed} res  next方法的参数 作为上一个异步的结果
         * @return {Promise}
         * @api private
         */
        function onFulfilled(res) {
            var ret;    // 对象 {value: 紧跟yield后面表达式的值, done: generator函数是否执行完毕}
            try {
                // console.log('成功开始');
                ret = gen.next(res);    // 调用遍历器gen对象的next方法
                // console.log('成功执行');
            } catch (e) {
                return reject(e);    // 捕获 异常
            };
            // console.log('成功next开始');
            next(ret);    
        };

        /**
         * 执行gen遍历器对象 的throw方法
         * @param {Error} err
         * @return {Promise}
         * @api private
         */
        function onRejected(err) {
            var ret;
            try {
                // console.log('错误开始');
                ret = gen.throw(err);    // generator函数体外抛出错误(如果generator函数体内有try catch则被generator函数体内捕获,如果没有则就被下面的这个catch捕获, 如果都没有的话则直接中断generator函数执行撒)
            } catch (e) {
                return reject(e);    // 捕获 异常 (此异常会被返回的promise实例的.catch((e)=>{console.error(e)})捕获)
            };
            // console.log('失败next开始');
            next(ret);
        };

        /**
         * 得到gen.next()方法的值(该值的value是promise实例),然后执行promise实例的then方法,为了交回generator的执行权,
         * 返回一个promise(注: promise的then和catch方法返回的都是新的promise实例哈)
         * @param {Object} ret    ret: 对象 {value: 紧跟yield后面表达式的值, done: generator函数是否执行完毕}
         * @return {Promise}
         * @api private
         */
        function next(ret) {
            if (ret.done)    // generator函数执行完毕的话, 则调用resolve方法
                return resolve(ret.value);    
            var value = toPromise.call(ctx, ret.value);    // 把ret.value值转换成promise实例
            if (value && isPromise(value))    // 如果value是promise实例的话,则执行promise实例的then方法,成功的话,继续调用onFulfilled,这样就达到了自动执行的目的
                return value.then(onFulfilled, onRejected);    // 等待异步完成后再通过onFulfilled函数把执行权交给generator函数, 如果异步失败则调用onRejected,不会继续执行generator容器剩下的异步操作
            return onRejected(new TypeError('You may only yield a function, promise, generator, array, or object, '
                              + 'but the following object was passed: "' + String(ret.value) + '"'));    // 值不是promise则调用onRejected方法,也不会继续执行generator容器剩下的异步操作了
        };
    });
};

/**
 * 把 yield后面的表达式转换成 promise实例
 * @param {Mixed} obj
 * @return {Promise}
 * @api private
 */
function toPromise(obj) {
    if (!obj) return obj;    // 如果是假值, 则直接返回
    if (isPromise(obj)) return obj;    // 如果是promise的话, 则直接返回
    if (isGeneratorFunction(obj) || isGenerator(obj)) return co.call(this, obj);    // 如果obj是个generator函数的话,则递归下去
    if ('function' == typeof obj) return thunkToPromise.call(this, obj);    // 把thunk函数转换成promise实例
    if (Array.isArray(obj)) return arrayToPromise.call(this, obj);    // obj如果是数组,则把数组中每个成员都转成promise
    if (isObject(obj)) return objectToPromise.call(this, obj);
    return obj;
};

/**
 * 把thunk函数转换成promise实例
 * @param {Function}
 * @return {Promise}
 * @api private
 */
function thunkToPromise(fn) {
    var ctx = this;    // 存一下上下文环境
    return new Promise(function (resolve, reject) {    // 返回一个promise
        fn.call(ctx, function (err, res) {
            if (err) return reject(err);    // 回调第一个参数有错误就reject
            if (arguments.length > 2) res = slice.call(arguments, 1);    // 去掉第一个err参数,把剩下的参数放入数组中
            resolve(res);    // 成功回调并把res作为参数传过去
        });
    });
}

/**
 * 数组中每个成员都转成promise, 使用Promise.all并发执行每个promise
 * @param {Array} obj
 * @return {Promise}
 * @api private
 */
function arrayToPromise(obj) {
    return Promise.all(obj.map(toPromise, this));
};

/**
 * Convert an object of "yieldables" to a promise.
 * Uses `Promise.all()` internally.
 *
 * @param {Object} obj
 * @return {Promise}
 * @api private
 */
function objectToPromise(obj){
    var results = new obj.constructor();    // 得到一个空对象
    var keys = Object.keys(obj);    // 获取obj对象的所有属性名
    var promises = [];    // promise数组集合
    for (var i = 0; i < keys.length; i++) {    // 遍历对象属性
        var key = keys[i];    // obj对象属性名
        var promise = toPromise.call(this, obj[key]);    // 把key对应的属性值转成promise
        if (promise && isPromise(promise)) defer(promise, key);    // 如果属性值是promise, 就推到promises数组中去
        else results[key] = obj[key];
    };
    return Promise.all(promises).then(function () {    // 还是使用Promise.all并行执行
        return results;
    });

    function defer(promise, key) {
        // predefine the key in the result
        results[key] = undefined;
        promises.push(promise.then(function (res) {
            results[key] = res;
        }));
    };
};

/**
 * 检查obj是否是一个promise, 根据obj的then属性是否是函数来判断
 * @param {Object} obj
 * @return {Boolean}
 * @api private
 */
function isPromise(obj) {
    return 'function' == typeof obj.then;
};

/**
 * 检查obj是否是遍历器对象(其实就是generator函数生成的遍历器)
 * @param {Mixed} obj
 * @return {Boolean}
 * @api private
 */
function isGenerator(obj) {
    return 'function' == typeof obj.next && 'function' == typeof obj.throw;
};

/**
 * 检查obj是不是generator函数
 * @param {Mixed} obj
 * @return {Boolean}
 * @api private
 */
function isGeneratorFunction(obj) {
    var constructor = obj.constructor;    // generator函数的constructor就是GeneratorFunction函数(constructor: GeneratorFunction函数)
    if (!constructor) return false;    // 如果假值, 则直接return
    if ('GeneratorFunction' === constructor.name || 'GeneratorFunction' === constructor.displayName) return true;   // constructor函数的name属性为GeneratorFunction或者displayName属性为'GeneratorFunction' 则obj就是Generator函数
    return isGenerator(constructor.prototype);    // 检查constructor.prototype是否是遍历器对象
};

/**
 * 检查val是不是一个普通对象
 * @param {Mixed} val
 * @return {Boolean}
 * @api private
 */
function isObject(val) {
    return Object == val.constructor;
};