Repository: TypeScript
Issue: Feature Request: @error -- @deprecated that is always an error
Labels: Suggestion,In Discussion

# Suggestion


<!--
  Please fill in each section completely. Thank you!
-->

## 🔍 Search Terms
overload, deprecated, error, error message.

List of keywords you searched for before creating this issue. Write them down here so that others can find this suggestion more easily and help provide feedback.

## ✅ Viability Checklist


My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).


## ⭐ Suggestion

Typescript type constraints are great for preventing issues at run-time and surfacing them at write-time. However, constraints that provide strong guarantees can often be complicated -- and the meaning behind those constraints can get lost.

I suggest adding an `@error` tsdoc directive which works identically to `@deprecated`, but which always makes it an error to use that value -- and surfaces the annotation *as* the error for API users to see. This allows annotation of type errors by matching types, as well as making a stronger deprecation for security static analysis.

## 📃 Motivating Example


## Example 1: Safe Types
```typescript
interface RunScript {
   /** runs a script which is known to be safe */
   (script: SafeScript): void

   /**
     * @error It is dangerous to run untrusted scripts!
     * @see https://github.com/myproject/docs/untrustedscripts
     */
    (script: string): never
}

declare const runScript: RunScript;

runScript("alert(1)") // error: It is dangerous to run untrusted scripts! [...]
```
## Example 2: Mutually Exclusive Fields

In this example, it is an implementation detail that `srcdoc` and `src` are mutually exclusive. However, it's not usually well surfaced *why* they are mutually exclusive.

```typescript
interface createIframe {
   (props: { src: string, srcdoc?: undefined }): HTMLIframeElement
   (props: { src?: undefined, srcdoc: string}): HTMLIFrameElement
   /** @error `src` and `srcdoc` together are ambiguous, see http://doc.com/whaterver */
   (props: { src: string, srcdoc: string }): never
}
```

## Example 3: Blocking Unsafe Globals (similar to [playground](https://www.typescriptlang.org/play?#code/KYDwDg9gTgLgBAbwL4G4BQaAmwDGAbAQymDgHM8IAjAvRNOBuASwDsZgoAzAnEgUTzAAtsDZ1GEuAHoAVDLgABbGGI4C7THEwQ4LCPACuAZxIyp9SQ1YsOACQAqAWQAyALjhGYUVqQsMkaAFYEDgGImwAdJQQmACeEdZ2Ts5AA))
```typescript
export {};

declare global {
    interface Element {
        /** @error do not use */
        innerHTML: string
    }
}
```

## Example 4: Blocking Unsafe Calls

It would be nice if `@error` could take precedence over other matches. Sadly, even `@deprecated` doesn't do this right now.

```typescript
export {};

declare global {
    interface Window {
        setTimeout: {
            /** @error calling setTimeout with a string allows `eval()`! */
            (value: string): any
        }
    }
}

window.setTimeout("10", 10) // error: calling setTimeout with a string allows `eval()`!
```


## 💻 Use Cases

There are two primary use cases as I see it:

1. Documenting common invalid types for APIs to help steer API users directly.
2. Using module augmentation to prevent unsafe APIs being used that would otherwise cause security issues.
3. Expressing APIs that are runtime errors, not deprecations (especially for security reasons), like React's recent removal of `javascript:` URIs as valid in `<a>` tags.

In the meantime, I'm simply marking these things as deprecated and hoping for the best.