Your first typed program

A cart that prints $NaN

Here is a small shopping cart in plain JavaScript, saved as cart.js. Two teas at 3 and one cake at 4 should cost 10. Run it and see what it prints:

function lineTotal(price, quantity) {
  return price * quantity;
}

function cartTotal(items) {
  let total = 0;
  for (const item of items) {
    total += lineTotal(item.price, item.quantity);
  }
  return total;
}

const cart = [
  { name: "Tea", price: 3, quantity: 2 },
  { name: "Cake", price: 4, qty: 1 },
];
console.log(`Total: $${cartTotal(cart)}`);

Lines 1 to 3 declare lineTotal, which multiplies a price by a quantity. Lines 5 to 11 declare cartTotal, which adds up the line total of every item. Lines 13 to 16 make a cart of tea and cake, and line 17 prints the total. It prints Total: $NaN. NaN means "not a number" (the Numbers lesson explains where it comes from).

The bug is on line 15: the cake says qty, but line 8 reads item.quantity. The cake has no quantity, so line 8 gets undefined, and 4 * undefined is NaN. JavaScript doesn't warn you. Here is the same cart turned into TypeScript, with a few types added:

1type CartItem = { name: string; price: number; quantity: number };2 3function lineTotal(price: number, quantity: number) {4  return price * quantity;5}6 7function cartTotal(items: CartItem[]) {8  let total = 0;9  for (const item of items) {10    total += lineTotal(item.price, item.quantity);11  }12  return total;13}14 15const cart: CartItem[] = [16  { name: "Tea", price: 3, quantity: 2 },17  { name: "Cake", price: 4, qty: 1 },18];19console.log(`Total: $${cartTotal(cart)}`);

Line 1 is new. It's a type alias: it gives the name CartItem to the shape every item must have, a name that is text and a price and quantity that are numbers. Lines 3, 7, and 15 use types: price: number and quantity: number, items: CartItem[] (a list of cart items), and cart: CartItem[]. The rest is the JavaScript you just read.

TypeScript marks line 17, on purpose: it's the bug. Object literal may only specify known properties, and 'qty' does not exist in type 'CartItem' means "this object has a property, qty, that a CartItem doesn't have". An object literal is an object written out in curly braces, like the cake. The code still prints Total: $NaN if you run it, but you found the bug before anyone did.

This lesson builds that TypeScript version one step at a time. You'll write types, read what the compiler says about them, and fix what it finds, without hiding anything.

Annotating a variable

A type annotation is a colon and a type, written after a name. Read let itemCount: number = 2 as "itemCount is a number, and it starts as 2". The three types you'll use most are number, string for text, and boolean for true or false.

1let itemCount: number = 2;2//  ^?3let total = 0;4//  ^?5console.log(itemCount, total);

Line 1 annotates itemCount as a number. The query on line 2 shows let itemCount: number. Line 3 has no annotation, yet the query on line 4 shows let total: number: TypeScript worked it out from the 0. Line 5 prints 2 0. You don't have to annotate every variable. The Type annotations & inference lesson, two lessons on, shows when you can leave it out. When you do write one, it's a promise that TypeScript holds every later line to:

1let total: number = 0;2total = total + 3;3total = "10";4console.log(total);

Line 1 promises that total is a number. Line 2 adds 3, which keeps that promise. Line 3 stores the text "10", and TypeScript marks it on purpose: Type 'string' is not assignable to type 'number', meaning "you're putting text where a number has to go". Line 4 would print 10, the text. Now try annotations yourself: type a different type on line 1.

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

With number there are no errors. string and boolean each break the promise on line 1, and boolean breaks line 2 as well. A typo like nmber gets a suggestion, and an empty annotation gets Type expected. Notice that line 3 prints 3 every time the code can run: an annotation never changes a value.

Annotations matter most on parameters, the names a function receives its values in (see Parameters). TypeScript can work out a variable's type from its starting value, but a parameter has no value until someone calls the function:

1function lineTotal(price: number, quantity: number) {2  return price * quantity;3}4 5console.log(lineTotal(3, 2));

Line 1 says lineTotal takes a price and a quantity, both numbers. Line 2 multiplies them. Line 5 calls it with 3 and 2 and prints 6. Every call is now checked against line 1, and the next section shows what that looks like.

Reading an error message

Here is lineTotal again, called with a price that came from a form:

1function lineTotal(price: number, quantity: number) {2  return price * quantity;3}4 5const priceText = "4"; // read from a form, so it's text6console.log(lineTotal(priceText, 2));

Lines 1 to 3 are the same function. Line 5 stores "4", which is text, because a form gives you text. Line 6 passes it to lineTotal, and TypeScript marks line 6 on purpose. Saved as src/cart.ts and checked with npx tsc --noEmit, this is what the terminal shows:

src/cart.ts:6:23 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

