From e3a0a9cb3a470eeedf25c93f7dfca30678cc68cc Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 21 Dec 2021 14:10:57 -0800 Subject: [PATCH] events: add jsdoc details for Event and EventTarget Signed-off-by: James M Snell PR-URL: https://github.com/nodejs/node/pull/41274 Reviewed-By: Antoine du Hamel Reviewed-By: Benjamin Gruenbaum Reviewed-By: Adrian Estrada --- lib/internal/event_target.js | 128 ++++++++++++++++++++++++++++++++++- 1 file changed, 127 insertions(+), 1 deletion(-) diff --git a/lib/internal/event_target.js b/lib/internal/event_target.js index e962c8b02399f4..83908e66bfc48d 100644 --- a/lib/internal/event_target.js +++ b/lib/internal/event_target.js @@ -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'); @@ -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'); @@ -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'); @@ -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'); @@ -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'); @@ -498,6 +567,9 @@ class EventTarget { } } + /** + * @param {Event} event + */ dispatchEvent(event) { if (!isEventTarget(this)) throw new ERR_INVALID_THIS('EventTarget'); @@ -627,24 +699,37 @@ 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'); @@ -652,6 +737,14 @@ class NodeEventTarget extends EventTarget { 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'); @@ -659,6 +752,14 @@ class NodeEventTarget extends EventTarget { 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'); @@ -666,6 +767,11 @@ class NodeEventTarget extends EventTarget { return this; } + /** + * @param {string} type + * @param {EventTargetCallback|EventListener} listener + * @returns {NodeEventTarget} + */ on(type, listener) { if (!isNodeEventTarget(this)) throw new ERR_INVALID_THIS('NodeEventTarget'); @@ -673,12 +779,23 @@ class NodeEventTarget extends EventTarget { 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'); @@ -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'); @@ -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');