Type assertions

Telling TypeScript what you know

A shop page has a search box: <input id="search">, with tea typed in it. Your code finds the box with document.querySelector, which gives back the first element that matches a CSS selector (the DOM navigation lesson covers it). Then it reads what was typed:

1const searchBox = document.querySelector("#search");2//    ^?3console.log(searchBox.value);

Line 1 asks the page for the element with the id search. The query on line 2 shows what TypeScript knows about it: const searchBox: Element | null. An Element is any element on a page, like a <div> or an <input>, and null means nothing was found. Line 3 reads value, and TypeScript marks it twice, on purpose here:

• 'searchBox' is possibly 'null' means "the page might have no element with this id".
• Property 'value' does not exist on type 'Element' means "not every element has a value". A <div> doesn't, so TypeScript won't let you read it from any element.

But you wrote the page, so you know #search is an input box, and input boxes always have a value. TypeScript can't see your HTML. It only reads the code. A type assertion passes on what you know: you write as and a type after a value.

1const searchBox = document.querySelector("#search") as HTMLInputElement;2//    ^?3console.log(searchBox.value);

Line 1 now ends with as HTMLInputElement. HTMLInputElement is the browser's type for an <input> box. The query on line 2 shows TypeScript believes you: const searchBox: HTMLInputElement. Both errors are gone, and line 3 prints tea.

Try it: type a different type after as, and watch the list under the code as you type.

1const searchBox = document.querySelector("#search") as HTMLInputElement;2console.log(searchBox.value);

HTMLElement is any element, so line 2 still can't read value. HTMLSelectElement, a drop-down list, has a value too, so TypeScript accepts it even though the page holds an input box. And number is refused outright, because an element can never be a number. Whatever you type, the code prints tea when it runs: the assertion only changes what TypeScript believes.

Writing an assertion with as

An assertion goes after a value: the value, the word as, then a type. You'll use it most for values that TypeScript knows little about. JSON.parse is one: it turns text into an object (the JSON lesson covers it), and TypeScript can't read what's inside the text.

1type User = { name: string; age: number };2 3const reply = '{ "name": "Asha", "age": 30 }';4const data = JSON.parse(reply);5//    ^?6const user = JSON.parse(reply) as User;7//    ^?8console.log(user.name);

Line 1 describes a User: a name that is text and an age that is a number. Line 3 is a reply from a server, as text. Line 4 parses it, and the query on line 5 shows const data: any. any means "TypeScript stops checking this value": you could misspell data.nmae and get no error. Line 6 parses the same text and adds as User, so the query on line 7 shows const user: User. Now TypeScript checks every use of user, and line 8 prints Asha.

Like every type, an assertion is removed before the browser runs the code. Here is what the browser gets from the overview's example:

const searchBox = document.querySelector("#search");
console.log(searchBox.value);

Line 1 has lost as HTMLInputElement. Nothing is left to check that the element really is an input box, so an assertion can never stop a mistake while the page runs. It only changes what TypeScript believes while it checks your code.

The names are close, so keep two things apart. An assertion function, like assertIsDefined in the Type predicates & assertion functions lesson, is real code: it checks the value while the page runs and throws when the check fails. A type assertion with as has no code at all.

There is a second way to write an assertion: the type in angle brackets, before the value.

1const searchBox = <HTMLInputElement>document.querySelector("#search");2//    ^?3console.log(searchBox.value);

Line 1 writes <HTMLInputElement> before the value. The query on line 2 shows the same type, and line 3 prints tea. This form doesn't work in .tsx files, the files that hold JSX for React, because <HTMLInputElement> looks like a JSX tag there. Most code uses as, and so does this lesson.

You've met one assertion already. In the null and undefined lesson, a ! after a value told TypeScript "this isn't null". That ! is a type assertion too, for that one fact. as can say any type.

Which assertions TypeScript allows

TypeScript trusts an assertion, but not blindly. It allows as only when the two types overlap: when one of them fits inside the other. Here are four assertions in a row:

1const found = document.querySelector("#search");2const input = found as HTMLInputElement; // more specific3const element = input as Element; // less specific4const anything = input as unknown; // fits every type5const count = input as number; // nothing in common

• Line 2 goes from Element | null to HTMLInputElement: a more specific type. An input box is one of the things Element | null can hold, so it's allowed.
• Line 3 goes from HTMLInputElement to Element: a less specific type. Every input box is an element, so it's allowed. You rarely need this one; TypeScript would accept the input box as an element anyway.
• Line 4 goes to unknown, a type that can hold any value at all. Every type fits inside it, so it's allowed.
• Line 5 goes from an input box to number. No input box is a number, and no number is an input box, so TypeScript marks it on purpose.

