Union dispatch
Select the correct object shape from a union before reading shape-specific fields.
TypeScript · Const
in
TypeScript recognizes JavaScript’s in property check as a type guard. It narrows union members based on whether the tested key is required, optional, or unlisted.
- Since
- 2.7
How it works
The in operator checks whether an object or its prototype chain has a property. TypeScript uses that runtime check to narrow a union: the true branch keeps members with an optional or required property, while the false branch keeps members with an optional or missing property.
Syntax
propertyKey in objectParameters
| Name | Type | Description |
|---|---|---|
propertyKey | string | number | symbol | The property key to test; it must be assignable to string | number | symbol. |
value | object | The value whose object or prototype chain is tested; it must be assignable to object. |
Returns
A boolean indicating whether the property exists on the object or anywhere on its prototype chain.
Key points
inperforms a runtime property-presence test, including inherited properties.- The runtime result directly participates in control-flow type analysis.
- The documented union-narrowing form uses a string literal key, or a type representing one.
- A successful check retains union members declaring the key as required or optional.
- For an unlisted key, newer TypeScript versions add a record intersection so the checked property can be accessed and narrowed further.
Common mistakes
- The value being checked must be an object; using a primitive on the right side is rejected.
- The property key must be a valid JavaScript property key rather than an arbitrary value.
- A false result does not mean the property is absent from every remaining type, because optional properties can still belong to the narrowed union.
Example: Narrow a union with `in`
type Order =
| { email: string }
| { callerNumber: string };
function contact(order: Order): string {
if ("email" in order) {
return order.email;
}
return order.callerNumber;
}
console.log(contact({ email: "dev@example.com" }));The property check selects the union member whose shape contains the tested key, allowing the corresponding property to be used safely.
When to use it
Unknown object inspection
Validate dynamic or unknown object data by checking for a key, then narrowing that property independently.
Shape-based routing
Distinguish structurally different request, event, or command variants without adding a separate tag field.
Interview questions
QHow does in narrow a discriminated union?
It is a JavaScript property-existence check that TypeScript also treats as a type guard. For a union, the true branch retains members with the tested property, including optional properties.
Follow-up: What happens with an unknown value? The check first narrows it to an object-like type containing the tested key, represented as an intersection with Record<key, unknown>.
QWhat does the false branch guarantee?
The false branch retains union members where the property is optional or not declared. Therefore, it is not equivalent to proving that no runtime property exists on the value.
Follow-up: Why can a prototype property affect the result? JavaScript's in operator examines the object and its prototype chain, not only own properties.
QWhat operand constraints does TypeScript enforce?
The left operand must be assignable to string | number | symbol, and the right operand must be assignable to object. These checks prevent invalid property-key and primitive checks.
Follow-up: How can an unknown input be handled safely? First establish that it is an object, then use in, and narrow the resulting property value separately.
Related
Narrowingtype guardsunion typesRecordunknownoptional properties