JSDoc doesnt support generics correctly

[thepassle]

🔎 Search Terms

jsdoc generics

🕗 Version & Regression Information

• This is a crash
• This changed between versions __ and ___
• This changed in commit or PR ___
• This is the behavior in every version I tried, and I reviewed the FAQ for entries about _____
• I was unable to test this on prior versions because ___

⏯ Playground Link

No response

💻 Code

Given the following code:

function api<T>(endpoint: string): Promise<T> {
  return fetch(endpoint).then(res => res.json());
}

When I consume the api function in a .js file, I'd still like to leverage the T generic via JSDoc-only. There currently isnt a straightforward way to do this, and the DX of this could definitely be improved.

🙁 Actual behavior

Cant leverage the T generic

🙂 Expected behavior

I can leverage the T generic

Additional information about the issue

This is a long overdue feature :)

[fatcerberus]

Not directly related to the issue but that function scares me. It's like when people ask for JSON.parse to be generic.

[thepassle]

Not directly related to the issue but that function scares me. It's like when people ask for JSON.parse to be generic.

Whatever, thats irrelevant, its just an example.

[thepassle]

Maybe a potential solution/proposal could be something like this?

function api<T>(endpoint: string): Promise<T> {
  return fetch(endpoint).then(res => res.json());
}

/**
 * @typedef {Object} Foo
 * @property {string} bar
 */

const r = await api/** @type {Foo} */('/api/foo');

// the type of `r` is `Foo`

This is still valid js, and its similar to how the generic would be provided in ts: api<Foo>('/api/foo')

[KonnorRogers]

This seems similar to this: https://github.com/microsoft/TypeScript/issues/27387

But also 👍

using Generic functions with JSDOC is quite painful.

[thepassle]

@RyanCavanaugh Would it be possible to get some feedback from the team on either this proposal or whats proposed in #27387?