From 5ce015ec72be98f064041d1bf5c3527a89c276cc Mon Sep 17 00:00:00 2001 From: Voltrex <62040526+VoltrexMaster@users.noreply.github.com> Date: Tue, 18 May 2021 03:54:16 +0430 Subject: [PATCH] typings: add JSDoc typings for events Added JSDoc typings for the `events` lib module. PR-URL: https://github.com/nodejs/node/pull/38712 Reviewed-By: Benjamin Gruenbaum Reviewed-By: Masashi Hirano Reviewed-By: James M Snell --- lib/events.js | 123 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 120 insertions(+), 3 deletions(-) diff --git a/lib/events.js b/lib/events.js index 4a21632b1cfc23..557461084631f3 100644 --- a/lib/events.js +++ b/lib/events.js @@ -79,6 +79,11 @@ const kMaxEventTargetListeners = Symbol('events.maxEventTargetListeners'); const kMaxEventTargetListenersWarned = Symbol('events.maxEventTargetListenersWarned'); +/** + * Creates a new `EventEmitter` instance. + * @param {{ captureRejections?: boolean; }} [opts] + * @returns {EventEmitter} + */ function EventEmitter(opts) { EventEmitter.init.call(this, opts); } @@ -156,6 +161,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)) @@ -247,8 +258,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); @@ -263,6 +277,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); }; @@ -315,6 +333,13 @@ function enhanceStackTrace(err, own) { return err.stack + sep + ArrayPrototypeJoin(ownStack, '\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'); @@ -456,12 +481,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); @@ -485,6 +523,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); @@ -492,6 +536,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); @@ -500,7 +551,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); @@ -554,6 +610,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; @@ -617,14 +680,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); @@ -633,6 +716,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; @@ -649,6 +739,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) : []; }; @@ -676,6 +771,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') { @@ -700,6 +802,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'); @@ -771,6 +881,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');