The infer keyword

Pull the item type out of a cart

Your code often has a big type and needs one part of it. A library gives you the type of a whole cart, a list of items, and you want the type of one item. A function returns an object, and you want that object's type. TypeScript can pull the part out for you, so you never write the same type twice. The keyword that does it is infer:

1type ItemOf<List> = List extends (infer Item)[] ? Item : never;2 3type Cart = { name: string; price: number }[];4type CartItem = ItemOf<Cart>;5//   ^?6const tea: CartItem = { name: "Tea", price: 3 };7console.log(tea.name);

Line 1 is a conditional type, from the Conditional types lesson: A extends B ? X : Y means "if type A fits B, the result is X, otherwise Y". The new part is infer Item. Read line 1 as a question with a blank in it:

• Is List a list of something, (…)[]?
• If yes, call that something Item, and the result is Item.
• If no, the result is never, the type that has no values (any, unknown & never covers it).

infer Item is the blank. It tells TypeScript: "work out what goes here, and call it Item".

Line 3 is the cart type: a list ([]) of objects with a name and a price. Line 4 asks ItemOf for the type of one item, and the query on line 5 shows the answer: { name: string; price: number }. You never wrote that type a second time. Line 6 uses it for the tea, and line 7 prints Tea.

How infer names part of a type

Why does the blank need a keyword? Try writing the pattern without it. TypeScript reports two errors, on purpose here:

1type ItemOf<List> = List extends Item[] ? Item : never;

Cannot find name 'Item' means TypeScript has never heard of a type called Item. It reports it twice: once in the pattern Item[], and once in the true branch ? Item. Every type name has to be made somewhere, for example with type Item = …, as a type parameter in <…>, or with infer. Here is what each part of the working version does:

• List extends … asks: does the type in List fit the pattern?
• (infer Item)[] is the pattern: a list of something. infer Item makes a new type name, Item, for whatever stands in that spot. The round brackets keep infer Item together; leave them out and TypeScript can't read the line.
• ? Item is the true branch: if the pattern fits, the result is the type TypeScript found.
• : never is the false branch: the result when the pattern doesn't fit.

Working out the type in the blank is called inference, the same word as when TypeScript works out that let total = 3 is a number (Type annotations & inference). That's where the keyword's name comes from. Now try it: type a different list type on line 3, and watch the answer after ^? on line 5 and the errors under the code.

1type ItemOf<List> = List extends (infer Item)[] ? Item : never;2 3type Tags = string[];4type Tag = ItemOf<Tags>;5//   ^?6const firstTag: Tag = "sale";7console.log(firstTag);

With number[], Tag becomes number, so storing "sale" on line 6 is an error. With (string | number)[] it's fine again. A plain string isn't a list at all: the pattern doesn't fit, ItemOf gives never, and nothing can be stored in a never. The same happens with readonly string[], a list you can't change, because the pattern describes a list you can change. Arrays and tuples covers read-only lists.

The name infer makes only lives in the true branch. Using it in the false branch is an error, on purpose here:

1type ItemOf<List> = List extends (infer Item)[] ? Item : Item;

The error is Cannot find name 'Item' again, this time once, for the last Item. When the pattern doesn't fit, there is nothing in the blank, so there is no Item to give back.

Return and parameter types of a function

A pattern can be any type with a blank in it, including a function type. A function type looks like an arrow function with types instead of code: (price: number) => string takes a number and returns a string (Function types covers them). Put the blank where the return type goes:

1type ReturnOf<Fn> = Fn extends (...args: any[]) => infer Result ? Result : never;2 3function getUser() {4  return { name: "Asha", cartItems: 2 };5}6 7type User = ReturnOf<typeof getUser>;8//   ^?9const user: User = { name: "Ravi", cartItems: 0 };10console.log(user.name);

Line 1's pattern is (...args: any[]) => infer Result. The part before the arrow, ...args: any[], is a rest parameter that accepts any arguments at all, so every function fits. It has to be any[] here, not unknown[]: a function that only takes a string can't take every value, so it wouldn't fit (...args: unknown[]). The blank sits after the arrow, where the return type goes.

Lines 3 to 5 are an ordinary function that returns a user. On line 7, typeof getUser gives the function's type. In a type, typeof followed by a value's name means "the type of this value" (keyof & typeof covers it); here that is () => { name: string; cartItems: number }. The query on line 8 shows what ReturnOf pulls out: { name: string; cartItems: number }. Line 9 makes another user of that type, and line 10 prints Ravi. When getUser changes, User changes with it.

Move the blank before the arrow, and you get the parameters instead:

