How TypeScript inference works

Where a type comes from when you don't write one

In Annotations & inference you saw that TypeScript works out a type from a starting value. That is one rule of several. The checker (the part of the compiler that works out types, from Inside the compiler) follows a few fixed rules, and three lines of a cart already use four of them. Point at any name to see its type:

1const cart = [{ name: "Tea", price: 3 }, { name: "Cake", price: 4 }];2//    ^?3const total = cart.reduce((sum, item) => sum + item.price, 0);4//    ^?5//                               ^?6console.log(total);

No type is written anywhere, yet every name has one:

• Line 1 makes a cart of two items. The query on line 2 shows each item's name as string, not "Tea". That is widening: the exact text became the general type.
• The cart is an array of one item type, worked out from both elements. That is the best common type.
• Line 3 adds up the prices with reduce. The query on line 5 shows item is a cart item, though its brackets say nothing about it. It got its type from the place it is written: the callback of cart.reduce. That is contextual typing.
• The query on line 4 shows const total: number. reduce is a generic function (one with a type parameter, a placeholder for a type), and TypeScript filled in that placeholder from the starting value 0. That is inferring a type argument.

Line 6 prints 7. The rules work in two directions, which the picture below shows:

Widening and the best common type go from the value: TypeScript looks at what you wrote and works out its type. Contextual typing goes from the place: TypeScript looks at where you wrote it and passes the type in. Type arguments use both.

The table below lists the four rules. Read each row as: the rule, where it looks, an example, and the type it gives.

Widening: when an exact value becomes a general type

Every value you write starts with its exact type: "dark" is the type "dark", and 16 is the type 16 (Literal types covers these). When TypeScript stores the value somewhere that can change later, it widens the exact type to the general one:

1let theme = "dark";2//  ^?3const fontSize = 16;4//    ^?5const order = { size: "M", quantity: 2 };6//    ^?

Line 1 is a let, which you can give any other text later, so the query on line 2 shows string. Line 3 is a const, which never changes, so it keeps 16. Line 5 is a const too, but its properties can still change (order.size = "L" is allowed), so the query on line 6 shows size: string.

That part you may know. Here is the part that surprises people. Press each button to declare theme a different way on line 3, then watch what copy becomes on line 4:

1type Theme = "dark" | "light";2function setTheme(theme: Theme) { console.log(`Theme: ${theme}`); }3let theme = "dark";4let copy = theme;5//  ^?6setTheme(copy);

With const, theme is exactly "dark", and yet copy is a string. A const with no type written holds a widening exact type: exact while it stays in the const, widened as soon as it is copied into a let, a property, or an array. Writing the type (const with a type) or as const gives an exact type that doesn't widen, so copy stays "dark". The output is Theme: dark every time: widening only changes the types, never what runs.

Values that a function gives back follow a rule of their own:

1function defaultTheme() {2  return "dark";3}4const theme = defaultTheme();5//    ^?6function shippingCost(total: number) {7  if (total >= 50) return 0;8  return 4.99;9}10const cost = shippingCost(30);11//    ^?12console.log(theme, cost);

defaultTheme on lines 1 to 3 always gives back "dark", and the query on line 5 shows string: one exact value given back is widened. shippingCost on lines 6 to 9 gives back 0 or 4.99, and the query on line 11 shows 0 | 4.99: when the returns give back different exact values, TypeScript keeps them as a union (a type that is one of several). Line 12 prints dark 4.99.

The best common type of several values

When one type has to describe several values, like the elements of an array, each value gives a candidate type. TypeScript then picks the best common type: a candidate that all the others fit into. If no candidate covers the rest, it joins them in a union:

1const prices = [3, 4, 5];2//    ^?3const discounts = [5, null, 10];4//    ^?5const tags = ["sale", 3];6//    ^?

On line 1 every candidate is number, so the query on line 2 shows number[]. On line 3 the candidates are number and null, and the query on line 4 shows (number | null)[]. On line 5 they are string and number, so (string | number)[].

Objects with different properties are joined too, with a small extra step:

1const cart = [{ name: "Tea", price: 3 }, { name: "Gift card" }];2//    ^?3const secondPrice = cart[1].price;4//    ^?5console.log(secondPrice);

Line 1 has a tea with a price and a gift card without one. The query on line 2 shows a union of the two shapes, and the gift card's shape has gained price?: undefined (an optional price that is always undefined). TypeScript adds it so that every item has a price to read. That is why line 3 is allowed, and the query on line 4 shows number | undefined. Line 5 prints undefined.

The best common type is always one of the candidates, or their union. TypeScript never invents a type you didn't write:

1class Control { label = "Button"; }2class SaveButton extends Control { save() {} }3class CancelButton extends Control { cancel() {} }4 5const toolbar = [new SaveButton(), new CancelButton()];6//    ^?7const footer = [new Control(), new SaveButton()];8//    ^?9const typed: Control[] = [new SaveButton(), new CancelButton()];

Lines 1 to 3 make a Control class and two kinds of button that extend it (Classes covers extends). Line 5 puts a save button and a cancel button in an array, and the query on line 6 shows (SaveButton | CancelButton)[], not Control[]: Control isn't one of the candidates. On line 7 it is, and every SaveButton fits into a Control, so the query on line 8 shows Control[]. When you want the parent type, write it, as line 9 does.

