Class generics not evaluated properly in JSDoc

[dominikschreiber]

🔎 Search Terms

jsdoc generics

🕗 Version & Regression Information

This is the behavior in every version I tried (i.e. at random from 3.6.3 to nightly), and I reviewed the FAQ for entries about jsdoc and generics

⏯ Playground Link

https://www.typescriptlang.org/play?ts=5.4.0-dev.20231205&filetype=js#code/PQKhAIAEBcFMFsAOAbAhncAVcJgCgBjNAZ2PABEB7ecAbz3EfFAhgE9FY6B5AIwCtYBaAB5i0AE4BLAHYBzADRYAfAF8c+JuBmUAJrGIAhNgEld4ALx1VAbgZM5saAGEAFlOS6JsGQAoAlHTe0ACuEjLg0O7EAHQ6+kamuqp4KXgsUNAcXLRU8CIyIfC8sBJqGoSUMuLaelxWMrAA7hTUAXYEVTUE7p7eEQ11MY4uvV4+7UA

💻 Code

(not working): TypeScript in JSDoc (playground link)

/** @template T */
class Dom {
 /** @type {Object<string, T>} */
 nodesById = {};
 getChildren() {return this.nodesById}
}

/** @type {Dom<number>} */
const node = new Dom();
const children = node.getChildren(); // type is {[id: string]: T}

(working): TypeScript (playground link)

class Dom<T> {
 nodesById: {[id: string]: T} = {};
 getChildren() {return this.nodesById}
}

const node = new Dom<number>();
const children = node.getChildren(); // type is {[id: string]: number}

🙁 Actual behavior

With TypeScript in JSDoc, children has the type {[id: string]: T}, i.e. T is not resolved, although node has the type Dom<number>.

🙂 Expected behavior

With TypeScript, children has the type {[id: string]: number}, i.e. T is taken correctly from Dom<number>. The same is expected for TypeScript in JSDoc.

Additional information about the issue

Obviously, this is just a minimal working example. We have a large legacy codebase where we introduce TypeScript gradually via JSDoc comments (a nuke-everything TypeScript rewrite would not be feasible).

[bouzlibop]

I encountered similar issue. It seems like there is a problem when a generic parameter is nested.

Here is an example (playground link):

/**
 * @template T
 * @param {function(T): string} getKey
 * @param {T[]} items
 * @returns {Object<string, T[]>}
 */
function groupBy(getKey, items) {
 /**
 * @type {Object<string, T[]>}
 */
 let grouped = {};
 for (let item of items) {
 const key = getKey(item);
 if (grouped[key] === undefined) grouped[key] = [];
 grouped[key].push(item);
 }
 return grouped;
}

const items = ["a1", "b1", "a2", "b2"];
const byFirstChar = (/** @type {string} */ str) => str[0];
groupBy(byFirstChar, items);

I would expect groupBy(byFirstChar, items) to have following signature:

function groupBy<string>(getKey: (arg0: string) => string, items: string[]): {
 [x: string]: string[];
}

but actually the signature looks like this:

function groupBy<string>(getKey: (arg0: string) => string, items: string[]): {
 [x: string]: T[];
}

Note that T in the return typed wasn't properly replaced by string.