satisfies support in JSDoc

[brendankenny]

Suggestion

🔍 Search Terms

satisfies, jsdoc

✅ Viability Checklist

My suggestion meets these guidelines:

• [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
• [x] This wouldn't change the runtime behavior of existing JavaScript code
• [x] This could be implemented without emitting different JS based on the types of the expressions
• [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• [x] 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!

[DanielRosenwasser]

I think /** @satisfies {Type} */ is my preference as well.

[a-tarasyuk]

/** @satisfies {Type} */

It looks good to me too. However, I'm not sure if adding new (custom?) jsdoc tags is OK.

[DanielRosenwasser]

Thank you @a-tarasyuk!