Allow to explicitly pass type parameters via JSDoc
See original GitHub issueSearch Terms
jsdoc generics type parameters constraints
Suggestion
It seems like it is not possible via JSDoc to explicitly tell compiler which type parameters to pass to a generic function.
Use Cases
In TypeScript it is possible to explicitly pass type parameters such as mongoose.model<Model, Schema>('modelName', Schema)
while I could not find a way to do same with JSDoc.
Examples
mongoose.model
has two signatures, first one with one type parameter and the other with two. To make use of the second signature we must pass types explicitly.
export function model<T extends Document>(
name: string,
schema?: Schema,
collection?: string,
skipInit?: boolean
): Model<T>;
export function model<T extends Document, U extends Model<T>>(
name: string,
schema?: Schema,
collection?: string,
skipInit?: boolean
): U;
// Choose second signature in typescript.
const model = mongoose.model<Model, Schema>('modelName', Schema);
// With JSDoc, compiler always chooses first signature and we receive a type mismatch error.
/** @type {Schema & mongoose.Model<Model>} */
const model = mongoose.model('modelName', Schema);
// But something like this would be great.
const model = mongoose.model/**<Model, Schema>*/('modelName', Schema);
My apologies if this is already possible, but I’ve spend almost a week battling this.
Related: https://github.com/Microsoft/TypeScript-Node-Starter/issues/101
Checklist
My suggestion meets these guidelines:
- 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. new expression-level syntax)
Issue Analytics
- State:
- Created 5 years ago
- Reactions:84
- Comments:18 (1 by maintainers)
Top Results From Across the Web
JSDoc Reference - TypeScript: Documentation
The list below outlines which constructs are currently supported when using JSDoc annotations to provide type information in JavaScript files.
Read more >Use JSDoc: @param
The following examples show how to use type expressions to indicate that a parameter can accept multiple types (or any type), and that...
Read more >How to document generic type parameters? - Stack Overflow
In C# I'd use <typeparam> . Is there an official JSDoc equivalent? typescript · jsdoc · Share.
Read more >Validating JavaScript Code With JSDoc Types Annotations
And this is my favorite case. You can specify callback's 'this' and parameter types, and they will be known in passed anonymous function....
Read more >Joshua's Docs - JSDoc Cheatsheet and Type Safety Tricks
Annotating destructured parameters ... If you want to annotate the type of variables that are assigned via destructuring, it can be a little ......
Read more >Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start FreeTop Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
Top GitHub Comments
BTW I just found out this works:
or
equivalent to
For functions that take an argument of the generic type, casting the argument itself is reasonably practical. We’ve settled on these patterns with
useState
anduseRef
in React for example:In cases where there is no argument for everything else to be inferred from, it gets much more verbose unfortunately. What would be helpful is being able to do something like:
Where the
?
is inferred asSet
. In this example it only saves a few characters, but it could be a lot more if the generic type name is lengthy and/or has to be imported from somewhere.