TypeScript Type Guard: Check the Type of an Object

A type guard is a runtime check that TypeScript understands, so it narrows the type inside the checked branch. typeof, instanceof and in are built-in guards; for anything else, you write a function whose return type is a type predicate, value is Type.

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

isUser returns a plain boolean at run time. The value is User return type tells the compiler what a true result proves, and every if (isUser(x)) then narrows x to User.

Built-in Type Guards

These checks narrow without any helper function:

They all run as ordinary JavaScript. What TypeScript adds is the narrowing: it reads the check and adjusts the type in each branch. The full list of forms is on the type narrowing page. A custom guard is for checks that do not fit in one expression, or that you want to reuse.

Writing a Type Predicate

A type predicate has the form parameterName is Type and replaces boolean as the return type. The narrowing works in both directions: true narrows to Type, and false removes Type from a union.

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

Passing a guard to filter gives a correctly typed array. Since TypeScript 5.5 the compiler also infers a predicate from simple arrow functions, so pets.filter((p) => p.kind === "cat") returns Cat[] without a named guard.

The predicate's type must fit the parameter's type: function f(x: string): x is number is error TS2677, A type predicate's type must be assignable to its parameter's type.

The Compiler Trusts Your Guard

TypeScript checks that a guard returns a boolean. It does not check that the boolean is right. A guard that returns true for the wrong values makes the types lie, and the program fails at run time with no compile error.

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2) throws TypeError: Cannot read properties of undefined (reading 'toFixed') at run time. The compiler accepted data.price as a number because the guard said so. Check every property the rest of the code relies on, and keep guards small, tested and close to the type they describe.

Checking If an Object Is of a Type

This is the question behind most custom guards: data arrives as unknown (from JSON.parse, fetch, localStorage, a message) and you need to know whether it matches your interface. The recipe:

1. typeof value === "object" && value !== null (an object, not null).
2. "prop" in value for each required property. On unknown, in adds the property to the type as unknown.
3. typeof value.prop === "..." (or a nested guard) for each property's type.
4. Array.isArray(value.items) && value.items.every(isItem) for arrays.

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

For large or deeply nested shapes, writing these by hand gets tedious. Schema libraries such as Zod or Valibot let you describe the shape once and give you both the runtime check and the TypeScript type.

Assertion Functions: asserts value is Type

An assertion function throws if the check fails and returns normally otherwise. Its return type is asserts value is Type (or asserts condition), and everything after the call is narrowed, with no if needed.

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

One rule trips people up: an assertion function must be called through a name with an explicit type. A const arrow function without an annotation, const check = (v: unknown): asserts v is string => {...}, gives error TS2775 at the call site, Assertions require every name in the call target to be declared with an explicit type annotation. Use a function declaration, or annotate the constant with a function type.

Guards vs Assertions vs Casts

A type assertion (as) changes the type without checking anything. At a boundary where data comes from outside, a guard or an assertion function is the safe version of the same idea.

this-Based Guards in Classes

A method can narrow the object it is called on with this is Type. It is handy in class hierarchies:

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}