The message on line 5 is long: Conversion of type 'HTMLInputElement' to type 'number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first. In plain words: "these two types have nothing in common, so this is probably a mistake". Its number is ts(2352). The last sentence hints at a way around it, which the next section looks at.

The table below sums up the four lines. Read each row as: this assertion, does TypeScript allow it, and why.

Double assertions: as unknown as

A shop saves the cart in the browser's storage, which keeps only text (the Web storage lesson covers it). Reading it back gives you a string. Here someone tries to treat that string as a list of cart items:

1type CartItem = { name: string; price: number };2 3const saved = '[{"name":"Tea","price":3}]';4const cart = saved as CartItem[];

Line 1 describes a CartItem. Line 3 is the saved cart: text that describes one tea. Line 4 says it's a CartItem[], a list of cart items. TypeScript refuses, on purpose here, with the message from the last section: Conversion of type 'string' to type 'CartItem[]' may be a mistake. Text is never a list.

The message said "convert the expression to 'unknown' first". Writing two assertions in a row, first to unknown and then to the type you want, is a double assertion. Each step is allowed on its own: any type goes up to unknown, and unknown goes down to any type.

1type CartItem = { name: string; price: number };2 3const saved = '[{"name":"Tea","price":3}]';4const cart = saved as unknown as CartItem[];5//    ^?6console.log(cart.length);

Line 4 now says as unknown as CartItem[]. There is no error, and the query on line 5 shows const cart: CartItem[]. But line 6 prints 26, not 1. The value is still the text from line 3, and a string's length counts its characters.

TypeScript's error was right: the code had a bug, and the double assertion only hid it. The fix is to turn the text into a real list with JSON.parse:

1type CartItem = { name: string; price: number };2 3const saved = '[{"name":"Tea","price":3}]';4const cart = JSON.parse(saved) as CartItem[];5//    ^?6console.log(cart.length);

Line 4 parses the text, which gives back any, and asserts it's a CartItem[]. The query on line 5 shows the same type, and line 6 prints 1: one tea. This single assertion is fine, because you saved this cart yourself and know its shape.

You'll also see as any as, which does the same thing through any. A double assertion turns off the check TypeScript has left. Keep it for the rare case where you really know better, such as a fake object in a test. When TypeScript says two types don't overlap, first look for the bug.

Assertions vs annotations

An annotation is the colon and type after a name, like const tea: CartItem. It looks a little like an assertion, and both give tea the type CartItem. But they ask TypeScript different questions. An annotation asks "does this value fit the type?" An assertion only asks "could this value be the type?" Press each button and watch the list under the code:

1type CartItem = { name: string; price: number };2 3const tea: CartItem = { name: "Tea", price: 3 };4console.log(tea.price * 2);

Annotation, full item has no errors and prints 6. Annotation, price left out gets Property 'price' is missing: the annotation checked the object and found no price. Assertion, price left out is the same object with as CartItem, and TypeScript says nothing. A CartItem has a name, so the two types overlap, and the assertion is allowed. The price is still missing, so tea.price * 2 prints NaN, which means "not a number". Assertion, price as text gets error 2352, because a text price can never be a number price.

So when you make a value yourself, use an annotation. It checks every property, so a missing one is caught before the code runs. Keep as for facts TypeScript can't see. The table compares the two. Read each row as a question, then how each one answers it.

A live search box

A real search box shows results as the shopper types. The code listens for the box's input event, which fires on every key press (the Introduction to events lesson covers listeners).

