Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Narrowing and Type Guards

Narrowing through aliased conditions

Reference for aliased condition narrowing in TypeScript: store a type check in a const and use it later in an if, and learn when the alias stops working.

An aliased condition is a boolean expression that you store in a const and test later. Since TypeScript 4.4, the compiler remembers what the stored expression proved, so if (alias) narrows the original variable just as if you had written the full check inline.

This lets you give a long or repeated check a readable name without losing narrowing. It works for typeof, instanceof, discriminant checks, equality checks and combinations of them with &&.

TypeScript
function size(value: string | string[]) {
  const isText = typeof value === "string";
  return isText ? value.length : value.length * 100;
}

Try it

TypeScript Naming a check

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 Combined conditions and where it stops

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

TypeScript
const alias = <condition on a reference>;
if (alias) { /* the reference is narrowed here */ }
Part Description
alias Must be declared with const, or be a readonly property, or be a parameter that is never assigned in the function body.
Condition Any narrowing expression: typeof, instanceof, in, ===, Array.isArray(), a call to a type guard, or && combinations of these.
Narrowed reference Must itself be a const variable, a readonly property, or a parameter that is never reassigned.

Edge cases:

  • The compiler follows up to five levels of aliases. Deeper chains stop narrowing.
  • If the narrowed variable is a let or is assigned anywhere in the function, the alias has no effect.
  • Aliases combined with || narrow in the true branch only as far as the union of both sides allows.

Usage notes

  • The alias must be evaluated before the check, so narrowing reflects the state at the point where the alias was created. Reassigning a const is impossible, which is why the rule is safe.
  • Parameters work as long as nothing writes to them. One assignment anywhere in the function disables aliased narrowing for that parameter.
  • Narrowing by alias is limited to the same function. The check cannot be moved out into another function unless that function is a type guard (x is T).
  • Destructured discriminated unions (supported since TypeScript 4.6) build on the same idea: const { kind, radius } = shape still narrows radius when you test kind, as long as the variables are const.
  • A named condition documents intent. Prefer const isExpired = ... over repeating the expression, but keep it close to where it is used.
  • For checks you want to reuse in many places, write a user-defined type guard instead of an alias.