6 console.log(lineTotal(priceText, 2));
                        ~~~~~~~~~


Found 1 error in src/cart.ts:6

Every error has the same parts. Read them in this order:

1. Where: src/cart.ts:6:23 is the file, line 6, and column 23. A column counts characters from the start of the line, so 23 is where priceText starts.
2. Its number: TS2345. Every kind of error has one. Search for it when a message is new to you.
3. What's wrong: the message itself, explained below.
4. The spot: line 6 again, with ~~~~~~~~~ under the exact part the message is about. Your editor draws the same thing as a red squiggle.
5. The count: Found 1 error, and where it is.

Now the message: Argument of type 'string' is not assignable to parameter of type 'number'. Take it a few words at a time:

• An argument is a value you pass in a call: priceText.
• A parameter is the name that receives it: price, on line 1.
• "Not assignable to" means "not allowed in".

So: "you passed text to a parameter that takes a number". Messages like this give the type you have first and the type you need second. Pick a different mistake below and read each message the same way.

1function lineTotal(price: number, quantity: number) {2  return price * quantity;3}4 5const total = lineTotal("4", 2);6console.log(total);

src/cart.ts:5:25 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

5 const total = lineTotal("4", 2);
                          ~~~

Some messages run over several lines, with an indented part. In A missing argument, the indented part points back at line 1 and names the parameter you forgot. In A misspelled name, it shows where the right name was declared. The first line always says what went wrong; the rest adds detail. A longer message works the same way:

1type CartItem = { name: string; price: number; quantity: number };2 3const scone = { name: "Scone", price: "2", quantity: 1 };4const cart: CartItem[] = [scone];

Line 1 describes a cart item. Line 3 makes a scone whose price is the text "2". Line 4 puts it in a cart of CartItems, and TypeScript marks line 4 on purpose with this message:

Type '{ name: string; price: string; quantity: number; }' is not assignable to type 'CartItem'.
  Types of property 'price' are incompatible.
    Type 'string' is not assignable to type 'number'.

Read it from the top. Line 1 says the whole scone doesn't fit a CartItem. Each indented line goes one step closer: line 2 says the problem is the price property, and line 3 says why: text where a number goes. The last line is usually the one to fix. Here, write price: 2 without quotes.

The table below collects the messages from this lesson. Read each row as: the message, what it means, and the usual fix.

Fixing an error, or hiding it

There are two ways to make an error go away. You can fix it: change the code so the types are right. Or you can hide it, also called silencing: tell TypeScript to stop reporting it. Both empty the error list. Only one changes what the code does. Try each on the same mistake:

1function addToTotal(total: number, price: number) {2  return total + price;3}4 5const cakePrice = "4"; // typed into a form, so it's text6console.log(addToTotal(3, cakePrice));

Leave it shows the problem: 3 + "4" joins text and prints 34. Fix converts the text with Number("4"), and the code prints 7. The two Hide buttons add a comment on line 6, just above the call (which moves down to line 7). The error vanishes, but the code still prints 34. The last button shows why @ts-expect-error is the better of the two comments: once the line is fixed, it reports Unused '@ts-expect-error' directive, so a hiding comment doesn't stay after its reason is gone.

// @ts-ignore tells TypeScript to ignore every error on the next line, now and forever. // @ts-expect-error says "the next line has an error, and I know". Hiding is right only when you're sure the code is correct and TypeScript can't see it, which is rare in your own code. When you do, use @ts-expect-error and write why on the same line. Two more ways to hide errors come later: the type any, in any, unknown & never, and turning strict off, which you saw in Setting up a project.

The table below compares the four ways. Read each row as: what you do, whether the bug is gone, and what TypeScript says afterwards.

From cart.js to cart.ts

Now put it together on the cart from the start of the lesson. Turning a JavaScript file into TypeScript takes four small steps, and after each one you read the errors again. Step through them:

1function lineTotal(price, quantity) {2  return price * quantity;3}4 5function cartTotal(items) {6  let total = 0;7  for (const item of items) {8    total += lineTotal(item.price, item.quantity);9  }10  return total;11}12 13const cart = [14  { name: "Tea", price: 3, quantity: 2 },15  { name: "Cake", price: 4, qty: 1 },16];17console.log(`Total: $${cartTotal(cart)}`);

Step 1 only renames the file. Almost all JavaScript is already TypeScript, so the code is unchanged, and the errors are about what TypeScript can't know yet: three parameters with no type. Step 2 types price and quantity. Step 3 describes a cart item with type CartItem, and that's when the real bug shows up, on line 17. Step 4 fixes it, and the total is right.

A few habits make this easier on bigger files:

• Start with function parameters. They're where TypeScript knows least, and every call gets checked once they're typed.
• Treat the errors as a to-do list, top to bottom. Read each message before you change anything.
• Expect real bugs. Step 3's error is the reason the cart printed $NaN.
• Not ready to rename? A // @ts-check comment at the top of a .js file asks your editor to check it as it is (the Types for JavaScript lesson covers this).

