Guide to creating JSDoc for a TouchEvent handler

Question

Guide to creating JSDoc for a TouchEvent handler

Looking to improve my shorter-js codebase with JSDoc for TypeScript definitions, but hitting a roadblock.

I've implemented the on() function using Element.addEventListener, working well so far. However, when passing a TouchEvent as a parameter for an event handler, TypeScript throws a 4-line error as shown below:

/**
 * @param {HTMLElement | Element | Document} element event.target
 * @param {string} eventName event.type
 * @param {EventListener} handler callback
 * @param {EventListenerOptions | boolean | undefined} options other event options
 */
function on(element, eventName, handler, options) {
  const ops = options || false;
  element.addEventListener(eventName, handler, ops);
}

/**
 * test handler
 * @type {EventListener}
 * @param {TouchEvent} e
 */
function touchdownHandler(e){
  console.log(e.touches)
}

// test invocation
on(document.body, 'touchdown', touchdownHandler);

body {height: 100%}

The error is triggered by the

on(document.body, 'touchdown', touchdownHandler)

call and reads as follows:

Argument of type '(e: TouchEvent) => void' is not assignable to parameter of type 'EventListener'.
  Type '(e: TouchEvent) => void' is not assignable to type 'EventListener'.
    Types of parameters 'e' and 'evt' are incompatible.
      Type 'Event' is missing the following properties from type 'TouchEvent': altKey, changedTouches, ctrlKey, metaKey, and 7 more.

Even using

document.body.addEventListener(...)

leads to the same error. I have attempted different definitions in my index.d.ts file without success.

It seems like I need to define something in my index.d.ts file and then reference it in the JSDoc for the touchdownHandler. Any ideas?

javascript typescript addeventlistener touch-event jsdoc

Answer 1

Answer №1

The issue here is that when using addEventListener, you must provide the actual type of event in order to map the handler to accept that specific kind of event. The declaration file dom.d.ts from the DOM Library contains event maps for this purpose. Your objective should be to ensure that the eventName is mapped to the event type of the handler.

In TypeScript, we can utilize param types to achieve this without generics. However, with JSDoc, we need to introduce a template variable for the Event Type:

/**
 * @template {keyof HTMLElementEventMap} T
 * @param {HTMLElement} element
 * @param {T} eventName
*/

Although there are other event maps available, in most cases, this approach will suffice. If more specificity is required, refer to the source code of the dom.d.ts.

Next, it's essential to define the type of the handler:

/**
 * @template {keyof HTMLElementEventMap} T
 * @param {HTMLElement} element
 * @param {T} eventName
 * @param {(event: HTMLElementEventMap[T]) => void} handler
 */

For instance, if T is set to 'click', the handler will receive the event as HTMLElementEventMap['click'], which is equivalent to MouseEvent.

Lastly, let's discuss the options. In JSDoc, you can indicate a parameter as optional instead of explicitly mentioning undefined:

/**
 * @template {keyof HTMLElementEventMap} T
 * @param {HTMLElement} element
 * @param {T} eventName
 * @param {(event: HTMLElementEventMap[T]) => void} handler
 * @param {EventListenerOptions | boolean} [options]
 */

This method aligns with your expectations.

Full Code:

/**
 * @template {keyof HTMLElementEventMap} T
 * @param {HTMLElement} element
 * @param {T} eventName
 * @param {(event: HTMLElementEventMap[T]) => void} handler
 * @param {EventListenerOptions | boolean} [options]
 */
function on(element, eventName,  handler, options) {
  const ops = options || false;
  element.addEventListener(eventName, handler, ops);
}

/**
 * test handler
 * @param {TouchEvent} e
 */
function touchdownHandler(e) {
  console.log(e.touches)
}

// test invocation
on(document.body, 'touchend', touchdownHandler);

Sandbox

To declare this using Generics, include the following code snippet:

declare function on<T extends keyof HTMLElementEventMap>(element: HTMLElement, eventName: T, handler: (event: HTMLElementEventMap[T]) => void, options?: EventListenerOptions | boolean): void;

Answer 2

The issue here is that when using addEventListener, you must provide the actual type of event in order to map the handler to accept that specific kind of event. The declaration file dom.d.ts from the DOM Library contains event maps for this purpose. Your objective should be to ensure that the eventName is mapped to the event type of the handler.

In TypeScript, we can utilize param types to achieve this without generics. However, with JSDoc, we need to introduce a template variable for the Event Type:

/**
 * @template {keyof HTMLElementEventMap} T
 * @param {HTMLElement} element
 * @param {T} eventName
*/

Although there are other event maps available, in most cases, this approach will suffice. If more specificity is required, refer to the source code of the dom.d.ts.

Next, it's essential to define the type of the handler:

/**
 * @template {keyof HTMLElementEventMap} T
 * @param {HTMLElement} element
 * @param {T} eventName
 * @param {(event: HTMLElementEventMap[T]) => void} handler
 */

