Type annotations & inference

Two ways a value gets its type

Every name in TypeScript has a type. A shopping cart needs a count of items and a total, and both must be numbers. There are two ways a name gets its type: you write it, or TypeScript works it out from the value. Here are both, side by side:

1let itemCount: number = 3;2//  ^?3let cartTotal = 42;4//  ^?5itemCount = 4;6cartTotal = 58;7console.log(itemCount, cartTotal);

Line 1 says itemCount is a number with : number after the name. Writing a type like that is called a type annotation. Line 3 makes cartTotal with no type written at all.

Lines 2 and 4 are queries. A comment like // ^? asks "what type is the name my ^ points at?", and the page writes TypeScript's answer after it. Both answers are the same: let itemCount: number and let cartTotal: number. For cartTotal, TypeScript read the starting value, 42, and worked out number by itself. That is called type inference: "infer" means to work something out from what you can see. Lines 5 and 6 store new numbers, and line 7 prints 4 58.

An inferred type isn't a weaker kind of type. TypeScript checks both names in exactly the same way:

1let itemCount: number = 3;2let cartTotal = 42;3 4itemCount = "four";5cartTotal = "free";

Line 4 tries to put the text "four" in itemCount, and line 5 tries to put "free" in cartTotal. TypeScript marks both lines, on purpose here, with the same message: Type 'string' is not assignable to type 'number'. It means "you're putting text where a number has to go". Line 5 gets the error even though nobody wrote number for cartTotal.

Writing an annotation

An annotation always goes after the thing it describes, behind a colon. Some languages put the type first, like int count; TypeScript never does. Here are the places you'll write one, in a small user profile:

1let userName: string = "Asha";2let age: number;3age = 31;4 5function greet(name: string): string {6  return `Hi, ${name}`;7}8console.log(greet(userName), age);

Line by line:

• Line 1 annotates a variable with a starting value: userName is a string, and "Asha" fits.
• Line 2 annotates a variable with no starting value. age has a type now, and line 3 gives it a value that fits it.
• Line 5 has two annotations. name: string inside the brackets is a parameter annotation: the function must be given text. : string after the brackets is a return type annotation: the function promises to give back text (Functions covers parameters and return).
• Line 6 returns a template literal, which is a string, so the promise holds. Line 8 prints Hi, Asha 31.

An annotation with no starting value gives a name a type, not a value. TypeScript keeps track of whether you stored one before you read it:

1let age: number;2console.log(age);3age = 31;

Line 1 says age is a number. Line 2 reads it, but nothing has been stored yet. TypeScript marks line 2 on purpose: Variable 'age' is used before being assigned. "Assigned" means "given a value". When it runs, line 2 prints undefined, which isn't a number at all. Line 3 comes too late.

The annotation decides the type, and the value has to fit it. Try it: type a different type after the colon on line 1, and watch the list under the code as you type.

1let quantity: number = 3;2quantity = quantity + 1;3console.log(quantity);

With string, the number 3 no longer fits. With boolean, line 2's sum breaks too, because TypeScript now believes quantity is true or false. A misspelled type, like numbr, gets Cannot find name 'numbr', and the message suggests number. The capital Number is the wrapper object type from the Primitive types lesson, which can't be used in a sum. An empty box gets Type expected, because a colon must be followed by a type.

How inference works

Most of the time you don't write a type, and TypeScript infers it. It doesn't guess. It follows fixed rules, and the first one is simple: a name gets the type of the value it starts with. The type of a calculation follows from what goes into it:

1const price = 4;2const quantity = 3;3const total = price * quantity;4//    ^?5const label = "Total: " + total;6//    ^?7const isFree = total === 0;8//    ^?9console.log(label, isFree);

Lines 1 and 2 store a price and a quantity. Line 3 multiplies them, and the query on line 4 shows const total: number: a number times a number is a number. Line 5 joins text and a number, which makes text, so the query on line 6 shows string. Line 7 compares two numbers with ===, which gives true or false, so the query on line 8 shows boolean. Line 9 prints Total: 12 false. You wrote no types, and every name has one.

The starting value decides the type, and later values must fit it. Press each button to give discount a different starting value, and watch the query on line 2:

1let discount = 5;2//  ^?3discount = 10;4console.log(discount);

5 and 2.5 both give number, so line 3's 10 fits. "5" gives string, true gives boolean, and 5n gives bigint, and each time line 3 gets an error. Nobody wrote a type, but the one TypeScript inferred is enforced. (A const keeps its exact value as its type, like const minOrder: 50, as the Primitive types lesson showed. This playground uses let, so the type is the wider number.)

