TypeScript Reference ยท Narrowing and Type Guards
Inferred type predicates in TypeScript
Reference for inferred type predicates in TypeScript 5.5 and later: when the compiler infers x is T for you, filter(x => x !== null), and when it does not.
Since TypeScript 5.5 the compiler can infer a type predicate for a function that has no return type annotation. If the function takes one parameter, returns a boolean expression, and that expression is true exactly when the parameter is a narrower type, TypeScript gives the function the return type x is T on its own.
The most visible effect is on Array.prototype.filter: values.filter((v) => v !== undefined) now returns an array without undefined, with no hand-written type guard needed.
const mixed = [1, null, 2, undefined]; const numbers = mixed.filter((x) => x !== null && x !== undefined); // number[] in TypeScript 5.5 and later
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
There is no new syntax: you write a normal function and the compiler adds x is T to its signature. To see it, hover the function in an editor, or inspect the emitted .d.ts file.
For a predicate to be inferred, all of these must hold:
| Condition | Description |
|---|---|
| No return type annotation | An explicit return type always wins. |
| One return statement | And no implicit returns (an arrow function with an expression body counts). |
| Does not mutate the parameter | Reassigning it disables inference. |
| Returns a boolean expression | Tied to narrowing of the parameter. |
| "If and only if" | If the function returns true, the parameter is of type T; if it returns false, the parameter is not T. |
Edge cases:
- The "if and only if" condition is why
(x) => !!xonnumber | nullinfers nothing: afalseresult does not prove the value isnull. - The inferred predicate appears in generated declaration files, so it becomes part of your public API.
Usage notes
- Version note. Added in TypeScript 5.5. Code that relied on a manual
filter(isDefined)guard keeps working, and the guard is now optional. - Check the "false" direction. The classic trap is a check like
(x) => x.length > 0. It does not prove anything about a type, so no predicate is inferred; that is fine and safe. - Explicit guards stay useful. Write one when the check is complex, shared across files, or needs to be stable in your
.d.tsoutput regardless of compiler inference. - Truthiness on objects. For
Foo | undefined,(x) => !!xdoes inferx is Foo, because an object is always truthy. For strings, numbers and booleans it does not, since"",0andfalseare falsy members of their own type. - Surprises. A function that used to return
booleannow returns a predicate, which can change inference at call sites (for example, infindandsome). Occasionally this exposes mistakes in old code.