Consider deprecating `<prefix>` type assertions

### Acknowledgement

- [x] I acknowledge that issues using this template may be closed without further explanation at the maintainer's discretion.

### Comment

# Consider deprecating `` type assertions

## Background

TypeScript has two syntax forms to declare type assertions that have identical behavior:

- `value as type` *(modern)*
- `value` *(legacy, not supported in `*.tsx` files or with `erasableSyntaxOnly`)*

The `as` operator was introduced in September 2015 in [TypeScript 1.6](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-1-6.html#new-tsx-file-extension-and-as-operator) as the default way to cast in TSX files. The motivation was to remove ambiguity between JSX expressions and angle-bracket style of the type assertions.

[Official](https://www.typescriptlang.org/docs/handbook/jsx.html#the-as-operator) [documentation](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions) is relatively unopinionated about which to prefer in scenarios where either is viable, but [some docs](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-inference) only show the `as` syntax. Third-party educators barely mention `` assertions; Matt Pocock's materials mention them once to say *"don't use this".*

`` type assertions are not allowed with [`erasableSyntaxOnly`](https://www.typescriptlang.org/tsconfig/#erasableSyntaxOnly). Node.js built-in support for type stripping only supports the `as` syntax.

The TypeScript-ESLint rule [`consistent-type-assertions`](https://typescript-eslint.io/rules/consistent-type-assertions) defaults to preferring the `as` syntax and will error on `` usage.

## Opinion

Due to the greater compatibility, as well as engineer's preference for *"give me one way to do it"* consistency, the `as` syntax has been dominant for many years. I would speculate that most TypeScript users don't consciously know the old syntax exists. Either they don't come across it, or if they do they may casually overlook it and perhaps confuse it with some use of generics.

It would be constructive for TypeScript to build on the observed widespread preference and to set a clear direction for the future. This would decrease developer confusion and increase the compatibility of code in the wild.

## Proposal

There is a graduated set of steps that could be taken, similar to that taken for the [deprecated `module` keyword for namespace](https://github.com/microsoft/TypeScript/issues/51825) that reduced two-ways-to-do-it down to one. (I'll also highlight that deprecation was an excellent example of language stewardship, ecosystem cooperation, and forward-looking-yet-safe language evolution 💙)

There is value in beginning these steps, even if the process takes a long time, and even if not all steps are completed.

### 1. Discourage `` assertions in docs

This would be a clear message to the ecosystem in the TypeScript documentation that one style is universally preferred over the other. It may inspire linters to take a stronger stance.

### 2. Soft-deprecate via Editor feedback

Use the LSP ~strikethrough~ ability to provide a visual indication of the legacy style within the IDE, along with a Quick Fix to convert the code to the modern style.

### 3. Warn in the checker

An error is emitted that can be silenced via `"ignoreDeprecations"`. This represents formal deprecation.

### 4. Error in the checker

The final stage of deprecation.

## Contributions

It would be very easy to find folk willing to contribute these changes if the core team preferred that.

## FAQ

#### Will this disambiguate JSX? e.g. to safely allow JSX tags in regular `*.ts` files?

No. That's not the goal. There remain orthogonal issues blocking that.

The issue names no implementation files or tests. Start by reviewing the proposal's documentation, editor-feedback, and checker-deprecation stages, then determine which stage the maintainers want to pursue; done would mean an agreed, scoped change with corresponding validation.

Written by the indexing model from the issue text.