How the TypeScript Extract Type Works

The Extract utility type lets us check a union type for specific members, and returns a new type based on what is leftover. It's quite similar in format to the Exclude type.

Let's find out how it works.

Utility Types

Utility Types are types defined in TypeScript to solve particular problems. If you're new to defining custom types in TypeScript, read my guide on defining custom types here.

How the Extract Type Works in Typescript

In TypeScript, we can define a specific type called a union type. A union type is a list of possible values for something. An example is shown below, where the type myUnionType means variables and other outputs can only be one of four values: x, y, z, or a.

type myUnionType = "x" | "y" | "z" | "a"

// This works since x is a member of "x" | "y" | "z" | "a"
let myFirstVariable:myUnionType = "x"

// This doesn't work since "my-string" is NOT member of "x" | "y" | "z" | "a"
let mySecondVariable:myUnionType = "my-string"

The Extract Type

If we want to remove specific elements from a union type, we can use the Exclude Type - but there are other ways we can manipulate union types.

The Extract Type lets us define a new list, and returns a new type if any items in that list exist in our original type.

Let's look at a quick example:

type myUnionType = "x" | "y" | "z" | "a"

let myFirstVariable:Extract<myUnionType, "x" | "y"> = "x"
//  ^
//  └ - - Type is "x" | "y"

When we write Extract, Extract checks myUnionType for "x" | "y". If they exist, it makes a new type containing the items that exist. Since both x and y exist in our union type, we end up with a new type - "x" | "y".

If we define members in our Extract statement that don't exist in our original union type, then they will be ignored in the new type. For example:

type myUnionType = "x" | "y" | "z" | "a"

let myFirstVariable:Extract<myUnionType, "x" | "y" | "b"> = "x"
//  ^
//  └ - - Type is STILL "x" | "y" since "b" is not in myUnionType

Using Extract does not affect the original type, so we can still use it if we want:

type myUnionType = "x" | "y" | "z" | "a"

let myFirstVariable:Extract<myUnionType, "x" | "y" | "b"> = "x"
//  ^
//  └ - - Type is "x" | "y"

let mySecondVariable:myUnionType = "z"
//  ^
//  └ - - Type is "x" | "y" | "z" | "a"

Extract, therefore, is a great tool when we want to limit our original union type to a set number of defined members for specific variables or outputs. It gives us flexibility in letting us define types on the fly, which we can use anywhere in our code.