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 &&.
function size(value: string | string[]) { const isText = typeof value === "string"; return isText ? value.length : value.length * 100; }
Try it
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.
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
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
letor 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
constis 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 } = shapestill narrowsradiuswhen you testkind, as long as the variables areconst. - 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.