Inference also works the other way round. Sometimes TypeScript knows a value's type from where you put it. This is called contextual typing: the context, meaning the place the code sits, gives the type. The most common case is a callback, a function you pass to another function, like the listener you pass to addEventListener (Events covers listeners):

1const buyButton = document.createElement("button");2buyButton.addEventListener("click", (event) => {3//                                   ^?4  console.log(event.clientX);5});

Line 1 makes a Buy button. Line 2 adds a click listener, an arrow function that takes event. Nobody wrote a type for event, but the query on line 3 shows (parameter) event: PointerEvent. TypeScript's description of the browser says a "click" listener is called with a PointerEvent, the object that describes a click or tap. That's why line 4 may read event.clientX, the distance of the click from the left edge of the visible page.

Hover to see a type

Inferred types aren't hidden. In your editor, point at any name and a small box shows its type. The ^? lines in these lessons show the same answer on the page:

1function lineTotal(price: number, quantity: number) {2//       ^?3  return price * quantity;4}5const teaTotal = lineTotal(3, 2);6//    ^?7const label = `Tea: $${teaTotal}`;8//    ^?9console.log(label);

The query on line 2 points at lineTotal and shows the whole function: function lineTotal(price: number, quantity: number): number. You wrote the two parameter types. The : number at the end is the return type, and TypeScript inferred it from line 3, because a number times a number is a number. The query on line 6 shows const teaTotal: number, and the one on line 8 shows const label: string. Line 9 prints Tea: $6.

Three ways to see a type, depending on where you are:

• In your editor: point at a name with the mouse. In VS Code you can also put the cursor on it and press Ctrl+K, then Ctrl+I (Cmd+K, Cmd+I on a Mac).
• In these lessons: point at a name in a checked example, or read the answer after a ^? line.
• In Edit & run: move the cursor onto a name, and its type shows under the editor. You can also add your own // ^? line, with the ^ under the name you want to ask about.

Press Edit & run on the example above and try it: add a line // ^? under line 3 with the ^ under price, and the answer is (parameter) price: number. Checking a type this way is the quickest way to learn inference: guess first, then hover.

When annotations help

Since TypeScript infers so much, when should you write a type? Mostly where TypeScript has nothing to read the type from. The first such place is a function's parameters:

1function addTax(price) {2  return price * 1.2;3}4console.log(addTax(10));

Line 1 declares addTax with a price parameter and no type. TypeScript marks it on purpose: Parameter 'price' implicitly has an 'any' type. In plain words: "I can't tell what price is, so I'd have to give up checking it". any is the type that turns checking off; the any, unknown & never lesson covers it. TypeScript doesn't look at the call on line 4 to work out the parameter's type: the function could be called from anywhere. The code still runs and prints 12.

This error comes from the noImplicitAny option, part of strict, which every example in these lessons uses. The fix is one annotation:

1function addTax(price: number) {2  return price * 1.2;3}4console.log(addTax(10));

Line 1 now says price: number. The error is gone, line 2 is checked as number math, and line 4 still prints 12. You didn't write a return type: TypeScript infers number from line 2.

A return type is never required, because TypeScript infers it from the return lines. But writing one moves errors to a better place. This shipping cost has a mistake: line 3 returns the text "4.99" instead of a number. Switch line 1 between no return type and : number, and watch where the error lands:

1function shippingCost(total: number) {2  if (total >= 50) return 0;3  return "4.99";4}5const cost = shippingCost(30);6//    ^?7const toPay: number = 30 + cost;8console.log(toPay);

With no return type, TypeScript believes the function gives back what it returns, text included, and the error appears on line 7, far from the mistake. With : number, the function makes a promise, and TypeScript checks every return against it, so line 3 itself gets the error. In a big project, the line that uses a value can be in a different file from the line that made it.

The last common place is a value from outside your code. JSON.parse reads text, so TypeScript can't know what it gives back (JSON covers it). Here are saved settings, read twice:

1type Settings = { theme: string; fontSize: number };2 3const saved = '{ "theme": "dark", "fontSize": 18 }';4const parsed = JSON.parse(saved);5//    ^?6const settings: Settings = JSON.parse(saved);7//    ^?8console.log(settings.fontSize + 2);

Line 1 names the shape of the settings with a type alias: type Settings = … gives a name to an object type (Object types covers them). Line 3 is the saved text. Line 4 parses it with no annotation, and the query on line 5 shows const parsed: any: TypeScript has nothing to infer from, so it gives up. Line 6 parses it again with : Settings, and the query on line 7 shows const settings: Settings. From here on, settings.fontSize is a number and settings.color would be an error. Line 8 prints 20.

The annotation on line 6 is a promise you make, not a check: if the saved text had a different shape, TypeScript couldn't notice, because the text only exists while the page runs. The table below sums up where to write a type. Read each row as: this kind of name, should you annotate it, and why.

A quantity box, typed at the edges

Put it together on a checkout page. The shopper types a quantity into a box, and the page reads it. A good habit is to annotate the edges of your code, where values come in and go out, like a function's parameters and return type, and let inference fill in the middle:

1const quantityInput = document.createElement("input");2//    ^?3quantityInput.value = "2";4 5function readQuantity(input: HTMLInputElement): number {6  return Number(input.value);7}8 9const quantity = readQuantity(quantityInput);10//    ^?11console.log(quantity + 1);

Line 1 makes an <input> box, and the query on line 2 shows TypeScript inferred HTMLInputElement, the type of an input element, from the "input" you passed in. Line 3 puts "2" in it, as if the shopper typed 2 (Form elements covers .value). Line 5 is the edge: readQuantity takes an HTMLInputElement and promises a number. Line 6 keeps the promise by turning the text into a number. Line 9 has no annotation, and the query on line 10 shows const quantity: number, worked out from the return type. Line 11 prints 3.

There are only two annotations in the whole example, both on line 5. Every other type was inferred, and every one is checked.

Common mix-ups

• "An inferred type is only a guess, so it isn't checked." No. Inference follows fixed rules, and the result is checked exactly like a type you wrote. let total = 0; total = "free"; is an error.
• "Annotating every variable makes code safer." No. On a variable with a starting value, the annotation usually says what TypeScript already knows. It adds words to read and change, not checks.
• "TypeScript works out a parameter's type from how I call the function." No. It never looks at the calls. A parameter needs an annotation, unless the function is passed somewhere that gives it one, like a listener.
• "An annotation turns the value into that type." No. const price: number = "4" doesn't make a number; it gets an error. Annotations are removed before the code runs, so they can't change a value.
• "Annotating a JSON.parse result checks the data." No. TypeScript trusts your annotation. It can't see data that only arrives while the page runs.
• "The type goes first, like string city." No. In TypeScript the type always comes after the name, behind a colon: city: string.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code to try your answer: the errors update as you type, the type under the cursor shows below the editor, and the console shows what it prints. Guess first, then use the hints.

1const total = 3 * 4;2console.log(total);

1const total = 3 * 4;2//    ^?3console.log(total);

let cartTotal = 42;
cartTotal = 50;
cartTotal = "fifty";
console.log(cartTotal);

1let cartTotal = 42;2cartTotal = 50;3cartTotal = 55;4console.log(cartTotal);

1function addTax(price) {2  return price * 1.2;3}4console.log(addTax(10));

1function addTax(price: number) {2  return price * 1.2;3}4console.log(addTax(10));

1function shippingCost(total: number) {2  if (total >= 50) return 0;3  return "4.99";4}5console.log(shippingCost(30) + 1);

1function shippingCost(total: number): number {2  if (total >= 50) return 0;3  return 4.99;4}5console.log(shippingCost(30) + 1);

1const searchBox = document.createElement("input");2searchBox.addEventListener("keydown", (event) => {3  console.log(event.key);4});

1const searchBox = document.createElement("input");2searchBox.addEventListener("keydown", (event) => {3//                                     ^?4  console.log(event.key);5});

1const taxRate: number = 0.25;2let itemCount: number = 3;3function lineTotal(price: number, quantity: number): number {4  return price * quantity;5}6const total: number = lineTotal(4, itemCount);7console.log(total * (1 + taxRate));

1const taxRate = 0.25;2let itemCount = 3;3function lineTotal(price: number, quantity: number) {4  return price * quantity;5}6const total = lineTotal(4, itemCount);7console.log(total * (1 + taxRate));

Check your understanding

For each question, ask: did someone write the type, and if not, what could TypeScript read it from? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• An annotation is a type you write after a name, behind a colon: let itemCount: number, function greet(name: string): string.
• Inference is TypeScript working the type out from the value. An inferred type is checked exactly like one you write.
• A variable gets the type of its starting value. A calculation gets the type of its result. A function passed somewhere, like a listener, gets its parameter types from that place.
• Point at a name in your editor, or use a ^? query, to see any type.
• Annotate parameters, values TypeScript can't see into, like JSON.parse results, and return types when you want errors at the mistake. Let inference do the rest.

Coming next: Arrays & tuples. It shows how to type a list of values, and a list with a fixed shape.