Skip to content

Commit

Permalink
typings: add JSDoc typings for events
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
VoltrexKeyva authored and richardlau committed Jul 20, 2021
1 parent 2d32031 commit 6ea1368
Showing 1 changed file with 120 additions and 3 deletions.
123 changes: 120 additions & 3 deletions lib/events.js
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
Expand Down Expand Up @@ -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))
Expand Down Expand Up @@ -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);
Expand All @@ -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);
};
Expand Down Expand Up @@ -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');

Expand Down Expand Up @@ -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);
Expand All @@ -491,13 +529,26 @@ 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);

this.on(type, _onceWrap(this, 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);
Expand All @@ -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);
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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);
Expand All @@ -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;

Expand All @@ -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) : [];
};
Expand Down Expand Up @@ -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') {
Expand All @@ -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');
Expand Down Expand Up @@ -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');
Expand Down

0 comments on commit 6ea1368

Please sign in to comment.