typings: add JSDoc typings for events

Added JSDoc typings for the `events` lib module. PR-URL: #38712 Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Masashi Hirano <[email protected]> Reviewed-By: James M Snell <[email protected]>

Author: VoltrexKeyva

lib/events.js

@@ -79,6 +79,11 @@ const kMaxEventTargetListeners = Symbol('events.maxEventTargetListeners');
 constkMaxEventTargetListenersWarned=
 Symbol('events.maxEventTargetListenersWarned');
 
+/**
+ * Creates a new `EventEmitter` instance.
+ * @param{{captureRejections?: boolean}} [opts]
+ * @returns{EventEmitter}
+ */
 functionEventEmitter(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(typeofn!=='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=functionsetMaxListeners(n){
 if(typeofn!=='number'||n<0||NumberIsNaN(n)){
 thrownewERR_OUT_OF_RANGE('n','a non-negative number',n);
@@ -263,6 +277,10 @@ function _getMaxListeners(that){
 returnthat._maxListeners;
 }
 
+/**
+ * Returns the current max listener value for the event emitter.
+ * @returns{number}
+ */
 EventEmitter.prototype.getMaxListeners=functiongetMaxListeners(){
 return_getMaxListeners(this);
 };
@@ -315,6 +333,13 @@ function enhanceStackTrace(err, own){
 returnerr.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=functionemit(type, ...args){
 letdoError=(type==='error');
 
@@ -456,12 +481,25 @@ function _addListener(target, type, listener, prepend){
 returntarget;
 }
 
+/**
+ * Adds a listener to the event emitter.
+ * @param{string | symbol} type
+ * @param{Function} listener
+ * @returns{EventEmitter}
+ */
 EventEmitter.prototype.addListener=functionaddListener(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=
 functionprependListener(type,listener){
 return_addListener(this,type,listener,true);
@@ -485,13 +523,26 @@ function _onceWrap(target, type, listener){
 returnwrapped;
 }
 
+/**
+ * Adds a one-time `listener` function to the event emitter.
+ * @param{string | symbol} type
+ * @param{Function} listener
+ * @returns{EventEmitter}
+ */
 EventEmitter.prototype.once=functiononce(type,listener){
 checkListener(listener);
 
 this.on(type,_onceWrap(this,type,listener));
 returnthis;
 };
 
+/**
+ * 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=
 functionprependOnceListener(type,listener){
 checkListener(listener);
@@ -500,7 +551,12 @@ EventEmitter.prototype.prependOnceListener =
 returnthis;
 };
 
-// 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=
 functionremoveListener(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=
 functionremoveAllListeners(type){
 constevents=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=functionlisteners(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=functionrawListeners(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(typeofemitter.listenerCount==='function'){
 returnemitter.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}
+ */
 functionlistenerCount(type){
 constevents=this._events;
 
@@ -649,6 +739,11 @@ function listenerCount(type){
 return0;
 }
 
+/**
+ * Returns an array listing the events for which
+ * the emitter has registered listeners.
+ * @returns{any[]}
+ */
 EventEmitter.prototype.eventNames=functioneventNames(){
 returnthis._eventsCount>0 ? ReflectOwnKeys(this._events) : [];
 };
@@ -676,6 +771,13 @@ function unwrapListeners(arr){
 returnret;
 }
 
+/**
+ * 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[]}
+ */
 functiongetEventListeners(emitterOrTarget,type){
 // First check if EventEmitter
 if(typeofemitterOrTarget.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}
+ */
 asyncfunctiononce(emitter,name,options={}){
 constsignal=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}
+ */
 functionon(emitter,event,options){
 constsignal=options?.signal;
 validateAbortSignal(signal,'options.signal');