User-defined type guards

What a type predicate is

When you push validation into a helper function, the checker loses track of what the boolean result means — and gives you the full union back. Type predicates solve this: they let a reusable function participate in the same narrowing machinery that typeof and instanceof use inline.

A normal function returning boolean does not narrow anything for the caller — the checker has no idea what the true result means. A type predicate return annotation, arg is T, tells the checker: “when this returns true, treat arg as T; when false, subtract T.”

function isString(x: unknown): x is string {
  return typeof x === "string";
}

function handle(v: string | number) {
  if (isString(v)) {
    v;
    // ^? string   — the predicate narrowed it, exactly like a built-in guard
    return v.toUpperCase();
  }
  v;
  // ^? number    — the false branch subtracts string
}

The predicate parameter (x / the named arg) must be one of the function’s parameters or this. The return type x is T replaces the plain boolean — at runtime the function still just returns a boolean.

The checker trusts you unsoundly

This is the part to internalize: TypeScript does not verify that the predicate body actually proves the claimed type. The is T annotation is an assertion you make; the checker takes it on faith. A guard whose body does not match its predicate compiles cleanly:

type User = { id: string; email: string; roles: string[] };

// LYING guard — body checks far less than the predicate claims
function isUser(x: unknown): x is User {
  return typeof x === "object" && x !== null;
}

const maybe: unknown = { id: "u1" };   // no email, no roles
if (isUser(maybe)) {
  maybe.email.toLowerCase();
  // ^? the checker thinks maybe: User, email: string
  // Runtime: TypeError — email is undefined
}

No error at compile time. The predicate is a contract you alone are responsible for honoring. A correct guard checks every field the predicate promises:

function isUser(x: unknown): x is User {
  return (
    typeof x === "object" && x !== null &&
    "id" in x && typeof (x as Record<string, unknown>).id === "string" &&
    "email" in x && typeof (x as Record<string, unknown>).email === "string" &&
    "roles" in x && Array.isArray((x as Record<string, unknown>).roles)
  );
}

in-based guards and discriminating without a tag

When members have no shared literal tag, an in check inside a predicate narrows structurally:

type WithData = { data: string };
type WithError = { error: string };

function hasData(r: WithData | WithError): r is WithData {
  return "data" in r;
}

This works, but it is fragile: if both members could carry a data key (even optionally), the in test no longer distinguishes them. Prefer an explicit discriminant tag when you control the shapes — that is the next lesson.

Guards for arrays and records

A common need is narrowing unknown (e.g. JSON) to a typed array. The predicate must check the container and a sample of elements — but checking only one element is itself an unsound shortcut:

function isStringArray(x: unknown): x is string[] {
  return Array.isArray(x) && x.every((e) => typeof e === "string");
}

function isRecordOfNumbers(x: unknown): x is Record<string, number> {
  return (
    typeof x === "object" && x !== null && !Array.isArray(x) &&
    Object.values(x).every((v) => typeof v === "number")
  );
}

x.every(...) over the whole array is honest; typeof x[0] === "string" (sampling one element) is a lie that the checker still believes. The cost of every is real for huge arrays — which is exactly why parse-once-at-the-boundary (validate the payload when it enters the system) beats re-guarding everywhere.

A glance ahead: assertion functions

A close cousin throws instead of returning a boolean. An assertion function uses asserts x is T: if it returns normally, the checker narrows x to T for the rest of the scope — no if needed:

function assertUser(x: unknown): asserts x is User {
  if (!isUser(x)) throw new Error("not a User");
}

function f(x: unknown) {
  assertUser(x);
  x;
  // ^? User   — narrowed from here on, because control only continues if it did not throw
}

The same unsound trust applies, plus the obligation to actually throw on the negative case. You will study assertion functions in depth in unit 06 (functions-this).