Skip to content

satisfies support in JSDocΒ #51086

Closed
@brendankenny

Description

@brendankenny

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!

Metadata

Metadata

Assignees

No one assigned

    Labels

    Domain: JSDocRelates to JSDoc parsing and type generationIn DiscussionNot yet reached consensusSuggestionAn idea for TypeScript

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions