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

Error in syntax: The tailwind import statement contains an unrecognized word and will not function correctly

Converting a TypeScript class to a plain JavaScript object using class-transformer

Effortlessly saving money with just one click

A function injected into a constructor of a class causes an undefined error

Using single quotation marks in Javascript

Display various elements depending on the size of the screen within Next.js

Create your masterpiece on a rotated canvas

"Utilizing Bootstrap Modal for efficient AJAX saving of multiple records with the help of bootstrapValidator

What is the reason for React.Component being implemented as a function rather than an ES6 class?

Convert your Node.js server URL hosted on AWS Elastic Beanstalk to HTTPS

Background image not displaying in new tab after Chrome extension installation

The function app.post in Express Node is not recognized

Vue .filter doesn't work with reactive data sources

Issue: $injector:unpr Angular Provider Not Recognized

ReactJS - Unable to access property of undefined object

Tips for concealing select options after choosing with select picker?

How can I declare CSS variables in Next.js components' module.css just like in global CSS?

Identifying when a page-loading or reloading event has been canceled

Automatically conceal a div once an iframe reaches a specific height

Tips for passing arguments to event handlers in React JS