For instance, if T is set to 'click', the handler will receive the event as HTMLElementEventMap['click'], which is equivalent to MouseEvent.

Lastly, let's discuss the options. In JSDoc, you can indicate a parameter as optional instead of explicitly mentioning undefined:

/**
 * @template {keyof HTMLElementEventMap} T
 * @param {HTMLElement} element
 * @param {T} eventName
 * @param {(event: HTMLElementEventMap[T]) => void} handler
 * @param {EventListenerOptions | boolean} [options]
 */

This method aligns with your expectations.

Full Code:

/**
 * @template {keyof HTMLElementEventMap} T
 * @param {HTMLElement} element
 * @param {T} eventName
 * @param {(event: HTMLElementEventMap[T]) => void} handler
 * @param {EventListenerOptions | boolean} [options]
 */
function on(element, eventName,  handler, options) {
  const ops = options || false;
  element.addEventListener(eventName, handler, ops);
}

/**
 * test handler
 * @param {TouchEvent} e
 */
function touchdownHandler(e) {
  console.log(e.touches)
}

// test invocation
on(document.body, 'touchend', touchdownHandler);

Sandbox

To declare this using Generics, include the following code snippet:

declare function on<T extends keyof HTMLElementEventMap>(element: HTMLElement, eventName: T, handler: (event: HTMLElementEventMap[T]) => void, options?: EventListenerOptions | boolean): void;

Answer 3

Answer №2

After already marking an answer, I have decided to share my own solution, which turned out to be simpler than I initially thought. This involves leveraging the EventListenerObject and its handleEvent method:

/**
 * Add eventListener to an `Element` | `HTMLElement` | `Document` | `Window` target.
 *
 * @param {HTMLElement | Element | Document | Window} element event.target
 * @param {string} eventName event.type
 * @param {EventListenerObject['handleEvent']} handler callback
 * @param {(EventListenerOptions | boolean)=} options other event options
 */
function on(element, eventName, handler, options) {
  const ops = options || false;
  element.addEventListener(eventName, handler, ops);
}

Now everything is functioning as expected.

on(document, 'load', (e) => console.log(e), false)

on(window, 'resize', (e) => console.log(e.type), false)

/**
 * test handler
 * @type {(event: Event) => void}
 * @param {TouchEvent} e
 */
 function touchdownHandler(e) {
  console.log(e.touches)
}

const div = document.createElement('div')
on(div, 'touchstart', touchdownHandler, false)

const main = document.createElement('main')
on(main, 'touchstart', touchdownHandler, false)

Answer 4

After already marking an answer, I have decided to share my own solution, which turned out to be simpler than I initially thought. This involves leveraging the EventListenerObject and its handleEvent method:

/**
 * Add eventListener to an `Element` | `HTMLElement` | `Document` | `Window` target.
 *
 * @param {HTMLElement | Element | Document | Window} element event.target
 * @param {string} eventName event.type
 * @param {EventListenerObject['handleEvent']} handler callback
 * @param {(EventListenerOptions | boolean)=} options other event options
 */
function on(element, eventName, handler, options) {
  const ops = options || false;
  element.addEventListener(eventName, handler, ops);
}

Now everything is functioning as expected.

on(document, 'load', (e) => console.log(e), false)

on(window, 'resize', (e) => console.log(e.type), false)

/**
 * test handler
 * @type {(event: Event) => void}
 * @param {TouchEvent} e
 */
 function touchdownHandler(e) {
  console.log(e.touches)
}

const div = document.createElement('div')
on(div, 'touchstart', touchdownHandler, false)

const main = document.createElement('main')
on(main, 'touchstart', touchdownHandler, false)

Guide to creating JSDoc for a TouchEvent handler

Answer №1

Answer №2

Similar questions

Leveraging AngularJS and ng-map to incorporate interactive dynamic heatmap displays

Are there any possible resolutions to the issues plaguing Next.Js?

When integrating the React custom hook setValue into another component, it appears to be returning an undefined

What is the best way to switch an element's attributes using only JavaScript?

Using Google App Script for Slides to center-align text within a text box

Encountering an "Undefined index" error when attempting to send a file and path using FormData through

Why am I not receiving any results from the communication between JavaScript and PHP using an HTTP GET request?

Javascript/Webpack/React: encountering issues with refs in a particular library

Using jQuery's $.ajax() function to make an asynchronous request, and then passing the

Avoiding the use of destructuring for undefined values in JavaScript can be achieved by implementing

Activate Keyboard and Background in the Bootstrap Modal

What is the memory allocation for null values in arrays by node.js?

Exploring the power of Blowfish encryption with Java and JavaScript

Every time a row is selected, React and material-ui cause all TableRows to be re-rendered anew

Angular is reporting that the check-in component is nonexistent

A conditional type used with an array to return either an Error object or a generic type when the array is destructured

The height of the browser action will not return to its original state

Enhancing your Selenium test case strategies for better performance

How can Swipe support help you slide a menu back in?

What is the best way to retrieve the value of a JavaScript variable and display it within an HTML label tag