Description
Suggestion
π Search Terms
satisfies, jsdoc
β Viability 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. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
- This feature would agree with the rest of TypeScript's Design Goals.
β Suggestion
It would be fantastic to have satisfies
support in jsdoc. This was previously discussed in the satisfies PR (with the suggestion to open a separate tracking issue) and in the 8/17/2022 Design Meeting.
There was a discussion about using /** @type {satisfies T} */
, but I would love to see TS be more opinionated on this and go for /** @satisfies {T} */
.
Two main reasons:
- more straightforward in intent and keeps already-lengthy jsdoc lines from getting even longer
- allows the same functionality as ts files if (for some reason) you really want to include a type annotation and a
satisfies
clause. There aren't great reasons to do this, but the fewer functionality differences between ts and jsdoc the better.
The design meeting mentioned:
We try not to add new tags that aren't doc'd in the usejsdoc site.
Ship has sailed with TS-specific syntax in JSDoc, right?
But: unknown tags are common in the wild and jsdoc
(the utility) has allowUnknownTags
set by default, so @satisfies
information isn't included in the generated docs, but it also doesn't cause any errors. Parser-wise, it should also be relatively easy to support in the future, if there's a desire.
The syntax ship has definitely sailed, in contrast. TS hasn't added tags before AFAIK, but common TS-specific syntax is already often not parsed and causes errors (e.g. /** @type {{name: string}[]} */ const arr = [];
).
π Motivating Example
/** @typedef {"red" | "green" | "blue"} Colors */
/**
* Ensure that we have exactly the keys from 'Colors'.
* @satisfies {Record<Colors, unknown>}
*/
const favoriteColors = {
red: 'yes',
green: false,
blue: 'kinda',
platypus: false,
// ~~~~~~~~ error - "platypus" was never listed in 'Colors'.
}
π» Use Cases
satisfies
in jsdoc!