index.js

'use strict';

var has = Object.prototype.hasOwnProperty;

//
// We store our EE objects in a plain object whose properties are event names.
// If `Object.create(null)` is not supported we prefix the event names with a
// `~` to make sure that the built-in object properties are not overridden or
// used as an attack vector.
// We also assume that `Object.create(null)` is available when the event name
// is an ES6 Symbol.
// 我们通过一个普通的带有事件名字的属性的对象来存储EE对象。如果当前环境不支持`Object.create(null)`,
// 我们添加一个`~`作为前缀来避免覆盖掉或者被作为一个向量来使用内置的对象属性。
// 我们也认为`Object.create(null)`在事件名字是ES6关键字的时候生效
var prefix = typeof Object.create !== 'function' ? '~' : false;

/**
 * Representation of a single EventEmitter function.
 * 一个单一的事件监听函数的单元
 *
 * @param {Function} fn Event handler to be called. 回调函数
 * @param {Mixed} context Context for function execution. 函数执行上下文
 * @param {Boolean} [once=false] Only emit once 是否执行一次的标志位
 * @api private
 */
function EE(fn, context, once) {
    this.fn = fn;
    this.context = context;
    this.once = once || false;
}

/**
 * Minimal EventEmitter interface that is molded against the Node.js
 * 最小的事件模型接口
 * EventEmitter interface.
 *
 * @constructor
 * @api public
 */
function EventEmitter() { /* Nothing to set */
}

/**
 * 通过名字保存事件监听器
 * Hold the assigned EventEmitters by name.
 *
 * @type {Object}
 * @private
 */
EventEmitter.prototype._events = undefined;

/**
 * Return an array listing the events for which the emitter has registered
 * 返回已经注册过的事件名称列表
 * listeners.
 *
 * @returns {Array}
 * @api public
 */
EventEmitter.prototype.eventNames = function eventNames() {
    var events = this._events
        , names = []
        , name;

    if (!events) return names;

    for(name in events) {
        if (has.call(events, name)) names.push(prefix ? name.slice(1) : name);
    }

    if (Object.getOwnPropertySymbols) {
        return names.concat(Object.getOwnPropertySymbols(events));
    }

    return names;
};

/**
 * Return a list of assigned event listeners.
 * 返回某个事件的时间监听函数列表
 *
 * @param {String} event The events that should be listed.
 * @param {Boolean} exists We only need to know if there are listeners.
 * @returns {Array|Boolean}
 * @api public
 */
EventEmitter.prototype.listeners = function listeners(event, exists) {
    var evt = prefix ? prefix + event : event
        , available = this._events && this._events[evt];

    if (exists) return !!available;
    if (!available) return [];
    if (available.fn) return [available.fn];

    for(var i = 0, l = available.length, ee = new Array(l); i < l; i++) {
        ee[i] = available[i].fn;
    }

    return ee;
};

/**
 * Emit an event to all registered event listeners.
 * 触发已经注册的事件监听函数
 *
 * @param {String} event The name of the event. 事件名
 * @returns {Boolean} Indication if we've emitted an event. 如果触发事件成功,则返回true,否则返回false
 * @api public 公有API
 */
EventEmitter.prototype.emit = function emit(event, a1, a2, a3, a4, a5) {
    var evt = prefix ? prefix + event : event;

    if (!this._events || !this._events[evt]) return false;

    var listeners = this._events[evt]
        , len = arguments.length
        , args
        , i;

    if ('function' === typeof listeners.fn) {
        if (listeners.once) this.removeListener(event, listeners.fn, undefined, true);

        switch(len) {
            case 1:
                return listeners.fn.call(listeners.context), true;
            case 2:
                return listeners.fn.call(listeners.context, a1), true;
            case 3:
                return listeners.fn.call(listeners.context, a1, a2), true;
            case 4:
                return listeners.fn.call(listeners.context, a1, a2, a3), true;
            case 5:
                return listeners.fn.call(listeners.context, a1, a2, a3, a4), true;
            case 6:
                return listeners.fn.call(listeners.context, a1, a2, a3, a4, a5), true;
        }

        for(i = 1, args = new Array(len - 1); i < len; i++) {
            args[i - 1] = arguments[i];
        }

        listeners.fn.apply(listeners.context, args);
    } else {
        var length = listeners.length
            , j;

        for(i = 0; i < length; i++) {
            if (listeners[i].once) this.removeListener(event, listeners[i].fn, undefined, true);

            switch(len) {
                case 1:
                    listeners[i].fn.call(listeners[i].context);
                    break;
                case 2:
                    listeners[i].fn.call(listeners[i].context, a1);
                    break;
                case 3:
                    listeners[i].fn.call(listeners[i].context, a1, a2);
                    break;
                default:
                    if (!args) for(j = 1, args = new Array(len - 1); j < len; j++) {
                        args[j - 1] = arguments[j];
                    }

                    listeners[i].fn.apply(listeners[i].context, args);
            }
        }
    }

    return true;
};

