FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

typings: add JSDoc typings for events · nodejs/node@6ea1368 · GitHub

/ node Public

Commit 6ea1368

Browse files
VoltrexKeyva
authored and
richardlau
committed
typings: add JSDoc typings for events
Added JSDoc typings for the `events` lib module. PR-URL: #38712 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Masashi Hirano <shisama07@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent 2d32031 commit 6ea1368

1 file changed

Lines changed: 120 additions & 3 deletions

File tree

‎lib/events.js‎

Lines changed: 120 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,11 @@ const lazyDOMException = hideStackFrames((message, name) => {
7979
});
8080

8181

82+
/**
83+
* Creates a new `EventEmitter` instance.
84+
* @param {{ captureRejections?: boolean; }} [opts]
85+
* @returns {EventEmitter}
86+
*/
8287
function EventEmitter(opts) {
8388
EventEmitter.init.call(this, opts);
8489
}
@@ -161,6 +166,12 @@ ObjectDefineProperties(EventEmitter, {
161166
}
162167
});
163168

169+
/**
170+
* Sets the max listeners.
171+
* @param {number} n
172+
* @param {EventTarget[] | EventEmitter[]} [eventTargets]
173+
* @returns {void}
174+
*/
164175
EventEmitter.setMaxListeners =
165176
function(n = defaultMaxListeners, ...eventTargets) {
166177
if (typeof n !== 'number' || n < 0 || NumberIsNaN(n))
@@ -255,8 +266,11 @@ function emitUnhandledRejectionOrErr(ee, err, type, args) {
255266
}
256267
}
257268

