Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Narrowing and Type Guards

The in operator and type narrowing

Reference for narrowing with the in operator in TypeScript: choosing union members by property, optional properties, unlisted keys and the unknown-key pitfalls.

The JavaScript in operator tests whether a property name exists on an object or anywhere on its prototype chain. TypeScript treats "name" in value as a type guard: in the true branch the type keeps the union members that have (or may have) that property, and in the false branch it keeps the members that do not require it.

This is the natural tool for unions of unrelated object shapes that have no shared tag field. If you control the types, a discriminant field is usually clearer.

TypeScript
type Fish = { swim(): void };
type Bird = { fly(): void };

function move(pet: Fish | Bird) {
  if ("swim" in pet) {
    pet.swim(); // pet: Fish
  } else {
    pet.fly(); // pet: Bird
  }
}

Try it

TypeScript Choosing a union member by property

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Optional properties keep both branches

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Narrowing unknown values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
"propertyName" in expression
Part Description
Left side A string literal, a unique symbol, a numeric literal or a value of type string, number or symbol. Only a literal key narrows.
Right side Must be an object type (or a type parameter or object-like type). Primitives are an error (TS2361).
Result boolean.

Edge cases:

  • If a union member declares the property as optional, it stays in both branches.
  • A member that does not mention the property at all stays in the false branch, and in the true branch it is kept only as an intersection with Record<"name", unknown> when no member declares it.
  • Since TypeScript 4.9, "x" in obj on an object or unknown-narrowed value adds the property with type unknown so you can read it.

Usage notes

  • Prototype chain. in also finds inherited names such as "toString", so "toString" in {} is true. For own properties use Object.hasOwn(obj, key), which does not narrow by itself.
  • Methods and data. in does not look at property values. A property that exists with the value undefined still counts.
  • Private fields. The related form #field in obj tests for a class's private field and narrows to that class (see private fields).
  • Reusable guards. Wrap the check in a user-defined guard when it appears in many places.
  • Fragile with extensible shapes. If a new union member also gets the property, the narrowing quietly becomes less precise. A tag field is more robust.
  • Not the loop form. for (const key in obj) is a separate statement; see the in keyword.