Skip to content

Type Predicate

In one line

'x is T' is a type guard return type that tells TypeScript to narrow the type in if/else branches.

In simple words

A type predicate is a function return type of the form parameterName is Type. When the function returns true, TypeScript narrows the parameter to that type in the if branch.

This is more powerful than a boolean return because it enables type narrowing. Without it, TypeScript only knows the function returns boolean — it can't narrow types.

Common use cases: checking if a value is a specific type (isString, isError), discriminating union members, validating API responses. The asserts keyword variant throws instead of returning boolean.

Example

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

function process(value: unknown) {
  if (isString(value)) {
    // value is narrowed to string here
    console.log(value.toUpperCase());
  } else {
    // value is still unknown here
  }
}

// Asserts variant — throws if false
function assertDefined<T>(val: T): asserts val is NonNullable<T> {
  if (val === null || val === undefined) throw new Error("Null");
}

value is string narrows the type in the if branch. asserts val is NonNullable<T> throws if the value is null/undefined.

Common confusions

  • Confused with: boolean return

    The difference: A boolean return tells TypeScript the function returns true/false but doesn't narrow types. A type predicate (x is T) tells TypeScript that when the function returns true, the parameter is of type T — enabling type narrowing in branches.

Related terms

Related Resources

Related Lessons

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary