Feature Request: @error -- @deprecated that is always an error

Suggestion

🔍 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:

• 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 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

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.

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)

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.

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.

Start by reviewing TypeScript's existing @deprecated handling, then trace how overload resolution and type checking treat the examples in the issue. Compare the proposed @error behavior across those examples, including surfacing its annotation text as a diagnostic while preserving runtime JavaScript output.