Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Narrowing and Type Guards

Control flow analysis in TypeScript

Explains TypeScript control flow analysis: declared versus narrowed types, assignments, early returns, loops, closures, try and finally, and what resets narrowing.

Control flow analysis is the compiler's way of following your code line by line. Every variable has a declared type, but at each point in the code TypeScript also tracks the narrowed type: the set of values the variable can hold there, given the checks and assignments that came before.

Checks such as typeof, ===, in and instanceof narrow inside the branch they guard. Assignments narrow too. return, throw, break, continue and calls to functions returning never end a path, and code after an if that always exits sees the narrowed type of the other path.

TypeScript
function f(x: string | number) {
  if (typeof x === "string") return;
  x; // number: the string path has returned
}

Try it

TypeScript Early return and assignment narrowing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Declared type versus narrowed type

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Narrowing resets in closures

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

There is no syntax: the analysis is automatic. What narrows a type:

Construct Effect
typeof, instanceof, in, ===, !==, truthiness Narrow within the guarded branch (and the opposite branch for the remaining types).
Assignment x = value The narrowed type becomes the assigned value's type, filtered by the declared type.
return, throw, continue, break End the path; code afterwards sees only the other paths.
Call to a function returning never Ends the path, if the function is declared with an explicit type.
asserts functions Narrow the rest of the scope.
Loops and try/catch/finally The types from all paths that can reach a point are merged (a union).

Edge cases:

  • Narrowing is lost when the compiler cannot prove a variable is unchanged, for example a let or a property modified in a callback.
  • At a function call, the compiler does not assume that property narrowing (obj.value) is invalidated, even though the callee could change it. This is a deliberate trade-off.

Usage notes

  • Prefer const. A const or a never-reassigned parameter keeps its narrowing inside later callbacks. Narrowing of a let that is assigned after the closure is created does not.
  • Narrowing follows references. Variables, parameters, this, and property access chains such as a.b.c narrow. Computed element access narrows with literal keys, and with const keys since TypeScript 4.7.
  • try/finally. In a finally block the type is the union of every type the variable had in the try. In catch blocks assume anything.
  • Unreachable code. Code after a return is reported only if allowUnreachableCode is false; otherwise it is greyed out.
  • Definite assignment. The same analysis decides "used before assigned" errors (TS2454) and noImplicitAny for let x; variables.
  • Debugging. Hover a variable in the editor or write const _check: never = x; to see its narrowed type in the error message.
  • Performance. Very large functions with many branches can slow down checking; split them up.