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.
function isString(x: unknown): x is string { return typeof x === "string"; }
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.
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
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 removesTfrom the argument type. A guard that returnsfalsefor some realTvalues 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
trueexactly when the value is aT. 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,findandsome. - 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 Tworks in methods of classes and interfaces, and helps with state classes such asfile.isOpen().- Assertion form. When you want a throw instead of a boolean, use an assertion function.