Contextual typing: the place decides

Sometimes the type flows the other way. When you write a value in a place that already has a type, TypeScript gives the value that type. This is called contextual typing, and its most common use is a callback's parameters. Press each button to move an event handler (Introduction to events covers addEventListener):

1const button = document.createElement("button");2button.addEventListener("click", (event) => {3  console.log(event.button);4});

With Inline, click, event is a PointerEvent: TypeScript read the event name "click", looked up what a click handler receives in the browser's types, and gave event that type. Inline, keydown makes it a KeyboardEvent, which has no button, and line 3 gets an error. A separate const loses the context: on line 2 nothing says what the function is for, so TypeScript reports Parameter 'event' implicitly has an 'any' type. Inference never looks ahead to line 5. A separate const, typed fixes it by writing the type.

Any place with a type gives context, not just function calls. Here, a typed object does:

1type Settings = {2  theme: "dark" | "light";3  onChange: (value: string) => void;4};5 6const settings: Settings = {7  theme: "dark",8  onChange: (value) => console.log(`Saved ${value}`),9  //         ^?10};11settings.onChange("dark");

Lines 1 to 4 describe Settings: a theme and an onChange function that receives a string. Line 6 says settings is a Settings, so every property inside gets context. On line 8, value has no type written, and the query on line 9 shows string. The same context checks line 7: "dark" is compared with "dark" | "light" and keeps its exact type, so it doesn't widen. Line 11 prints Saved dark.

Inferring type arguments

A generic function has a type parameter, like T: a placeholder that each call fills in with a type argument (Generic functions introduces them). You rarely write the type argument, because TypeScript infers it from the arguments:

1function firstItem<T>(items: T[]) {2  return items[0];3}4const firstPrice = firstItem([3, 4]);5//    ^?6const firstName = firstItem(["Tea", "Cake"]);7//    ^?8console.log(firstPrice, firstName);

Line 1 says firstItem takes a list of T. Line 4 passes [3, 4], a number[], so T is number, and the query on line 5 shows const firstPrice: number. Line 6 passes text, so T is string. Line 8 prints 3 Tea.

Each argument that mentions T gives a candidate. When two arguments disagree, TypeScript doesn't join them the way it joins array elements. This is an error on purpose:

1function listOf<T>(first: T, second: T): T[] {2  return [first, second];3}4const sizes = listOf("S", "M");5//    ^?6const mixed = listOf(3, "4");

listOf takes two values of the same type T. On line 4 both are text, so T is string and the query on line 5 shows string[]. On line 6, 3 gives the candidate number and "4" gives string. Neither covers the other, so TypeScript goes with the first, number, and reports the argument that doesn't fit: Argument of type 'string' is not assignable to parameter of type 'number'. Often that is the bug you want caught. When mixing is what you mean, write the type argument yourself, and nothing is inferred:

1function listOf<T>(first: T, second: T): T[] {2  return [first, second];3}4const mixed = listOf<number | string>(3, "4");5//    ^?6console.log(mixed);

Line 4 says T is number | string, so both arguments fit, and the query on line 5 shows (string | number)[]. Line 6 prints the list with 3 and "4".

Sometimes an argument shouldn't help decide T at all. A size picker takes a list of sizes and a starting size, and the starting size should be one of the list, not a new size. TypeScript 5.4 added NoInfer for this. Press each button:

1function pickSize<S extends string>(sizes: S[], initial: S) {2  return initial;3}4const size = pickSize(["S", "M", "L"], "XL");5//    ^?6console.log(size);

Without NoInfer, the starting size "XL" joins the candidates, so S becomes four sizes and the mistake gets through. With NoInfer, NoInfer<S> on line 1 tells TypeScript to use S for that parameter but not to learn S from it. Only the list decides, so line 4 gets an error. With a real size, "M", the error is gone. Every version prints the size it was given: types never change what runs.

When inference gives up

Inference needs something to learn from. When there is too little, you get a type that is either too empty or too loose:

1const filters = {};2//    ^?3filters.size = "M";

Line 1 makes an empty object, and the query on line 2 shows its type: {}, an object with no known properties. Line 3 adds a size, and TypeScript reports Property 'size' does not exist on type '{}'. The type was decided on line 1 and doesn't grow. Write the type you want: const filters: { size?: string } = {};.

1const reply = JSON.parse('{ "price": 3 }');2//    ^?3console.log(reply.prise);4 5function emptyList<T>(): T[] {6  return [];7}8const list = emptyList();9//    ^?

Line 1 reads a reply with JSON.parse. Its declaration says it gives back any, so the query on line 2 shows any: a type that turns checking off (any, unknown & never covers it). Line 3 misspells price as prise, and nothing complains; it prints undefined. Lines 5 to 7 declare a generic emptyList, and line 8 calls it with no arguments, so there is nothing to learn T from. TypeScript falls back to unknown, a type that allows nothing until you check it, and the query on line 9 shows unknown[].

Two cases look like giving up but aren't: a let with no value, and an empty array.

1let total;2total = 3;3const doubled = total * 2;4//    ^?5const items = [];6items.push("Tea");7console.log(items, doubled);8//          ^?

Line 1 declares total with no value and no type. Instead of giving up, TypeScript follows what is stored in it: after line 2, total is a number, so the query on line 4 shows doubled is a number. Line 5's empty array works the same way: after push("Tea") on line 6, the query on line 8 shows items as string[]. Line 7 prints the list with "Tea", then 6. This is the checker following the code line by line, which Control flow analysis opens up.

The table below sums up these cases. Read each row as: what you write, what TypeScript infers, and what to write instead.

A settings object that lost its theme

A settings panel keeps its defaults in an object and passes them to a function. No types are written on the object, and the call fails. This is an error on purpose:

1type Theme = "dark" | "light";2type Settings = { theme: Theme; fontSize: number };3 4const defaults = { theme: "dark", fontSize: 16 };5//    ^?6 7function applySettings(settings: Settings) {8  console.log(`${settings.theme}, ${settings.fontSize}px`);9}10applySettings(defaults);

Lines 1 and 2 describe a Settings object whose theme is "dark" or "light". Line 4 makes the defaults, and the query on line 5 shows the cause: theme: string. The property widened, because nothing on line 4 says it is a theme. Line 10 gets Argument of type '{ theme: string; fontSize: number; }' is not assignable to parameter of type 'Settings': any string might not be a theme. The code still prints dark, 16px.

The fix is to give line 4 a context. satisfies does it while keeping the object's own type:

1type Theme = "dark" | "light";2type Settings = { theme: Theme; fontSize: number };3 4const defaults = { theme: "dark", fontSize: 16 } satisfies Settings;5//    ^?6 7function applySettings(settings: Settings) {8  console.log(`${settings.theme}, ${settings.fontSize}px`);9}10applySettings(defaults);

Line 4 ends with satisfies Settings (as const & satisfies covers it). Settings is now the context for the object, so "dark" keeps its exact type: the query on line 5 shows theme: "dark". Line 10 is fine. Writing const defaults: Settings would work too, and as const would keep every value exact.

Common mix-ups

• "Inference is TypeScript guessing." No. It follows fixed rules: the same code always gets the same types, and you can predict them.
• "A const always keeps its exact value." No. Its properties widen, its array elements widen, and a copy in a let widens. Only a written type or as const stops that.
• "TypeScript looks at how I use a name later to pick its type." No. The type comes from the declaration and its place. A separate handler doesn't learn from the line that uses it. Only a let with no value and an empty array follow what comes next.
• "Different values always make a union." No. Array elements and return statements do, but two arguments for the same T don't: the second one gets an error.
• "The best common type finds the shared parent class." No. It picks one of the candidates or joins them. [new SaveButton(), new CancelButton()] isn't a Control[] unless you say so.
• "NoInfer turns off checking." No. The argument is still checked; it just doesn't help decide the type.

Practice exercises

Guess first, then check: point at a name, or press Edit & run and add a // ^? line under it.

1const order = { size: "M", quantity: 2 };2const size = order.size;

1const order = { size: "M", quantity: 2 };2const size = order.size;3//    ^?

1const ratings = [5, 4, null];

1const ratings = [5, 4, null];2//    ^?

1const onKey = (event) => {2  console.log(event.key);3};4window.addEventListener("keydown", onKey);

1window.addEventListener("keydown", (event) => {2  console.log(event.key);3  //          ^?4});

1type Theme = "dark" | "light";2function setTheme(theme: Theme) { console.log(theme); }3 4const saved = "light";5let current = saved;6setTheme(current);

1type Theme = "dark" | "light";2function setTheme(theme: Theme) { console.log(theme); }3 4const saved = "light";5let current: Theme = saved;6setTheme(current);

1function pair<T>(first: T, second: T) {2  return [first, second];3}4const prices = pair(3, "4");

1function pair<T>(first: T, second: T) {2  return [first, second];3}4const prices = pair<number | string>(3, "4");5console.log(prices);

1function pickColor<C extends string>(colors: C[], fallback: C) {2  return fallback;3}4const color = pickColor(["red", "green"], "blue");5console.log(color);

1function pickColor<C extends string>(colors: C[], fallback: NoInfer<C>) {2  return fallback;3}4const color = pickColor(["red", "green"], "green");5//    ^?6console.log(color);

Check your understanding

For each question, ask where the type comes from: the value or the place. The quiz shows its code without the checker, so the types don't give the answers away.

Key takeaways

• Inference follows fixed rules, in two directions: from the value, and from the place.
• Exact values widen where they can change: a let, a property, an array element, a copy of a const. A written type or as const stops it.
• Several values get their best common type: a candidate that covers the rest, or the union of them all.
• A value written where a type is expected gets that type: callbacks, handlers, and typed objects.
• Type arguments come from the arguments. Disagreeing arguments get an error; NoInfer keeps an argument from deciding.
• With nothing to learn from, you get {}, any, or unknown. Write the type there.

Coming next: Control flow analysis. It shows how the checker follows your code line by line, which is how let total; became a number.