Low readability when type casting by JSDoc

Search Terms

jsdoc, type cast

Suggestion

Currently type casting by JSDoc is not pretty 1) because the comment must be after variable declaration 2) it requires parentheses (#18212).

// @ts-check
const img = /** @type {HTMLImageElement} */ (document.getElementById('#cat'))
img.src = 'cat.gif'

How about the JSDoc type declaration automatically casts the assigned type, only when the variable declaration has the value assigning part?

Use Cases

The code will be prettier: https://github.com/w3c/respec/pull/1949#discussion_r240971984

Examples

Current:

// @ts-check

/** @type {HTMLImageElement} */
const img = document.getElementById('#cat') // Error: Type 'Element' is not assignable to type 'HTMLImageElement'
img.src = 'cat.gif'

Suggestion:

// @ts-check

/** @type {HTMLImageElement} */
const img = document.getElementById('#cat') // Element being casted as HTMLImageElement
img.src = 'cat.gif'

/** @type {HTMLImageElement} */
let img2;
img2 = document.getElementById('#cat') // Still an error

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, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Start by reading the proposed JSDoc casting examples and the referenced respec discussion. Compare the requested behavior for const declarations with the explicitly unchanged behavior for later assignments. Done means the proposal has an agreed implementation and verified type-checking behavior without changing emitted JavaScript.