/**
 * Register a new EventListener for the given event.
 * 注册一个指定的事件的事件监听函数
 *
 * @param {String} event Name of the event. 事件名
 * @param {Function} fn Callback function. 回调函数
 * @param {Mixed} [context=this] The context of the function. 上下文
 * @api public 公有API
 */
EventEmitter.prototype.on = function on(event, fn, context) {
    var listener = new EE(fn, context || this)
        , evt = prefix ? prefix + event : event;

    if (!this._events) this._events = prefix ? {} : Object.create(null);
    if (!this._events[evt]) {
        this._events[evt] = listener;//第一次存储为一个事件监听对象
    } else {
        if (!this._events[evt].fn) {//第三次及以后则直接向对象数组中添加事件监听对象
            this._events[evt].push(listener);
        } else {//第二次将存储的对象与新对象转换为事件监听对象数组
            this._events[evt] = [
                this._events[evt], listener
            ];
        }
    }

    return this;
};

/**
 * Add an EventListener that's only called once.
 * 注册一个只被调用一次的事件监听函数,与on基本一样,只是参数不同
 *
 * @param {String} event Name of the event.
 * @param {Function} fn Callback function.
 * @param {Mixed} [context=this] The context of the function.
 * @api public
 */
EventEmitter.prototype.once = function once(event, fn, context) {
    var listener = new EE(fn, context || this, true)
        , evt = prefix ? prefix + event : event;

    if (!this._events) this._events = prefix ? {} : Object.create(null);
    if (!this._events[evt]) this._events[evt] = listener;
    else {
        if (!this._events[evt].fn) this._events[evt].push(listener);
        else this._events[evt] = [
            this._events[evt], listener
        ];
    }

    return this;
};

/**
 * Remove event listeners.
 * 移除事件监听函数
 *
 * @param {String} event The event we want to remove. 需要被移除的事件名
 * @param {Function} fn The listener that we need to find. 需要被移除的事件监听函数
 * @param {Mixed} context Only remove listeners matching this context. 只移除匹配该参数指定的上下文的监听函数
 * @param {Boolean} once Only remove once listeners. 只移除匹配该参数指定的once属性的监听函数
 * @api public 公共API
 */
EventEmitter.prototype.removeListener = function removeListener(event, fn, context, once) {
    var evt = prefix ? prefix + event : event;

    if (!this._events || !this._events[evt]) return this;

    var listeners = this._events[evt]
        , events = [];

    if (fn) {
        if (listeners.fn) {
            if (
                listeners.fn !== fn
                || (once && !listeners.once)
                || (context && listeners.context !== context)
            ) {
                events.push(listeners);
            }
        } else {
            for(var i = 0, length = listeners.length; i < length; i++) {
                if (
                    listeners[i].fn !== fn
                    || (once && !listeners[i].once)
                    || (context && listeners[i].context !== context)
                ) {
                    events.push(listeners[i]);
                }
            }
        }
    }

    //
    // Reset the array, or remove it completely if we have no more listeners.
    //
    if (events.length) {
        this._events[evt] = events.length === 1 ? events[0] : events;
    } else {
        delete this._events[evt];
    }

    return this;
};

/**
 * Remove all listeners or only the listeners for the specified event.
 * 移除指定事件的全部监听函数
 *
 * @param {String} event The event want to remove all listeners for.
 * @api public
 */
EventEmitter.prototype.removeAllListeners = function removeAllListeners(event) {
    if (!this._events) return this;

    if (event) {
        delete this._events[prefix ? prefix + event : event];
    } else {
        this._events = prefix ? {} : Object.create(null);
    }

    return this;
};

//
// Alias methods names because people roll like that.
//
EventEmitter.prototype.off = EventEmitter.prototype.removeListener;
EventEmitter.prototype.addListener = EventEmitter.prototype.on;

//
// This function doesn't apply anymore.
//
EventEmitter.prototype.setMaxListeners = function setMaxListeners() {
    return this;
};

//
// Expose the prefix.
//
EventEmitter.prefixed = prefix;

//
// Expose the module.
//
if ('undefined' !== typeof module) {
    module.exports = EventEmitter;
}