Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Type Operators

TypeScript type predicates (x is T)

Reference for TypeScript type predicates: write custom type guard functions with x is T, narrow in both branches, filter arrays and avoid unsound guards.

A type predicate is a special return type, parameter is Type, that turns a function into a user-defined type guard. When the function returns true, TypeScript narrows the argument to Type in the calling code; when it returns false, the argument is narrowed to whatever remains.

The compiler trusts your predicate. It does not check that the function body really tests for Type, so the guard is only as honest as your implementation.

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

Try it

TypeScript A guard for unknown input

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 arrays and this-guards

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 name(param: Input): param is Narrowed { ... }
const guard = (x: Input): x is Narrowed => ...;
method(): this is Narrowed { ... }
Part Description
param Must be the name of one of the function's parameters.
Narrowed The type assumed when the function returns true. It must be assignable to the parameter's type.
this is T A predicate on the receiver, used in class and interface methods.

Returns: a boolean at runtime. In the false branch the argument is narrowed by excluding Narrowed, which only works well when the input is a union.

Since TypeScript 5.5 the compiler can infer a predicate for simple functions such as x => x !== undefined, so explicit annotations are mostly needed for complex checks or for older versions.

Usage notes

  • Unsound guards compile. A function that always returns true with a predicate for string is accepted. Keep the body a real check.
  • The false branch is a promise too. If your guard returns false for some values that are actually Narrowed, those values are wrongly excluded afterward. Make the check exact in both directions.
  • Prefer simple typeof, in and instanceof checks inline when used once; reach for a predicate when the check is reused or complicated.
  • Array filtering: .filter(isString) narrows the result element type.
  • Validation libraries produce predicates (or assertion functions) from schemas so you can narrow parsed JSON.
  • Methods and callbacks: predicates work as callback parameters, but a wrapper arrow function loses narrowing unless it declares its own predicate.