Allow using the satisfies operator in JSDoc comments

[jespertheend]

Suggestion

🔍 Search Terms

satisfies operator 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

TypeScript has the satisfies operator, but there's no way to use this operator in JavaScript files with JSDoc.

📃 Motivating Example

Take the following TypeScript code:

type Foo = {
	bar: string;
	baz: number;
}

const x = {
	bar: "sldkfj",
	baz: 3,
} as const satisfies Foo;

This is currently not possible in JavaScript files

💻 Use Cases

The example above gives the benefit of both type checking x for errors, as well as autocompleting property names when adding new properties.

Proposal

I think the same syntax for casting can be used here. Especially with the example above since that is already being cast:

/**
 * @typedef Foo
 * @property {string} bar
 * @property {number} baz
 */

const x = /** @type {const satisfies Foo} */ ({
	bar: "bar",
	baz: 3,
});

For cases where you don't want to cast as const similar syntax can be used:

const x = /** @type {satisfies Foo} */ ({
	bar: "bar",
	baz: 3,
});

[jespertheend]

As a workaround, for now the same effect can still be achieved using a generic function:

/**
 * @template {Foo} T
 * @param {T} x
 */
const satisfiesFoo = x => x;

const x = satisfiesFoo(/** @type {const} */ ({
	bar: "bar",
	baz: 3,
}));

[MartinJohns]

Duplicate of #51086. Used search terms: satisfies jsdoc in:title

[Andarist]

This already works since 5.0: #51753

/**
 * @typedef Foo
 * @property {string} bar
 * @property {number} baz
 */

/** @satisfies {Foo} */
const x = /** @type {const} */ ({
	bar: "bar",
	baz: 3,
})

const y = /** @type {const} @satisfies {Foo} */ ({
	bar: "bar",
	baz: 3,
})

TS playground

[jespertheend]

Ah sorry about that! Not sure how I missed this.