Type Narrowing: unknown, Guards & Predicates

Not every value flowing through a program has a known type up front, JSON parsed from a network response, user input, data from a library without types. TypeScript gives you unknown for exactly that, plus tools to narrow it down safely.

TypeScript

function parseConfig(raw: unknown) {
  if (typeof raw !== 'object' || raw === null) {
    throw new Error('Config must be an object');
  }
  // raw is narrowed from unknown to `object` here, but its properties still aren't known
  console.log(raw);
}

function parseConfig(raw: unknown) {
  if (typeof raw !== 'object' || raw === null) {
    throw new Error('Config must be an object');
  }
  // raw is narrowed from unknown to `object` here, but its properties still aren't known
  console.log(raw);
}

unknown vs any

any turns off type checking entirely, unknown still forces you to prove what a value is before you can use it.

TypeScript

function useAny(value: any) {
  value.toUpperCase(); // ✅ compiles, but crashes at runtime if value isn't a string
}

function useUnknown(value: unknown) {
  value.toUpperCase(); // ❌ compile error: value is still 'unknown'
  if (typeof value === 'string') {
    value.toUpperCase(); // ✅ narrowed to string, now this is safe
  }
}

function useAny(value: any) {
  value.toUpperCase(); // ✅ compiles, but crashes at runtime if value isn't a string
}

function useUnknown(value: unknown) {
  value.toUpperCase(); // ❌ compile error: value is still 'unknown'
  if (typeof value === 'string') {
    value.toUpperCase(); // ✅ narrowed to string, now this is safe
  }
}

unknown is the type-safe way to accept "could be anything," it makes the compiler force every caller to check before touching the value, any just gets out of the way and hopes for the best.

Narrowing with typeof, instanceof, and in

TypeScript

type Input = string | number | Date;

function describe(value: Input): string {
  if (typeof value === 'string') return value.toUpperCase();      // typeof narrows primitives
  if (value instanceof Date) return value.toISOString();          // instanceof narrows classes
  return value.toFixed(2);                                        // only number is left
}

interface Cat { meow(): void }
interface Dog { bark(): void }

function speak(pet: Cat | Dog) {
  if ('meow' in pet) pet.meow();  // 'in' narrows by checking for a property
  else pet.bark();
}

type Input = string | number | Date;

function describe(value: Input): string {
  if (typeof value === 'string') return value.toUpperCase();      // typeof narrows primitives
  if (value instanceof Date) return value.toISOString();          // instanceof narrows classes
  return value.toFixed(2);                                        // only number is left
}

interface Cat { meow(): void }
interface Dog { bark(): void }

function speak(pet: Cat | Dog) {
  if ('meow' in pet) pet.meow();  // 'in' narrows by checking for a property
  else pet.bark();
}

Custom type predicates

For shapes typeof/instanceof/in can't fully describe, write your own narrowing function with an is return type.

TypeScript

interface Task {
  id: string;
  title: string;
}

function isTask(value: unknown): value is Task {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'title' in value
  );
}

function handle(value: unknown) {
  if (isTask(value)) {
    console.log(value.title); // narrowed to Task, .title is safe here
  }
}

interface Task {
  id: string;
  title: string;
}

function isTask(value: unknown): value is Task {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'title' in value
  );
}

function handle(value: unknown) {
  if (isTask(value)) {
    console.log(value.title); // narrowed to Task, .title is safe here
  }
}

value is Task tells the compiler: "if this function returns true, treat value as a Task from this point on." It's not checked for correctness, a wrong isTask will lie to the compiler, so the logic inside still has to be right.

WARNING

Reach for unknown, not any, whenever a value's type genuinely isn't known yet (parsed JSON, a library return value). any is easy in the moment but silently reintroduces every bug static types exist to prevent.

Type Narrowing: unknown, Guards & Predicates

unknown vs any

Narrowing with typeof, instanceof, and in

Custom type predicates

📝 Narrowing Quiz