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;
};