A price label on a product form

On a shop's admin page, the owner types a new price into a box, and the page shows a label like $4.50. Here is the JavaScript:

const priceInput = document.createElement("input");
priceInput.value = "4.5";

function priceLabel(price) {
  return `$${price.toFixed(2)}`;
}

console.log(priceLabel(priceInput.value));

Line 1 makes the price box, and line 2 puts "4.5" in it, as if the owner typed it (Form elements covers .value). Lines 4 to 6 build the label: toFixed(2) writes a number with two decimals. Line 8 passes the box's value. It crashes: TypeError: price.toFixed is not a function, because .value is always text, and text has no toFixed. Add one annotation, on line 4:

1const priceInput = document.createElement("input");2priceInput.value = "4.5";3 4function priceLabel(price: number) {5  return `$${price.toFixed(2)}`;6}7 8console.log(priceLabel(priceInput.value));

price: number on line 4 is the only change, and TypeScript marks line 8 on purpose: Argument of type 'string' is not assignable to parameter of type 'number'. The crash is now an error you see while you type. Fix it where the text comes in:

1const priceInput = document.createElement("input");2priceInput.value = "4.5";3 4function priceLabel(price: number) {5  return `$${price.toFixed(2)}`;6}7 8console.log(priceLabel(Number(priceInput.value)));

Line 8 now passes Number(priceInput.value), the number 4.5. No errors, and it prints $4.50. Each change you can make to an error either fixes the bug or only hides the message. Sort these:

Common mix-ups

• "An annotation converts the value." No. let total: number = "10" is an error, not the number 10. Number("10") converts.
• "@ts-ignore fixes the error." No. It hides the message. The fix-or-hide playground still printed 34.
• "I have to understand the whole long message." No. The first line says what's wrong, and the last indented line usually says which part to fix.
• "Renaming .js to .ts changes what my code does." No. The code runs the same. The errors that appear are a to-do list, and some of them are real bugs.
• "The error number tells me the line." No. In src/cart.ts:6:23 - error TS2345, 6 is the line and 23 the column. 2345 is the kind of error.
• "Turning strict off is a quick way to finish converting." No. It hides a whole group of checks in every file, like the ones that asked for parameter types in step 1 of the conversion.

Practice exercises

Press Edit & run on any starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

src/checkout.ts:7:15 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

line 7, column 15

let itemCount: number = 0;
itemCount = itemCount + 2;
itemCount = "3";
console.log(itemCount);

1let itemCount: number = 0;2itemCount = itemCount + 2;3itemCount = 3; // line 3 had the error: "3" is text4console.log(itemCount);

1function shippingCost(weight: number) {2  return weight + 4;3}4 5const weightText = "5"; // from a form6console.log(shippingCost(weightText));

1function shippingCost(weight: number) {2  return weight + 4;3}4 5const weightText = "5"; // from a form6console.log(shippingCost(Number(weightText)));

type Profile = { name: string; age: number; newsletter: boolean };

const asha = { name: "Asha", age: 30, newsletter: "yes" };
const profile: Profile = asha;

1type Profile = { name: string; age: number; newsletter: boolean };2 3const asha = { name: "Asha", age: 30, newsletter: true };4const profile: Profile = asha;

1function addTip(bill: number, tip: number) {2  return bill + tip;3}4 5const tipText = "2"; // from a form6// @ts-ignore7console.log(addTip(10, tipText));

1function addTip(bill: number, tip: number) {2  return bill + tip;3}4 5const tipText = "2"; // from a form6console.log(addTip(10, Number(tipText)));

1function discounted(total, percent) {2  return total - (total * percent) / 100;3}4 5const order = { total: 50, coupon: 10 };6console.log(discounted(order.total, order.coupn));

1function discounted(total: number, percent: number) {2  return total - (total * percent) / 100;3}4 5const order = { total: 50, coupon: 10 };6console.log(discounted(order.total, order.coupon));

Check your understanding

For each question, read the code or the message part by part: where it is, what's wrong, and whether a change fixes the bug or only hides it. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A type annotation is a colon and a type after a name, like let total: number = 0. It's a promise every later line is checked against.
• Annotations matter most on function parameters, which have no value for TypeScript to learn from.
• An error's first line gives the file, line, and column, the error's number, and the message: the type you have, then the type you need.
• In a message over several lines, the first line says what's wrong, and each indented line goes one step closer to the cause.
• Fix the code instead of hiding the error. If you must hide one, use @ts-expect-error and say why.
• To convert a file: rename it, type the parameters, describe the shapes, and fix what the errors find.

Coming next: Primitive types. It covers string, number, boolean, and the other simple types you just started writing.