Support for "const modifier on type parameters" with JSDoc

[leibale]

🔍 Search Terms

"const type parameter jsdoc", "const generic jsdoc", "const template jsdoc"

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

v5.0 added support for "const modifier on type parameters", but it is not supported with JSDoc @template tag (or at least I couldn't make it work nor find any documentation about it).

I propose adding support for the const prefix in the @template:

/**
* @template {const Array<any>} T
*/

📃 Motivating Example

The same as "const modifier on type parameters" itself..

💻 Use Cases

1. What do you want to use this for?
   ...
2. What shortcomings exist with current approaches?
   ...
3. What workarounds are you using in the meantime?
   I have to wrap the generic value with /** @type {const} */(...) every time I'm using the function

[Andarist]

A workaround for this that you can use at the declaration site:

/** @type {<const T>(a: T) => T} */
function test(a) {
    return a;
}

[leibale]

@Andarist thanks! :)

[fatcerberus]

squirrely braces

Well, that’s a new one 😆

[RyanCavanaugh]

@sandersn this seems like an easy one to just add, can you check?

[sandersn]

The only change is in the parser; parseTemplateTagTypeParameter would need to parse modifiers as well.
The parser produces a normal type parameter, so that should be the only change needed.

The syntax shouldn't be /** @template {const Constraint} T */ though; Typescript syntax puts const before the parameter name, not the constraint name. Better would be /** @template {Constraint} const T */ or /** @template const T, const U */

As before, multiple type parameters in a single tag is ambiguous, so it might be better to forbid modifiers there:

/** @template const T, U */ -- is U const? Who knows.

[fatcerberus]

is U const? Who knows.

Reminds me of C pointers.

int* p, q;  // p is int*, q is int

Used to trip me up all the time; now it just annoys me.