[SOLVED] How to write a @typedef with arguments? (Like CustomEvent's detail type argument)

How to write a @typedef with arguments? (Like CustomEvent's detail type argument)

Suppose I have a type that describes an API response:

/**
 * @typedef {{
 *  status: string,
 *  code: number,
 *  type: string,
 *  data: T[],
 * }} ApiResponse
 */

where T could be any of a number of DTO types the API could return.

When I write connectors dealing with specific API requests, I want to specify that T type like I could specify the type of the detail property of the CustomEvent object.

/**
 * @param {CustomEvent<DialogAction>} event
 */
function ClickHandler(event) {
    api.query(event.detail.action, { id: event.detail.id, }).then(
        /** @param {ApiResponse<DataType>} response */
        (response) => do.smth(response.data[0].???);
    );
}

Now, it correctly suggests event.detail.{id,action}, but does not recognize the data[]'s fields.

The question is - how should I write the definitions for the lexer to understand them?

Should I add something to my @typedef or should I do something entirely different? Write *.d.ts declarations? I don't know, and google not helping because I don't know how these constructions called correctly.

Solution

If you use TS flavored JSDoc, you can use the @template tag:

/**
 * @template T
 * @typedef {{
 *  status: string,
 *  code: number,
 *  type: string,
 *  data: T[],
 * }} ApiResponse
 */

These variables are called generics.