1const searchBox = document.querySelector("#search") as HTMLInputElement;2 3searchBox.addEventListener("input", (event) => {4  const box = event.target as HTMLInputElement;5  //                ^?6  console.log(`Searching for ${box.value}`);7});8 9searchBox.value = "cake";10searchBox.dispatchEvent(new Event("input"));

Line 1 finds the box and asserts it's an input box, as in the overview. Line 3 adds a listener for the input event. Inside it, line 4 reads event.target, the element the event happened on. The query on line 5 shows its type, EventTarget | null: TypeScript only knows it's something that can get events. You put the listener on the search box, so you know the target is that box, and as HTMLInputElement says so. Lines 9 and 10 act like a shopper: they type cake and fire the event, so line 6 prints Searching for cake.

Both assertions are safe because you know your own page. When you aren't sure, check instead, with a check in an if or a type guard. instanceof asks while the page runs whether a value was made by a class, such as HTMLInputElement (the Checking types reliably lesson covers it):

1const found = document.querySelector("#search");2 3if (found instanceof HTMLInputElement) {4  console.log(`Searching for ${found.value}`);5  //                             ^?6} else {7  console.log("No search box on this page");8}

Line 1 finds the element with no assertion. Line 3 checks it. Inside the if, TypeScript has narrowed found to an input box (the Narrowing lesson explains how): the query on line 5 shows const found: HTMLInputElement, so reading found.value has no error. Line 4 prints Searching for tea. On a page with no search box, line 7 would print a message instead of throwing an error.

The table lists common places you might reach for as. Read each row as: this situation, what to write, and why.

Common mix-ups

The most common mix-up is to use as to change a value. Here is text asserted as a number, next to a real conversion:

1const quantity = "3" as unknown as number;2//    ^?3console.log(quantity + 1);4console.log(Number("3") + 1);

Line 1 asserts the text "3" is a number, and the query on line 2 shows TypeScript believes it. Line 3 adds 1 and prints 31, because the value is still text and + joins text. Line 4 converts with Number("3"), which really makes the number 3, and prints 4.

• "as number turns a value into a number." No. An assertion never changes a value. Use Number() to convert text.
• "TypeScript checks my assertion while the page runs." No. The assertion is removed with the types. A wrong one shows up later, as a wrong value or an error.
• "An assertion and an annotation do the same thing." No. An annotation checks that the value fits. An assertion only checks that the types overlap, so a missing property gets through.
• "No error means my assertion is right." No. TypeScript allowed HTMLSelectElement for an input box. It can't see the page, so it can't know.
• "When TypeScript refuses an assertion, add as unknown." No. Error 2352 usually means a real bug, like the saved cart that was still text.
• "Every element needs an assertion." No. querySelector("input") with a tag name already gives HTMLInputElement | null. You need as for selectors like ids and classes.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code to try a fix: the errors update as you type, and the console shows what it prints. The page for these exercises has a search box holding tea and an email box holding asha@example.com.

const priceText = "12";
const price = priceText as number;
console.log(price + 1);

1const priceText = "12";2const price = Number(priceText);3console.log(price + 1);

1type User = { name: string; age: number };2 3const reply = '{ "name": "Asha", "age": 30 }';4const user = JSON.parse(reply) as User;

1type User = { name: string; age: number };2 3const reply = '{ "name": "Asha", "age": 30 }';4const user = JSON.parse(reply) as User;5//    ^?

1const emailBox = document.querySelector("#email");2console.log(emailBox.value);

1const emailBox = document.querySelector("#email") as HTMLInputElement;2console.log(emailBox.value);

1type CartItem = { name: string; price: number };2 3const cake = { name: "Cake" } as CartItem;4console.log(cake.price * 2);

1type CartItem = { name: string; price: number };2 3const cake: CartItem = { name: "Cake", price: 4 };4console.log(cake.price * 2);

1type CartItem = { name: string; price: number };2 3const saved = '[{"name":"Tea","price":3},{"name":"Cake","price":4}]';4const cart = saved as unknown as CartItem[];5console.log(`${cart.length} items`);

1type CartItem = { name: string; price: number };2 3const saved = '[{"name":"Tea","price":3},{"name":"Cake","price":4}]';4const cart = JSON.parse(saved) as CartItem[];5console.log(`${cart.length} items`);

1const searchBox = document.querySelector("#serch") as HTMLInputElement;2console.log(searchBox.value.toUpperCase());

1const searchBox = document.querySelector("#serch");2if (searchBox instanceof HTMLInputElement) {3  console.log(searchBox.value.toUpperCase());4} else {5  console.log("No search box");6}

Check your understanding

For each question, keep two moments apart: what TypeScript believes while it checks, and what the value really is when the code runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A type assertion, value as Type, tells TypeScript what type a value has when you know more than it can see, like which element a selector finds.
• TypeScript trusts an assertion. It's removed before the code runs, so nothing checks it, and it never changes a value.
• as is allowed only when the types overlap: a more specific or less specific type. Otherwise you get error 2352.
• as unknown as gets past that error, but the value stays what it was. Error 2352 usually points at a real bug.
• An annotation checks that a value fits; an assertion doesn't. Use annotations for values you create.
• When you aren't sure, check the value with code like instanceof, or convert it with Number().

Coming next: as const & satisfies. Two more ways to talk to TypeScript about a value: keep its exact values, and check it against a type without losing them.