1type ParamsOf<Fn> = Fn extends (...args: infer Params) => any ? Params : never;2 3function searchProducts(query: string, page: number) {4  return `${query} on page ${page}`;5}6 7type SearchArgs = ParamsOf<typeof searchProducts>;8//   ^?9const lastSearch: SearchArgs = ["tea", 2];10console.log(searchProducts(...lastSearch));

Line 1 puts the blank where ...args goes. A rest parameter collects every argument into one list, so Params is all of the parameters together, as a tuple: a list with a fixed length and a type for each place. The query on line 8 shows [query: string, page: number]. The words query: and page: are labels for each place; they don't change the type. Line 9 saves a search as a tuple, and line 10 spreads it back into a call and prints tea on page 2.

A pattern can also pick out one parameter. Here is the type of the event a click handler takes:

1type FirstParam<Fn> = Fn extends (first: infer First, ...rest: any[]) => any ? First : never;2 3function onCartClick(event: MouseEvent, productId: number) {4  console.log(productId);5}6 7type ClickEvent = FirstParam<typeof onCartClick>;8//   ^?

Line 1's pattern has two parameters: first: infer First catches the first one, and ...rest: any[] accepts any others. Lines 3 to 5 are a click handler that takes the browser's MouseEvent and a product id. The query on line 8 shows ClickEvent is MouseEvent.

Unwrapping promises and lists

An async function always returns a promise, even when its code returns a plain object. So its return type is wrapped in Promise<…>. To reach the value inside, put the blank inside the promise:

1type ReturnOf<Fn> = Fn extends (...args: any[]) => infer Result ? Result : never;2type Unwrap<T> = T extends Promise<infer Value> ? Value : T;3 4async function fetchUser() {5  return { name: "Asha", cartItems: 2 };6}7 8type Reply = ReturnOf<typeof fetchUser>;9//   ^?10type User = Unwrap<Reply>;11//   ^?

Line 1 is ReturnOf from before. Line 2 is new: its pattern is Promise<infer Value>, a promise of something. Lines 4 to 6 are an async function that returns a user. Line 8 asks for its return type, and the query on line 9 shows it's a promise: Promise<{ name: string; cartItems: number }>. Line 10 unwraps it, and the query on line 11 shows the user object itself.

Look at Unwrap's false branch: it's T, not never. When T isn't a promise, you get it back unchanged. You choose what the false branch gives. Try it with different replies:

1type Unwrap<T> = T extends Promise<infer Value> ? Value : T;2 3type Reply = Promise<string>;4type Name = Unwrap<Reply>;5//   ^?6const name: Name = "Asha";7console.log(name);

A promise of text gives string. Plain text gives string too, from the false branch. A promise of a number gives number, so line 6 is an error. A promise in a promise gives Promise<string>: Unwrap opened one layer and stopped. When the code runs, the types are gone, so it prints Asha every time.

To open every layer, let the true branch call Unwrap again on what it found:

1type UnwrapAll<T> = T extends Promise<infer Value> ? UnwrapAll<Value> : T;2 3type Reply = Promise<Promise<string>>;4type Name = UnwrapAll<Reply>;5//   ^?6const name: Name = "Asha";7console.log(name);

Line 1's true branch is UnwrapAll<Value>: it unwraps what it found, again and again, until the false branch gives back something that isn't a promise. A type that uses itself like this is called recursive. Line 3 is a promise in a promise, and the query on line 5 shows string. Line 6 stores "Asha" without an error, and line 7 prints it.

Lists work the same way. ItemOf unwraps a list. For a tuple, a pattern can name one place, like the first or the last. A breadcrumb trail at the top of a shop page is a good example:

1type FirstOf<List> = List extends [infer First, ...unknown[]] ? First : never;2type LastOf<List> = List extends [...unknown[], infer Last] ? Last : never;3 4type Trail = ["Home", "Shop", "Tea"];5type Start = FirstOf<Trail>;6//   ^?7type Here = LastOf<Trail>;8//   ^?9type Nothing = FirstOf<[]>;10//   ^?

In a tuple pattern, ...unknown[] means "any number of other items, of any type". unknown is the type every value fits. Line 1 puts the blank first and the rest after it. Line 2 puts the rest first and the blank last. Line 4 is the trail. The query on line 6 shows "Home", the first page, and the query on line 8 shows "Tea", the last. Line 9 tries an empty tuple, which has no first item, so the query on line 10 shows never.

The table below collects the patterns so far. Read each row as: this pattern, the types it matches, and what its blank holds.

infer with a constraint

Sometimes the type you find has to go somewhere picky. Here, PageTitle only takes text, and you want to give it the first page of a trail. TypeScript reports an error, on purpose here:

1type PageTitle<Name extends string> = { title: Name; path: string };2 3type FirstPage<Trail> = Trail extends [infer First, ...unknown[]]4  ? PageTitle<First>5  : never;

