Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Narrowing and Type Guards

User-defined type guards in TypeScript

Reference for user-defined type guards in TypeScript: the x is T return type, this is T, filtering arrays, validating unknown data and guards that lie.

A user-defined type guard is a function whose return type is a type predicate, written parameter is Type. The function returns a boolean. When a caller sees true, TypeScript narrows the argument to Type; when it sees false, the argument is narrowed to whatever remains.

Use one when the built-in checks (typeof, in, instanceof, equality) are not enough: validating unknown data, recognizing a shape that has no tag, or giving Array.prototype.filter a precise result type.

TypeScript
function isString(x: unknown): x is string {
  return typeof x === "string";
}

Try it

TypeScript Validating unknown data

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 Filtering with a guard

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 A guard that lies

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
function isT(x: unknown): x is T { ... }
const isT = (x: unknown): x is T => ...;
class A { isB(): this is B { ... } }
Part Description
x is T The predicate. x must be the name of a parameter of this function.
T The type to narrow to. It must be assignable to the parameter's declared type.
this is T A guard on the receiver, used in classes and interfaces.

Edge cases:

  • When the guard returns false, TypeScript removes T from the argument type. A guard that returns false for some real T values therefore makes the "else" branch wrong.
  • A predicate type that is not assignable to the parameter type is error TS2677.
  • The predicate form is only allowed as a return type annotation; it cannot be used on variables or properties.

Usage notes

  • TypeScript does not check the body. The compiler trusts the predicate. A wrong guard silently produces wrong types, as the last example shows. Test guards well.
  • Write both directions. A correct guard returns true exactly when the value is a T. Narrowing in the false branch depends on it.
  • Keep guards small and honest. For large shapes, a schema library (see runtime validation) is less error-prone than hand-written checks.
  • Guards are normal functions. They can be exported, passed as callbacks and used with filter, find and some.
  • Inference. Since TypeScript 5.5 many simple callbacks get their predicates inferred, so arr.filter((x) => x !== null) already narrows. See inferred type predicates.
  • this is T works in methods of classes and interfaces, and helps with state classes such as file.isOpen().
  • Assertion form. When you want a throw instead of a boolean, use an assertion function.