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.

まず、TypeScript における既存の @deprecated の処理を確認し、次に、オーバーロード解決と型チェックが issue の例をどのように扱うかを追跡します。これらの例全体で提案されている @error の動作を比較し、実行時の JavaScript 出力を維持しながら、そのアノテーションテキストを診断として表示することも含めて検討します。