What is a user-defined type guard?

Question

Accepted Answer

A **user-defined type guard** is a function whose return type is a **type predicate** (`x is T`). When it returns `true`, the compiler narrows the argument to `T` in the calling code — letting you encapsulate custom runtime checks.

```ts
interface Cat { meow(): void; }
interface Dog { bark(): void; }

// the magic is the return type `pet is Cat`, not just `boolean`
function isCat(pet: Cat | Dog): pet is Cat {
  return "meow" in pet;
}

function speak(pet: Cat | Dog) {
  if (isCat(pet)) {
    pet.meow(); // ✅ narrowed to Cat
  } else {
    pet.bark(); // ✅ narrowed to Dog
  }
}
```

Without the `pet is Cat` predicate, `isCat` returning `boolean` would *not* narrow `pet` — the compiler would still see `Cat | Dog` inside the `if`. The predicate is what teaches it.

## Validating unknown external data

```ts
interface User { id: number; name: string; }

function isUser(x: unknown): x is User {
  return (
    typeof x === "object" && x !== null &&
    typeof (x as any).id === "number" &&
    typeof (x as any).name === "string"
  );
}

const data: unknown = await res.json();
if (isUser(data)) data.name; // ✅ safely typed as User
```

## Caveat

The compiler **trusts** your predicate — if the body's logic is wrong, you get an unsafe narrowing. For complex shapes, a schema validator (zod) generates correct guards for you.

## Why it matters

Type guards let you turn arbitrary runtime checks into reusable narrowing functions — essential for validating `unknown` data at API/boundaries and for distinguishing members of a union when a simple `typeof`/`in` check isn't enough on its own.