258-
// Obviously not all Emitters should be limited to 10. This function allows
259-
// that to be increased. Set to zero for unlimited.
269+
/**
270+
* Increases the max listeners of the event emitter.
271+
* @param {number} n
272+
* @returns {EventEmitter}
273+
*/
260274
EventEmitter.prototype.setMaxListeners = function setMaxListeners(n) {
261275
if (typeof n !== 'number' || n < 0 || NumberIsNaN(n)) {
262276
throw new ERR_OUT_OF_RANGE('n', 'a non-negative number', n);
@@ -271,6 +285,10 @@ function _getMaxListeners(that) {
271285
return that._maxListeners;
272286
}
273287

288+
/**
289+
* Returns the current max listener value for the event emitter.
290+
* @returns {number}
291+
*/
274292
EventEmitter.prototype.getMaxListeners = function getMaxListeners() {
275293
return _getMaxListeners(this);
276294
};
@@ -321,6 +339,13 @@ function enhanceStackTrace(err, own) {
321339
return err.stack + sep + ownStack.join('\n');
322340
}
323341

342+
/**
343+
* Synchronously calls each of the listeners registered
344+
* for the event.
345+
* @param {string | symbol} type
346+
* @param {...any} [args]
347+
* @returns {boolean}
348+
*/
324349
EventEmitter.prototype.emit = function emit(type, ...args) {
325350
let doError = (type === 'error');
326351

@@ -462,12 +487,25 @@ function _addListener(target, type, listener, prepend) {
462487
return target;
463488
}
464489

490+
/**
491+
* Adds a listener to the event emitter.
492+
* @param {string | symbol} type
493+
* @param {Function} listener
494+
* @returns {EventEmitter}
495+
*/
465496
EventEmitter.prototype.addListener = function addListener(type, listener) {
466497
return _addListener(this, type, listener, false);
467498
};
468499

469500
EventEmitter.prototype.on = EventEmitter.prototype.addListener;
470501

502+
/**
503+
* Adds the `listener` function to the beginning of
504+
* the listeners array.
505+
* @param {string | symbol} type
506+
* @param {Function} listener
507+
* @returns {EventEmitter}
508+
*/
471509
EventEmitter.prototype.prependListener =
472510
function prependListener(type, listener) {
473511
return _addListener(this, type, listener, true);
@@ -491,13 +529,26 @@ function _onceWrap(target, type, listener) {
491529
return wrapped;
492530
}
493531

532+
/**
533+
* Adds a one-time `listener` function to the event emitter.
534+
* @param {string | symbol} type
535+
* @param {Function} listener
536+
* @returns {EventEmitter}
537+
*/
494538
EventEmitter.prototype.once = function once(type, listener) {
495539
checkListener(listener);
496540

497541
this.on(type, _onceWrap(this, type, listener));
498542
return this;
499543
};
500544

545+
/**
546+
* Adds a one-time `listener` function to the beginning of
547+
* the listeners array.
548+
* @param {string | symbol} type
549+
* @param {Function} listener
550+
* @returns {EventEmitter}
551+
*/
501552
EventEmitter.prototype.prependOnceListener =
502553
function prependOnceListener(type, listener) {
503554
checkListener(listener);
@@ -506,7 +557,12 @@ EventEmitter.prototype.prependOnceListener =
506557
return this;
507558
};
508559

509-
// Emits a 'removeListener' event if and only if the listener was removed.
560+
/**
561+
* Removes the specified `listener` from the listeners array.
562+
* @param {string | symbol} type
563+
* @param {Function} listener
564+
* @returns {EventEmitter}
565+
*/
510566
EventEmitter.prototype.removeListener =
511567
function removeListener(type, listener) {
512568
checkListener(listener);
@@ -560,6 +616,13 @@ EventEmitter.prototype.removeListener =
560616

561617
EventEmitter.prototype.off = EventEmitter.prototype.removeListener;
562618

619+
/**
620+
* Removes all listeners from the event emitter. (Only
621+
* removes listeners for a specific event name if specified
622+
* as `type`).
623+
* @param {string | symbol} [type]
624+
* @returns {EventEmitter}
625+
*/
563626
EventEmitter.prototype.removeAllListeners =
564627
function removeAllListeners(type) {
565628
const events = this._events;
@@ -623,14 +686,34 @@ function _listeners(target, type, unwrap) {
623686
unwrapListeners(evlistener) : arrayClone(evlistener);
624687
}
625688

689+
/**
690+
* Returns a copy of the array of listeners for the event name
691+
* specified as `type`.
692+
* @param {string | symbol} type
693+
* @returns {Function[]}
694+
*/
626695
EventEmitter.prototype.listeners = function listeners(type) {
627696
return _listeners(this, type, true);
628697
};
629698

699+
/**
700+
* Returns a copy of the array of listeners and wrappers for
701+
* the event name specified as `type`.
702+
* @param {string | symbol} type
703+
* @returns {Function[]}
704+
*/
630705
EventEmitter.prototype.rawListeners = function rawListeners(type) {
631706
return _listeners(this, type, false);
632707
};
633708

709+
/**
710+
* Returns the number of listeners listening to the event name
711+
* specified as `type`.
712+
* @deprecated since v3.2.0
713+
* @param {EventEmitter} emitter
714+
* @param {string | symbol} type
715+
* @returns {number}
716+
*/
634717
EventEmitter.listenerCount = function(emitter, type) {
635718
if (typeof emitter.listenerCount === 'function') {
636719
return emitter.listenerCount(type);
@@ -639,6 +722,13 @@ EventEmitter.listenerCount = function(emitter, type) {
639722
};
640723

641724
EventEmitter.prototype.listenerCount = listenerCount;
725+
726+
/**
727+
* Returns the number of listeners listening to event name
728+
* specified as `type`.
729+
* @param {string | symbol} type
730+
* @returns {number}
731+
*/
642732
function listenerCount(type) {
643733
const events = this._events;
644734

@@ -655,6 +745,11 @@ function listenerCount(type) {
655745
return 0;
656746
}
657747

748+
/**
749+
* Returns an array listing the events for which
750+
* the emitter has registered listeners.
751+
* @returns {any[]}
752+
*/
658753
EventEmitter.prototype.eventNames = function eventNames() {
659754
return this._eventsCount > 0 ? ReflectOwnKeys(this._events) : [];
660755
};
@@ -682,6 +777,13 @@ function unwrapListeners(arr) {
682777
return ret;
683778
}
684779

780+
/**
781+
* Returns a copy of the array of listeners for the event name
782+
* specified as `type`.
783+
* @param {EventEmitter | EventTarget} emitterOrTarget
784+
* @param {string | symbol} type
785+
* @returns {Function[]}
786+
*/
685787
function getEventListeners(emitterOrTarget, type) {
686788
// First check if EventEmitter
687789
if (typeof emitterOrTarget.listeners === 'function') {
@@ -704,6 +806,14 @@ function getEventListeners(emitterOrTarget, type) {
704806
emitterOrTarget);
705807
}
706808

809+
/**
810+
* Creates a `Promise` that is fulfilled when the emitter
811+
* emits the given event.
812+
* @param {EventEmitter} emitter
813+
* @param {string} name
814+
* @param {{ signal: AbortSignal; }} [options]
815+
* @returns {Promise}
816+
*/
707817
async function once(emitter, name, options = {}) {
708818
const signal = options?.signal;
709819
validateAbortSignal(signal, 'options.signal');
@@ -801,6 +911,13 @@ function eventTargetAgnosticAddListener(emitter, name, listener, flags) {
801911
}
802912
}
803913

914+
/**
915+
* Returns an `AsyncIterator` that iterates `event` events.
916+
* @param {EventEmitter} emitter
917+
* @param {string | symbol} event
918+
* @param {{ signal: AbortSignal; }} [options]
919+
* @returns {AsyncIterator}
920+
*/
804921
function on(emitter, event, options) {
805922
const signal = options?.signal;
806923
validateAbortSignal(signal, 'options.signal');

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL