diff --git a/lib/events.js b/lib/events.js index 77db8a28fdb241..4a6e2c3a3ac5ff 100644 --- a/lib/events.js +++ b/lib/events.js @@ -79,6 +79,11 @@ const lazyDOMException = hideStackFrames((message, name) => { }); +/** + * Creates a new `EventEmitter` instance. + * @param {{ captureRejections?: boolean; }} [opts] + * @returns {EventEmitter} + */ function EventEmitter(opts) { EventEmitter.init.call(this, opts); } @@ -161,6 +166,12 @@ ObjectDefineProperties(EventEmitter, { } }); +/** + * Sets the max listeners. + * @param {number} n + * @param {EventTarget[] | EventEmitter[]} [eventTargets] + * @returns {void} + */ EventEmitter.setMaxListeners = function(n = defaultMaxListeners, ...eventTargets) { if (typeof n !== 'number' || n < 0 || NumberIsNaN(n)) @@ -255,8 +266,11 @@ function emitUnhandledRejectionOrErr(ee, err, type, args) { } } -// Obviously not all Emitters should be limited to 10. This function allows -// that to be increased. Set to zero for unlimited. +/** + * Increases the max listeners of the event emitter. + * @param {number} n + * @returns {EventEmitter} + */ EventEmitter.prototype.setMaxListeners = function setMaxListeners(n) { if (typeof n !== 'number' || n < 0 || NumberIsNaN(n)) { throw new ERR_OUT_OF_RANGE('n', 'a non-negative number', n); @@ -271,6 +285,10 @@ function _getMaxListeners(that) { return that._maxListeners; } +/** + * Returns the current max listener value for the event emitter. + * @returns {number} + */ EventEmitter.prototype.getMaxListeners = function getMaxListeners() { return _getMaxListeners(this); }; @@ -321,6 +339,13 @@ function enhanceStackTrace(err, own) { return err.stack + sep + ownStack.join('\n'); } +/** + * Synchronously calls each of the listeners registered + * for the event. + * @param {string | symbol} type + * @param {...any} [args] + * @returns {boolean} + */ EventEmitter.prototype.emit = function emit(type, ...args) { let doError = (type === 'error'); @@ -462,12 +487,25 @@ function _addListener(target, type, listener, prepend) { return target; } +/** + * Adds a listener to the event emitter. + * @param {string | symbol} type + * @param {Function} listener + * @returns {EventEmitter} + */ EventEmitter.prototype.addListener = function addListener(type, listener) { return _addListener(this, type, listener, false); }; EventEmitter.prototype.on = EventEmitter.prototype.addListener; +/** + * Adds the `listener` function to the beginning of + * the listeners array. + * @param {string | symbol} type + * @param {Function} listener + * @returns {EventEmitter} + */ EventEmitter.prototype.prependListener = function prependListener(type, listener) { return _addListener(this, type, listener, true); @@ -491,6 +529,12 @@ function _onceWrap(target, type, listener) { return wrapped; } +/** + * Adds a one-time `listener` function to the event emitter. + * @param {string | symbol} type + * @param {Function} listener + * @returns {EventEmitter} + */ EventEmitter.prototype.once = function once(type, listener) { checkListener(listener); @@ -498,6 +542,13 @@ EventEmitter.prototype.once = function once(type, listener) { return this; }; +/** + * Adds a one-time `listener` function to the beginning of + * the listeners array. + * @param {string | symbol} type + * @param {Function} listener + * @returns {EventEmitter} + */ EventEmitter.prototype.prependOnceListener = function prependOnceListener(type, listener) { checkListener(listener); @@ -506,7 +557,12 @@ EventEmitter.prototype.prependOnceListener = return this; }; -// Emits a 'removeListener' event if and only if the listener was removed. +/** + * Removes the specified `listener` from the listeners array. + * @param {string | symbol} type + * @param {Function} listener + * @returns {EventEmitter} + */ EventEmitter.prototype.removeListener = function removeListener(type, listener) { checkListener(listener); @@ -560,6 +616,13 @@ EventEmitter.prototype.removeListener = EventEmitter.prototype.off = EventEmitter.prototype.removeListener; +/** + * Removes all listeners from the event emitter. (Only + * removes listeners for a specific event name if specified + * as `type`). + * @param {string | symbol} [type] + * @returns {EventEmitter} + */ EventEmitter.prototype.removeAllListeners = function removeAllListeners(type) { const events = this._events; @@ -623,14 +686,34 @@ function _listeners(target, type, unwrap) { unwrapListeners(evlistener) : arrayClone(evlistener); } +/** + * Returns a copy of the array of listeners for the event name + * specified as `type`. + * @param {string | symbol} type + * @returns {Function[]} + */ EventEmitter.prototype.listeners = function listeners(type) { return _listeners(this, type, true); }; +/** + * Returns a copy of the array of listeners and wrappers for + * the event name specified as `type`. + * @param {string | symbol} type + * @returns {Function[]} + */ EventEmitter.prototype.rawListeners = function rawListeners(type) { return _listeners(this, type, false); }; +/** + * Returns the number of listeners listening to the event name + * specified as `type`. + * @deprecated since v3.2.0 + * @param {EventEmitter} emitter + * @param {string | symbol} type + * @returns {number} + */ EventEmitter.listenerCount = function(emitter, type) { if (typeof emitter.listenerCount === 'function') { return emitter.listenerCount(type); @@ -639,6 +722,13 @@ EventEmitter.listenerCount = function(emitter, type) { }; EventEmitter.prototype.listenerCount = listenerCount; + +/** + * Returns the number of listeners listening to event name + * specified as `type`. + * @param {string | symbol} type + * @returns {number} + */ function listenerCount(type) { const events = this._events; @@ -655,6 +745,11 @@ function listenerCount(type) { return 0; } +/** + * Returns an array listing the events for which + * the emitter has registered listeners. + * @returns {any[]} + */ EventEmitter.prototype.eventNames = function eventNames() { return this._eventsCount > 0 ? ReflectOwnKeys(this._events) : []; }; @@ -682,6 +777,13 @@ function unwrapListeners(arr) { return ret; } +/** + * Returns a copy of the array of listeners for the event name + * specified as `type`. + * @param {EventEmitter | EventTarget} emitterOrTarget + * @param {string | symbol} type + * @returns {Function[]} + */ function getEventListeners(emitterOrTarget, type) { // First check if EventEmitter if (typeof emitterOrTarget.listeners === 'function') { @@ -704,6 +806,14 @@ function getEventListeners(emitterOrTarget, type) { emitterOrTarget); } +/** + * Creates a `Promise` that is fulfilled when the emitter + * emits the given event. + * @param {EventEmitter} emitter + * @param {string} name + * @param {{ signal: AbortSignal; }} [options] + * @returns {Promise} + */ async function once(emitter, name, options = {}) { const signal = options?.signal; validateAbortSignal(signal, 'options.signal'); @@ -801,6 +911,13 @@ function eventTargetAgnosticAddListener(emitter, name, listener, flags) { } } +/** + * Returns an `AsyncIterator` that iterates `event` events. + * @param {EventEmitter} emitter + * @param {string | symbol} event + * @param {{ signal: AbortSignal; }} [options] + * @returns {AsyncIterator} + */ function on(emitter, event, options) { const signal = options?.signal; validateAbortSignal(signal, 'options.signal');