Skip to content
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

satisfies support in JSDoc #51086

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