Line 1 says PageTitle's Name must be a string: Name extends string is a constraint, as in Generic constraints. Lines 3 to 5 find the first item of a trail and pass it to PageTitle. Line 4 gets Type 'First' does not satisfy the constraint 'string'. It means: PageTitle only takes text, and nothing promises that First is text. A trail's first item could be any type.

The fix is a constraint on the blank itself: infer First extends string.

1type PageTitle<Name extends string> = { title: Name; path: string };2 3type FirstPage<Trail> = Trail extends [infer First extends string, ...unknown[]]4  ? PageTitle<First>5  : never;6 7type Home = FirstPage<["Home", "Shop"]>;8//   ^?9type Missing = FirstPage<[404, "Shop"]>;10//   ^?11const home: Home = { title: "Home", path: "/" };12console.log(home.title);

The constraint on line 3 does two jobs:

• In the true branch, First is known to be a string, so line 4 may pass it to PageTitle.
• When the first item isn't text, the pattern doesn't fit, and you get the false branch.

The query on line 8 shows Home is { title: "Home"; path: string }. Line 9 tries a trail that starts with the number 404, and the query on line 10 shows never. Line 11 makes a home page of the Home type, and line 12 prints Home.

The constraint can be any type, like a union. Here it accepts an id that is a string or a number:

1type IdOf<T> = T extends { id: infer Id extends string | number } ? Id : never;2 3type ProductId = IdOf<{ id: number; name: string }>;4//   ^?5type OrderId = IdOf<{ id: "A-7"; total: number }>;6//   ^?7type FlagId = IdOf<{ id: boolean }>;8//   ^?

Line 1's pattern is an object with an id. Objects with more properties fit too, as long as they have an id. Line 3's product has a number id, and the query on line 4 shows number. Line 5's order has the id "A-7", and the query on line 6 shows exactly "A-7", a literal type. Line 7's id is a boolean, which the constraint turns away, so the query on line 8 shows never.

Types from an API helper

Here is how infer helps in a real app. A fetchCart function stands in for a call to the server, and its reply is the only place the cart's shape is written. The rest of the page works its types out from it. Press the buttons to change what fetchCart returns on line 6:

1type ItemOf<List> = List extends (infer Item)[] ? Item : never;2type Unwrap<T> = T extends Promise<infer Value> ? Value : T;3type ReturnOf<Fn> = Fn extends (...args: any[]) => infer Result ? Result : never;4 5async function fetchCart() {6  return { items: [{ name: "Tea", price: 3 }], total: 3 };7}8 9type CartReply = Unwrap<ReturnOf<typeof fetchCart>>;10type CartLine = ItemOf<CartReply["items"]>;11//   ^?12 13function showLine(line: CartLine) {14  return `${line.name}: $${line.price}`;15}16console.log(showLine({ name: "Cake", price: 4 }));

Lines 1 to 3 are the three helpers from this lesson. Lines 5 to 7 are fetchCart. Read line 9 from the inside out: typeof fetchCart is the function's type, ReturnOf gives its promise, and Unwrap opens the promise. On line 10, CartReply["items"] is the type of the reply's items property (the Indexed access types lesson covers this), and ItemOf gives one item. The query on line 11 shows CartLine. Lines 13 to 15 show one line of the cart, and line 16 prints Cake: $4.

With Price as text, CartLine's price becomes a string, and line 16, which passes a number, gets an error. With Add a size, CartLine gets a size, and line 16's cake has none. You changed one line, and TypeScript pointed at the one place that no longer matches. Without infer, you would have written the item type by hand, and it would have quietly gone out of date.

Now sort some types. Each card uses one of these helpers. Every helper gives never when its pattern doesn't match:

1type ItemOf<List> = List extends (infer Item)[] ? Item : never;2type ReturnOf<Fn> = Fn extends (...args: any[]) => infer Result ? Result : never;3type FirstOf<List> = List extends [infer First, ...unknown[]] ? First : never;4type FirstText<List> = List extends [infer First extends string, ...unknown[]] ? First : never;

Common mix-ups

infer only works inside the pattern of a conditional type. Here it is on its own, an error on purpose:

1type Cart = { name: string; price: number }[];2type CartItem = infer Item;

Line 2 gets 'infer' declarations are only permitted in the 'extends' clause of a conditional type. It means infer needs a pattern to line up with a type, and only the part after extends is a pattern. Line 2 has no type to compare with, so there is nothing to work out.

A function with overloads, several call signatures for one function, has a surprise too:

1type ReturnOf<Fn> = Fn extends (...args: any[]) => infer Result ? Result : never;2 3function formatPrice(price: number): string;4function formatPrice(price: string): number;5function formatPrice(price: number | string) {6  return typeof price === "number" ? String(price) : Number(price);7}8 9type Formatted = ReturnOf<typeof formatPrice>;10//   ^?

