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.
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
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.
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.
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
"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 objon anobjectorunknown-narrowed value adds the property with typeunknownso you can read it.
Usage notes
- Prototype chain.
inalso finds inherited names such as"toString", so"toString" in {}istrue. For own properties useObject.hasOwn(obj, key), which does not narrow by itself. - Methods and data.
indoes not look at property values. A property that exists with the valueundefinedstill counts. - Private fields. The related form
#field in objtests 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.