Select a discriminated-union variant
A union represents multiple object variants and a function needs one specific discriminant.
TypeScript · Type Alias
Extract
Extract filters a union by retaining the members of Type that are assignable to Union. It is a globally available built-in utility type for selecting compatible variants or types.
- Since
- 2.8
How it works
Extract is a built-in conditional utility type that filters a union. It produces a new type containing the members of Type assignable to Union, which is useful for selecting specific variants from broad unions.
Syntax
Extract<Type, Union>Parameters
| Name | Type | Description |
|---|---|---|
Type | type | The source type whose union members are tested. |
Union | type | The type that retained members must be assignable to. |
Returns
A type containing the members of Type that are assignable to Union.
Key points
- Extract is a built-in utility type, so it can be used without importing a library helper.
- Its generic form takes a source type and a union-like matching type: Extract<Type, Union>.
- The result retains every member of Type that satisfies assignability to the second parameter.
- For a literal union, matching literals are preserved precisely rather than widened to a general string.
- It can select structural function types from a mixed union when the function type matches Function.
Common mistakes
- The second argument is an assignability test, not a value-level predicate; only union members assignable to it remain.
Example: Filtering a discriminated union
type Shape =
| { kind: "circle"; radius: number }
| { kind: "square"; sideLength: number };
type Circles = Extract<Shape, { kind: "circle" }>;
const circle: Circles = { kind: "circle", radius: 10 };Extract keeps only the Shape union member whose kind is "circle".
When to use it
Keep members matching a structural type
A broad union mixes primitives and callable values.
Build reusable union filters
A generic API needs to narrow a union according to a caller-provided constraint.
Interview questions
QWhat does Extract do?
Extract<Type, Union> returns the subset of Type's union members that are assignable to Union. For example, Extract<"a" | "b" | "c", "a" | "f"> evaluates to "a".
Follow-up: How can you select one variant of a discriminated union? Use an object pattern such as Extract<Shape, { kind: "circle" }> so only the compatible member remains.
QWhere is Extract available, and does it run at runtime?
It is available globally as a utility type and operates on union members. It does not create a runtime value or perform runtime filtering.
Follow-up: What happens when Type is not a union? The same assignability test is applied to that type, producing it when compatible or never otherwise.
QWhen was Extract introduced, and what are its type parameters?
Extract was released in TypeScript 2.8. Its declaration has two type parameters: the source Type and the target Union used for the assignability check.
Follow-up: How does it differ from Exclude? Extract keeps members assignable to the second type, whereas Exclude removes those members.
Related
ExcludeNonNullableReturnTypeInstanceType