Line 3 says a number gives back a string, and line 4 says a string gives back a number. Line 5 is the code that runs. The query on line 10 shows number: when a function has several signatures, infer reads the last one, line 4. It can't pick the signature that fits a call, because there is no call here.

• "I can write infer anywhere in a type." No. Only after extends in a conditional type. Anywhere else is error 1338.
• "infer looks at my values while the page runs." No. It works on types, before the code runs. The playgrounds print Asha and Cake: $4 whatever the types say.
• "When the pattern doesn't match, infer gives unknown." No. You get the false branch, exactly as you wrote it: never in ItemOf, T itself in Unwrap.
• "(infer Item)[] matches every kind of list." No. A readonly string[] doesn't fit it. Write readonly (infer Item)[] to match both kinds.
• "infer picks the overload that fits my call." No. It reads the last signature.
• "I have to write ReturnOf myself in real code." No. TypeScript has ReturnType, Parameters, and Awaited built in. Writing your own shows how they work.

infer isn't the only way to reach part of a type. The table below compares it with reading a property type by name, CartReply["items"] from the API helper. Read each row as a question, then each way's answer.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code: the errors update as you type, and a // ^? line under a type name shows what TypeScript found. Try a guess first, then use the hints.

1type ItemOf<List> = List extends (infer Item)[] ? Item : never;2 3type Prices = number[];4type Price = ItemOf<Prices>;

1type ItemOf<List> = List extends (infer Item)[] ? Item : never;2 3type Prices = number[];4type Price = ItemOf<Prices>;5//   ^?

1type Unwrap<T> = T extends Promise<infer Value> ? Value : T;2 3type Theme = Unwrap<string>;

1type Unwrap<T> = T extends Promise<infer Value> ? Value : T;2 3type Theme = Unwrap<string>;4//   ^?

1// Replace never with a pattern that finds the last item.2type LastOf<List> = never;3 4type Here = LastOf<["Home", "Shop", "Tea"]>;

1type LastOf<List> = List extends [...unknown[], infer Last] ? Last : never;2 3type Here = LastOf<["Home", "Shop", "Tea"]>;4//   ^?

1type FirstParam<Fn> = Fn extends (...args: any[]) => any ? unknown : never;2 3function onSearch(event: KeyboardEvent, query: string) {4  console.log(query);5}6 7type SearchEvent = FirstParam<typeof onSearch>;8const pressed: SearchEvent["key"] = "Enter";

1type FirstParam<Fn> = Fn extends (first: infer First, ...rest: any[]) => any ? First : never;2 3function onSearch(event: KeyboardEvent, query: string) {4  console.log(query);5}6 7type SearchEvent = FirstParam<typeof onSearch>;8//   ^?9const pressed: SearchEvent["key"] = "Enter";10console.log(pressed);

1type Setting<Value extends string | number> = { value: Value; label: string };2 3type FirstSetting<List> = List extends [infer First, ...unknown[]] ? Setting<First> : never;4 5type FontSize = FirstSetting<[16, "large"]>;6const fontSize: FontSize = { value: 16, label: "Font size" };

1type Setting<Value extends string | number> = { value: Value; label: string };2 3type FirstSetting<List> = List extends [infer First extends string | number, ...unknown[]] ? Setting<First> : never;4 5type FontSize = FirstSetting<[16, "large"]>;6//   ^?7const fontSize: FontSize = { value: 16, label: "Font size" };8console.log(fontSize.value);

1type Unwrap<T> = T extends Promise<infer Value> ? Value : T;2 3type Reply = Promise<Promise<string>>;4type Name = Unwrap<Reply>;5const name: Name = "Asha";6console.log(name);

1type Unwrap<T> = T extends Promise<infer Value> ? Unwrap<Value> : T;2 3type Reply = Promise<Promise<string>>;4type Name = Unwrap<Reply>;5//   ^?6const name: Name = "Asha";7console.log(name);

Check your understanding

For each question, line the pattern up with the type. Does it fit? If yes, what sits in the blank? If no, what does the false branch say? The quiz code isn't checked on the page, so no error list or type hint gives the answer away.

Key takeaways

• infer Name puts a named blank in the pattern of a conditional type, after extends.
• If the pattern fits, the name holds the type in the blank, and you use it in the true branch.
• If it doesn't fit, you get the false branch, exactly as you wrote it: often never, or the type itself.
• Put the blank where you need it: a list's item, a function's return type or parameters, a promise's value, a tuple's first or last place.
• A true branch that calls its own type again, like UnwrapAll, opens every layer.
• infer First extends string adds a constraint: the blank only accepts that type, so you can use it where that type is needed.

Coming next: Mapped types. They go through every property of a type and change each one: make them all optional, read-only, or a new type.