x is T Custom Type Guards & Assertion Functions

Last updated: 2026-10-22

x is T Custom Type Guards & Assertion Functions

When built-in guards (typeof/instanceof/in) fall short, write your own guard function: declare its return type as x is T (a type predicate) and TypeScript narrows x to T in branches where the function returns true. Its sibling is the assertion function (asserts x is T), which does not return a boolean but throws on failure.

ℹ️ Info The editor transpiles TypeScript to JavaScript and runs it (no type checking); see each example's Output for type-check results.

📝 Syntax

// Type predicate: x is narrowed to T where the function returns true
function isFoo(x: unknown): x is Foo {
  return typeof x === "object" && x !== null && "foo" in x;
}

// Assertion function: throws when invalid; x is treated as T afterwards
function assertFoo(x: unknown): asserts x is Foo {
  if (!isFoo(x)) throw new Error("not a Foo");
}

⚙️ Parameters

Returns：A predicate function is an ordinary boolean function at runtime; narrowing happens at compile time. An asserts function returns nothing (void) at runtime and signals failure by throwing.

▶ Example

Edit the code below and click Try it to see the transpiled result:

Output：

failed: 404
data: x,y

(Runtime output after transpilation; once isFailure returns true, res is narrowed to ApiError and res.data type-checks — narrowing is guaranteed statically by tsc, at runtime there are only values)

💡 Notes

🏷️ Related Narrowing & Assertions

💡 Related cases

📚 Related tutorials

❓ FAQ

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us