Skip to content

satisfies support in JSDoc #51086

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking β€œSign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
5 tasks done
brendankenny opened this issue Oct 6, 2022 Β· 3 comments Β· Fixed by #51753
Closed
5 tasks done

satisfies support in JSDoc #51086

brendankenny opened this issue Oct 6, 2022 Β· 3 comments Β· Fixed by #51753
Labels
Domain: JSDoc Relates to JSDoc parsing and type generation In Discussion Not yet reached consensus Suggestion An idea for TypeScript

Comments

@brendankenny
Copy link
Contributor

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!

@DanielRosenwasser
Copy link
Member

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

@DanielRosenwasser DanielRosenwasser added Suggestion An idea for TypeScript In Discussion Not yet reached consensus Domain: JSDoc Relates to JSDoc parsing and type generation labels Oct 6, 2022
@a-tarasyuk
Copy link
Contributor

/** @satisfies {Type} */

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

@DanielRosenwasser
Copy link
Member

Thank you @a-tarasyuk!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Domain: JSDoc Relates to JSDoc parsing and type generation In Discussion Not yet reached consensus Suggestion An idea for TypeScript
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants