Skip to content

Commit

Permalink
events: add jsdoc details for Event and EventTarget
Browse files Browse the repository at this point in the history 
Signed-off-by: James M Snell <[email protected]>

PR-URL: nodejs#41274
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: Adrian Estrada <[email protected]>
  • Loading branch information
@jasnell @Linkgoron
jasnell authored and Linkgoron committed Jan 31, 2022
1 parent 808973a commit 1211f4c
Showing 1 changed file with 127 additions and 1 deletion.
128 changes: 127 additions & 1 deletion lib/internal/event_target.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,14 @@ function isEvent(value) {
}

class Event {
/**
* @param {string} type
* @param {{
* bubbles?: boolean,
* cancelable?: boolean,
* composed?: boolean,
* }} [options]
*/
constructor(type, options = null) {
if (arguments.length === 0)
throw new ERR_MISSING_ARGS('type');
Expand Down Expand Up @@ -146,42 +154,63 @@ class Event {
this[kDefaultPrevented] = true;
}

/**
* @type {EventTarget}
*/
get target() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kTarget];
}

/**
* @type {EventTarget}
*/
get currentTarget() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kTarget];
}

/**
* @type {EventTarget}
*/
get srcElement() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kTarget];
}

/**
* @type {string}
*/
get type() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kType];
}

/**
* @type {boolean}
*/
get cancelable() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kCancelable];
}

/**
* @type {boolean}
*/
get defaultPrevented() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kCancelable] && this[kDefaultPrevented];
}

/**
* @type {number}
*/
get timeStamp() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
Expand All @@ -192,43 +221,63 @@ class Event {
// The following are non-op and unused properties/methods from Web API Event.
// These are not supported in Node.js and are provided purely for
// API completeness.

/**
* @returns {EventTarget[]}
*/
composedPath() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kIsBeingDispatched] ? [this[kTarget]] : [];
}

/**
* @type {boolean}
*/
get returnValue() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return !this.defaultPrevented;
}

/**
* @type {boolean}
*/
get bubbles() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kBubbles];
}

/**
* @type {boolean}
*/
get composed() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kComposed];
}

/**
* @type {number}
*/
get eventPhase() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kIsBeingDispatched] ? Event.AT_TARGET : Event.NONE;
}

/**
* @type {boolean}
*/
get cancelBubble() {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
return this[kPropagationStopped];
}

/**
* @type {boolean}
*/
set cancelBubble(value) {
if (!isEvent(this))
throw new ERR_INVALID_THIS('Event');
Expand Down Expand Up @@ -391,6 +440,19 @@ class EventTarget {
}
[kRemoveListener](size, type, listener, capture) {}

/**
* @callback EventTargetCallback
* @param {Event} event
* @typedef {{ handleEvent: EventTargetCallback }} EventListener
* @param {string} type
* @param {EventTargetCallback|EventListener} listener
* @param {{
* capture?: boolean,
* once?: boolean,
* passive?: boolean,
* signal?: AbortSignal
* }} [options]
*/
addEventListener(type, listener, options = {}) {
if (!isEventTarget(this))
throw new ERR_INVALID_THIS('EventTarget');
Expand Down Expand Up @@ -471,6 +533,13 @@ class EventTarget {
this[kNewListener](root.size, type, listener, once, capture, passive, weak);
}

/**
* @param {string} type
* @param {EventTargetCallback|EventListener} listener
* @param {{
* capture?: boolean,
* }} [options]
*/
removeEventListener(type, listener, options = {}) {
if (!isEventTarget(this))
throw new ERR_INVALID_THIS('EventTarget');
Expand Down Expand Up @@ -498,6 +567,9 @@ class EventTarget {
}
}

/**
* @param {Event} event
*/
dispatchEvent(event) {
if (!isEventTarget(this))
throw new ERR_INVALID_THIS('EventTarget');
Expand Down Expand Up @@ -627,58 +699,103 @@ class NodeEventTarget extends EventTarget {
initNodeEventTarget(this);
}

/**
* @param {number} n
*/
setMaxListeners(n) {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
EventEmitter.setMaxListeners(n, this);
}

/**
* @returns {number}
*/
getMaxListeners() {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
return this[kMaxEventTargetListeners];
}

/**
* @returns {string[]}
*/
eventNames() {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
return ArrayFrom(this[kEvents].keys());
}

/**
* @param {string} [type]
* @returns {number}
*/
listenerCount(type) {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
const root = this[kEvents].get(String(type));
return root !== undefined ? root.size : 0;
}

/**
* @param {string} type
* @param {EventTargetCallback|EventListener} listener
* @param {{
* capture?: boolean,
* }} [options]
* @returns {NodeEventTarget}
*/
off(type, listener, options) {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
this.removeEventListener(type, listener, options);
return this;
}

/**
* @param {string} type
* @param {EventTargetCallback|EventListener} listener
* @param {{
* capture?: boolean,
* }} [options]
* @returns {NodeEventTarget}
*/
removeListener(type, listener, options) {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
this.removeEventListener(type, listener, options);
return this;
}

/**
* @param {string} type
* @param {EventTargetCallback|EventListener} listener
* @returns {NodeEventTarget}
*/
on(type, listener) {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
this.addEventListener(type, listener, { [kIsNodeStyleListener]: true });
return this;
}

/**
* @param {string} type
* @param {EventTargetCallback|EventListener} listener
* @returns {NodeEventTarget}
*/
addListener(type, listener) {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
this.addEventListener(type, listener, { [kIsNodeStyleListener]: true });
return this;
}

/**
* @param {string} type
* @param {any} arg
* @returns {boolean}
*/
emit(type, arg) {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
Expand All @@ -688,6 +805,11 @@ class NodeEventTarget extends EventTarget {
return hadListeners;
}

/**
* @param {string} type
* @param {EventTargetCallback|EventListener} listener
* @returns {NodeEventTarget}
*/
once(type, listener) {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
Expand All @@ -696,6 +818,10 @@ class NodeEventTarget extends EventTarget {
return this;
}

/**
* @param {string} type
* @returns {NodeEventTarget}
*/
removeAllListeners(type) {
if (!isNodeEventTarget(this))
throw new ERR_INVALID_THIS('NodeEventTarget');
Expand Down

0 comments on commit 1211f4c

Please sign in to comment.