Clarify treatment of unreachable code due to type analysis

[marcandre]

Suggestion

Clarify official position on unreachable code due to static typing.

🔍 Search Terms

unreachable code allowUnreachableCode 7027

✅ 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

Code can be unreachable because of javascript itself, or because of type annotations (but potentially reachable at runtime).

The documentation for allowUnreachableCode states that it affect the former but that it "does not affect errors on the basis of code which appears to be unreachable due to type analysis".

1. This seems to be inaccurate since ~3.7 that introduced never:

Here's an example with an implicit never from microsoft/TypeScript#39386:

const hel2 = (x: number) => {
  switch (typeof x) {
    case 'number': return 0
  }
  x    // Unreachable code detected
}

An example with an explicit never from microsoft/TypeScript#34879:

declare function foo(): never

function bar() {
    foo()
    return 1 // unreachable code detected
}

In both of these examples, it is possible to reach this code at runtime if using javascript code that does not respect the type annotations. The allowUnreachableCode config affects the error reporting.

2. The documentation does not state what is the expected behavior of code unreachable due to type annotations.

3. It is very useful to detect unreachable code (of either kind) as these are almost always due to errors in the code. I hope that typescript will be able in the future to report more of these cases (I am opening for this; other example is Detect unreachable code in more scenarios TypeScript#39995).

These errors could either be grouped together, or else a new kind of error (with a corresponding config flag) should be created. In all cases documentation should describe the current state of affairs.

[DanielRosenwasser]

I think the docs just need to be fixed. We assume you're not trying to intentionally bungle your types and lie, otherwise this sort of warning isn't as useful.

[typescript-bot]

Hello! As per #2804, we are automatically closing all open issues. Please see #2804 for a description of what issues and PRs can be accepted going forward.