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

typings: add JSDoc typings for events · nodejs/node@7fb809b · GitHub

/ node Public

Commit 7fb809b

Browse files
VoltrexKeyva
authored and
danielleadams
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 4e33532 commit 7fb809b

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 kMaxEventTargetListeners = Symbol('events.maxEventTargetListeners');
7979
const kMaxEventTargetListenersWarned =
8080
Symbol('events.maxEventTargetListenersWarned');
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
}
@@ -156,6 +161,12 @@ ObjectDefineProperties(EventEmitter, {
156161
}
157162
});
158163

164+
/**
165+
* Sets the max listeners.
166+
* @param {number} n
167+
* @param {EventTarget[] | EventEmitter[]} [eventTargets]
168+
* @returns {void}
169+
*/
159170
EventEmitter.setMaxListeners =
160171
function(n = defaultMaxListeners, ...eventTargets) {
161172
if (typeof n !== 'number' || n < 0 || NumberIsNaN(n))
@@ -247,8 +258,11 @@ function emitUnhandledRejectionOrErr(ee, err, type, args) {
247258
}
248259
}
249260

250-
// Obviously not all Emitters should be limited to 10. This function allows
251-
// that to be increased. Set to zero for unlimited.
261+
/**
262+
* Increases the max listeners of the event emitter.
263+
* @param {number} n
264+
* @returns {EventEmitter}
265+
*/
252266
EventEmitter.prototype.setMaxListeners = function setMaxListeners(n) {
253267
if (typeof n !== 'number' || n < 0 || NumberIsNaN(n)) {
254268
throw new ERR_OUT_OF_RANGE('n', 'a non-negative number', n);
@@ -263,6 +277,10 @@ function _getMaxListeners(that) {
263277
return that._maxListeners;
264278
}
265279

280+
/**
281+
* Returns the current max listener value for the event emitter.
282+
* @returns {number}
283+
*/
266284
EventEmitter.prototype.getMaxListeners = function getMaxListeners() {
267285
return _getMaxListeners(this);
268286
};
@@ -315,6 +333,13 @@ function enhanceStackTrace(err, own) {
315333
return err.stack + sep + ArrayPrototypeJoin(ownStack, '\n');
316334
}
317335

336+
/**
337+
* Synchronously calls each of the listeners registered
338+
* for the event.
339+
* @param {string | symbol} type
340+
* @param {...any} [args]
341+
* @returns {boolean}
342+
*/
318343
EventEmitter.prototype.emit = function emit(type, ...args) {
319344
let doError = (type === 'error');
320345

@@ -456,12 +481,25 @@ function _addListener(target, type, listener, prepend) {
456481
return target;
457482
}
458483

484+
/**
485+
* Adds a listener to the event emitter.
486+
* @param {string | symbol} type
487+
* @param {Function} listener
488+
* @returns {EventEmitter}
489+
*/
459490
EventEmitter.prototype.addListener = function addListener(type, listener) {
460491
return _addListener(this, type, listener, false);
461492
};
462493

463494
EventEmitter.prototype.on = EventEmitter.prototype.addListener;
464495

496+
/**
497+
* Adds the `listener` function to the beginning of
498+
* the listeners array.
499+
* @param {string | symbol} type
500+
* @param {Function} listener
501+
* @returns {EventEmitter}
502+
*/
465503
EventEmitter.prototype.prependListener =
466504
function prependListener(type, listener) {
467505
return _addListener(this, type, listener, true);
@@ -485,13 +523,26 @@ function _onceWrap(target, type, listener) {
485523
return wrapped;
486524
}
487525

526+
/**
527+
* Adds a one-time `listener` function to the event emitter.
528+
* @param {string | symbol} type
529+
* @param {Function} listener
530+
* @returns {EventEmitter}
531+
*/
488532
EventEmitter.prototype.once = function once(type, listener) {
489533
checkListener(listener);
490534

491535
this.on(type, _onceWrap(this, type, listener));
492536
return this;
493537
};
494538

539+
/**
540+
* Adds a one-time `listener` function to the beginning of
541+
* the listeners array.
542+
* @param {string | symbol} type
543+
* @param {Function} listener
544+
* @returns {EventEmitter}
545+
*/
495546
EventEmitter.prototype.prependOnceListener =
496547
function prependOnceListener(type, listener) {
497548
checkListener(listener);
@@ -500,7 +551,12 @@ EventEmitter.prototype.prependOnceListener =
500551
return this;
501552
};
502553

503-
// Emits a 'removeListener' event if and only if the listener was removed.
554+
/**
555+
* Removes the specified `listener` from the listeners array.
556+
* @param {string | symbol} type
557+
* @param {Function} listener
558+
* @returns {EventEmitter}
559+
*/
504560
EventEmitter.prototype.removeListener =
505561
function removeListener(type, listener) {
506562
checkListener(listener);
@@ -554,6 +610,13 @@ EventEmitter.prototype.removeListener =
554610

555611
EventEmitter.prototype.off = EventEmitter.prototype.removeListener;
556612

613+
/**
614+
* Removes all listeners from the event emitter. (Only
615+
* removes listeners for a specific event name if specified
616+
* as `type`).
617+
* @param {string | symbol} [type]
618+
* @returns {EventEmitter}
619+
*/
557620
EventEmitter.prototype.removeAllListeners =
558621
function removeAllListeners(type) {
559622
const events = this._events;
@@ -617,14 +680,34 @@ function _listeners(target, type, unwrap) {
617680
unwrapListeners(evlistener) : arrayClone(evlistener);
618681
}
619682

683+
/**
684+
* Returns a copy of the array of listeners for the event name
685+
* specified as `type`.
686+
* @param {string | symbol} type
687+
* @returns {Function[]}
688+
*/
620689
EventEmitter.prototype.listeners = function listeners(type) {
621690
return _listeners(this, type, true);
622691
};
623692

693+
/**
694+
* Returns a copy of the array of listeners and wrappers for
695+
* the event name specified as `type`.
696+
* @param {string | symbol} type
697+
* @returns {Function[]}
698+
*/
624699
EventEmitter.prototype.rawListeners = function rawListeners(type) {
625700
return _listeners(this, type, false);
626701
};
627702

703+
/**
704+
* Returns the number of listeners listening to the event name
705+
* specified as `type`.
706+
* @deprecated since v3.2.0
707+
* @param {EventEmitter} emitter
708+
* @param {string | symbol} type
709+
* @returns {number}
710+
*/
628711
EventEmitter.listenerCount = function(emitter, type) {
629712
if (typeof emitter.listenerCount === 'function') {
630713
return emitter.listenerCount(type);
@@ -633,6 +716,13 @@ EventEmitter.listenerCount = function(emitter, type) {
633716
};
634717

635718
EventEmitter.prototype.listenerCount = listenerCount;
719+
720+
/**
721+
* Returns the number of listeners listening to event name
722+
* specified as `type`.
723+
* @param {string | symbol} type
724+
* @returns {number}
725+
*/
636726
function listenerCount(type) {
637727
const events = this._events;
638728

@@ -649,6 +739,11 @@ function listenerCount(type) {
649739
return 0;
650740
}
651741

742+
/**
743+
* Returns an array listing the events for which
744+
* the emitter has registered listeners.
745+
* @returns {any[]}
746+
*/
652747
EventEmitter.prototype.eventNames = function eventNames() {
653748
return this._eventsCount > 0 ? ReflectOwnKeys(this._events) : [];
654749
};
@@ -676,6 +771,13 @@ function unwrapListeners(arr) {
676771
return ret;
677772
}
678773

774+
/**
775+
* Returns a copy of the array of listeners for the event name
776+
* specified as `type`.
777+
* @param {EventEmitter | EventTarget} emitterOrTarget
778+
* @param {string | symbol} type
779+
* @returns {Function[]}
780+
*/
679781
function getEventListeners(emitterOrTarget, type) {
680782
// First check if EventEmitter
681783
if (typeof emitterOrTarget.listeners === 'function') {
@@ -700,6 +802,14 @@ function getEventListeners(emitterOrTarget, type) {
700802
emitterOrTarget);
701803
}
702804

805+
/**
806+
* Creates a `Promise` that is fulfilled when the emitter
807+
* emits the given event.
808+
* @param {EventEmitter} emitter
809+
* @param {string} name
810+
* @param {{ signal: AbortSignal; }} [options]
811+
* @returns {Promise}
812+
*/
703813
async function once(emitter, name, options = {}) {
704814
const signal = options?.signal;
705815
validateAbortSignal(signal, 'options.signal');
@@ -771,6 +881,13 @@ function eventTargetAgnosticAddListener(emitter, name, listener, flags) {
771881
}
772882
}
773883

884+
/**
885+
* Returns an `AsyncIterator` that iterates `event` events.
886+
* @param {EventEmitter} emitter
887+
* @param {string | symbol} event
888+
* @param {{ signal: AbortSignal; }} [options]
889+
* @returns {AsyncIterator}
890+
*/
774891
function on(emitter, event, options) {
775892
const signal = options?.signal;
776893
validateAbortSignal(signal, 'options.signal');

0 commit comments

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