any, unknown & never

any, unknown, and never: three special types

Most types describe one kind of value: number, string, an object with a price. Three special types describe something else. any and unknown are for a value that could be anything, like a reply from a server. never is for a value that can't exist at all. Here is a server reply typed as any, with a typo:

1const reply: any = JSON.parse('{ "name": "Tea", "price": 3 }');2console.log(reply.prise);

Line 1 turns the text from the server into an object with JSON.parse (the JSON lesson covers it) and says it's any. Line 2 reads reply.prise, a misspelling of price. TypeScript reports nothing, and the code prints undefined. any means "don't check this value", so TypeScript doesn't. Now the same two lines with unknown:

1const reply: unknown = JSON.parse('{ "name": "Tea", "price": 3 }');2console.log(reply.prise);

The only change is the type on line 1. Now TypeScript marks line 2, on purpose: 'reply' is of type 'unknown'. In plain words: "you haven't checked what reply is, so you can't read anything from it yet". unknown also accepts any value, but it makes you check the value before you use it. The code still prints undefined if you run it, because the types are removed before it runs.

any turns checking off

A value typed any gets no checks at all. You can read any property, call any method, and store it anywhere. TypeScript assumes you know what you're doing. Here is a product typed any:

1const product: any = { name: "Tea", price: 3 };2console.log(product.price.toFixed(2));3console.log(product.prise.toFixed(2));

Line 1 makes a product with a name and a price, and says it's any. Line 2 reads the price and formats it with two decimals: it prints 3.00. Line 3 has the typo prise. TypeScript reports nothing, so the first sign of the bug is when the code runs: product.prise is undefined, and calling toFixed on it throws a TypeError that stops the code.

You don't have to write any to get it. Some functions give it back, and the best-known one is JSON.parse: TypeScript can't know what the text holds. Worse, anything you read from an any is any too:

1const reply = JSON.parse('{ "name": "Tea", "price": 3 }');2//    ^?3const price = reply.price;4//    ^?5const quantity: number = reply.name;6console.log(price, quantity);

Line 1 parses a reply and writes no type. The query on line 2 shows TypeScript gave it const reply: any. Line 3 reads reply.price, and the query on line 4 shows const price: any: still any, still unchecked. Line 5 stores reply.name, the text "Tea", in a variable that must be a number, and there's no error. Line 6 prints 3 Tea: a "number" holding text.

So one any can quietly switch checking off for every value that comes from it. The reply from fetch has the same problem: await response.json() gives back any too (the Fetch lesson covers fetch). Use any rarely, for example for a moment while you move old JavaScript to TypeScript.

unknown: check a value before you use it

unknown is the safe type for a value you don't know yet. Like any, it accepts every value:

1let saved: unknown = 3;2saved = "dark";3saved = { theme: "dark" };4saved = null;5console.log(saved);

Line 1 stores the number 3 in saved. Lines 2 to 4 store text, an object, and null. There are no errors, and line 5 prints null, the last value stored. The difference shows up when you try to use the value:

1const saved: unknown = JSON.parse('"dark"');2console.log(saved.toUpperCase());3const theme: string = saved;

Line 1 reads a saved theme. '"dark"' is the JSON for the text "dark", the way it would be stored in the browser. TypeScript marks two lines, on purpose:

• Line 2: 'saved' is of type 'unknown'. You can't call a method on saved until you've checked what it is.
• Line 3: Type 'unknown' is not assignable to type 'string'. You can't put it into a string variable either, because it might not be text.

To use it, check what it is with typeof, which gives the name of a value's type as text, like "string" or "number" (the Checking types lesson covers it):

1const saved: unknown = JSON.parse('"dark"');2 3if (typeof saved === "string") {4  console.log(saved.toUpperCase());5  //          ^?6}

Line 3 asks whether saved is text. Inside the if, TypeScript knows it is: the query on line 5 shows const saved: string. So line 4 may call toUpperCase, and it prints DARK. Making a type more exact with a check like this is called narrowing; the Narrowing lesson covers it in depth.

Not every check tells TypeScript enough. Try four different checks on line 3, and watch the list under the code:

1const saved: unknown = JSON.parse('"dark"');2 3if (typeof saved === "string") {4  console.log(saved.toUpperCase());5}

Only a check that proves saved is text lets line 4 call toUpperCase. Only check it's there rules out null and undefined but leaves numbers in. Check for a number proves the wrong type, and No real check proves nothing. Every choice except Check for a number prints DARK when it runs, because this saved value happens to be text; TypeScript asks you to be sure.

When you do know the shape of a value, you can give it a real type instead. Line 1 below gives an object type a name, Product, with the word type, so line 3 can use it (the Type aliases & interfaces lesson covers type). Compare the three types for the same reply:

1type Product = { name: string; price: number };2 3const reply: any = JSON.parse('{ "name": "Tea", "price": 3 }');4console.log(reply.price * 2);5console.log(reply.prise);

With any, nothing gets an error, not even the typo on line 5. With unknown, both lines 4 and 5 get errors until you check the reply. With Product, only the typo gets an error, and TypeScript even suggests price. The console output is the same every time, because the types are removed before the code runs. A type like Product is a promise you make: TypeScript can't see inside the text JSON.parse reads, so it trusts you.

never: the type with no values

never is the opposite of unknown. unknown accepts every value; never accepts none. You meet it in three places. The first is a function that never finishes normally, because it always throws:

1function fail(message: string): never {2  throw new Error(message);3}4 5function checkQuantity(quantity: number) {6  if (quantity < 1) fail("Pick at least 1");7  return quantity;8}9 10console.log(checkQuantity(2));

Line 1 says fail returns never: no call to it ever comes back with a value. Line 2 throws an error, which stops the function (the try and catch lesson covers throwing). Line 6 calls fail when the quantity is less than 1, and line 7 returns the quantity otherwise. Line 10 prints 2. With checkQuantity(0), line 6 would throw Pick at least 1.

TypeScript doesn't always work this type out for you. Compare a function declaration and an arrow function that both always throw:

1function fail(message: string) {2//       ^?3  throw new Error(message);4}5 6const stop = (message: string) => {7//    ^?8  throw new Error(message);9};

The query on line 2 shows function fail(message: string): void. void means "returns nothing useful". The query on line 7 shows const stop: (message: string) => never. For a function declaration, TypeScript says void even when it always throws, so write : never yourself when you mean it.

The second place: nothing can ever be stored in a never.

1let leftover: never;2leftover = 3;3leftover = "Tea";

Line 1 makes a variable of type never. Lines 2 and 3 try to store the number 3 and the text "Tea", and both get an error on purpose: Type '3' is not assignable to type 'never'. The '3' in the message is the value itself. No value fits.

The third place is the most useful: never is what's left after checks have ruled out every possible type. This example uses string | number, which means "a string or a number". The next lesson, Union types, covers that |.

1function toQuantity(value: string | number) {2  if (typeof value === "number") return value;3  if (typeof value === "string") return Number(value);4  return value;5  //     ^?6}7 8console.log(toQuantity("2") + toQuantity(3));

Line 1 says value is a string or a number, like a quantity that may come from a form as text. Line 2 returns it when it's a number. Line 3 turns text into a number and returns that. So by line 4, no kind of value is left: the query on line 5 shows (parameter) value: never. Line 4 can never run. Line 7 prints 5, from 2 plus 3. The Exhaustiveness checking lesson uses this to make sure every case is handled.

You'll also meet never where you don't expect it. An empty list inside an object, with no type written, becomes a list of never. (An empty list stored straight in a variable is treated differently; the Arrays & tuples lesson shows that case.)

1const cart = { items: [] };2//    ^?3cart.items.push("Tea");4console.log(cart.items.length);

Line 1 starts a cart with no items. The query on line 2 shows items: never[]: TypeScript saw an empty list and nothing else, so it decided the list holds no values at all. Line 3 gets an error on purpose: Argument of type '"Tea"' is not assignable to parameter of type 'never', which means "this list can't hold "Tea"". The code still runs and line 4 prints 1. The fix is to say what the list will hold:

1const cart: { items: string[] } = { items: [] };2cart.items.push("Tea");3console.log(cart.items.length);

Line 1 says items is a string[], a list of strings, that starts empty. Line 2 adds "Tea" with no error, and line 3 prints 1.

noImplicitAny: no any you didn't write

When TypeScript can't work out a type and you didn't write one, it falls back to any. This is called an implicit any: an any you never asked for. The most common place is a function parameter:

1function formatPrice(price) {2  return "$" + price.toFixed(2);3}4 5console.log(formatPrice(3));

Line 1 takes a price but doesn't say what it is. TypeScript marks it on purpose: Parameter 'price' implicitly has an 'any' type. In plain words: "nothing says what price is, so it would be any and go unchecked". Line 5 prints $3.00 when it runs.

That error comes from a compiler setting called noImplicitAny. It's part of strict, the group of careful settings every example in these lessons uses. Here is the same function with noImplicitAny turned off, called with text:

1function formatPrice(price) {2  return "$" + price.toFixed(2);3}4 5console.log(formatPrice("3"));

The list under the code shows the setting this example changes. There are no errors now: price is quietly any. So line 5 can pass the text "3", and when the code runs, line 2 throws TypeError: price.toFixed is not a function. Keep noImplicitAny on. Type the parameter yourself and watch the errors change:

1function formatPrice(price) {2  return "$" + price.toFixed(2);3}4 5console.log(formatPrice(3));

With price: number, the error is gone and price is checked. price: any also removes the error, because noImplicitAny only reports the any you didn't write. price: unknown moves the error to line 2, where the value is used. The table below sums it up. Read each row as: what you write, then what TypeScript says with the setting on and off.

A saved setting and a caught error

A settings page saves the reader's font size in the browser as JSON text, and reads it back on the next visit. But saved text can be anything: an old version of the page, or a value someone edited by hand. Here is a reader that trusts it:

1function readFontSize(saved: string): number {2  const data = JSON.parse(saved);3  return data;4}5 6const fontSize = readFontSize('"big"');7console.log(fontSize + 2);

Line 1 promises that readFontSize returns a number. Line 2 parses the saved text, and data is any, so line 3 can return it with no error. Line 6 reads a saved value that is the text "big". Line 7 adds 2 and prints big2, and TypeScript said nothing. Now with unknown:

1function readFontSize(saved: string): number {2  const data: unknown = JSON.parse(saved);3  if (typeof data === "number") {4    return data;5  }6  return 16;7}8 9console.log(readFontSize("18") + 2);10console.log(readFontSize('"big"') + 2);

Line 2 says data is unknown. Without line 3, returning it would be an error, because an unknown can't go where a number must. Line 3 checks it's a number, and line 4 returns it. Anything else falls through to line 6, which returns the default size 16. Line 9 prints 20, from a saved 18. Line 10 prints 18: the saved "big" was replaced by 16.

You'll also meet unknown without writing it. In a catch block, the error is unknown, because JavaScript lets you throw any value, not just errors:

1function loadCart() {2  throw new Error("The cart service is down");3}4 5try {6  loadCart();7} catch (error) {8  console.log(error.message);9}

Line 2 throws an Error with a message. Line 6 calls it inside try, and line 7 catches what was thrown. Line 8 reads error.message, and TypeScript marks it on purpose: 'error' is of type 'unknown'. It runs and prints The cart service is down, but only because this code threw a real Error. The fix checks first:

1function loadCart() {2  throw new Error("The cart service is down");3}4 5try {6  loadCart();7} catch (error) {8  if (error instanceof Error) {9    console.log(error.message);10  }11}

Line 8 uses instanceof Error, which is true when the value was made with new Error(…). Inside the if, error is an Error, so line 9 may read its message, and it prints The cart service is down. This setting is called useUnknownInCatchVariables, and it's part of strict too.

Common mix-ups

• "any and unknown are the same." No. Both accept every value, but any lets you use it with no checks, and unknown makes you check it first.
• "No errors with any means the code is right." No. It means TypeScript didn't look. product.prise.toFixed(2) has no error and still throws.
• "JSON.parse gives back unknown." No. It gives back any. Write const data: unknown = JSON.parse(text) to get the careful type.
• "Any check makes an unknown usable." No. The check must prove the type you need. if (saved) leaves a number possible, so toUpperCase still gets an error.
• "never is the same as void." No. void means a function finishes and returns nothing useful. never means it never finishes normally, because it always throws.
• "Writing any fixes a noImplicitAny error." It removes the error, and the checking with it. Write the real type, like price: number, or unknown if you don't know it.

The table below puts the three types side by side. Read each row as a question, then each type's answer.

Practice exercises

Each exercise is TypeScript. When you fix code, press Edit & run on the starter code: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1const order = JSON.parse('{ "id": 7, "paid": false }');2const paid = order.paid;

1const order = JSON.parse('{ "id": 7, "paid": false }');2const paid = order.paid;3//    ^?

const saved: unknown = JSON.parse("16");
const size = saved;
console.log(size + 2);

1const saved: unknown = JSON.parse("16");2const size = saved;3console.log(size + 2); // line 3: 'size' is of type 'unknown'

1const saved: unknown = JSON.parse("16");2console.log(saved.toFixed(1));

1const saved: unknown = JSON.parse("16");2if (typeof saved === "number") {3  console.log(saved.toFixed(1));4}

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

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

1const order: any = JSON.parse('{ "item": "Tea", "quantity": 2 }');2console.log(order.quantaty * 3);

1type Order = { item: string; quantity: number };2 3const order: Order = JSON.parse('{ "item": "Tea", "quantity": 2 }');4console.log(order.quantity * 3);

1const cart = { items: [] };2cart.items.push("Tea");3console.log(cart.items.length);

1const cart: { items: string[] } = { items: [] };2cart.items.push("Tea");3console.log(cart.items.length);

Check your understanding

For each question, keep two moments apart: what TypeScript says before the code runs, and what the code does when it runs. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• any switches checking off: any property, any call, stored anywhere, with no errors.
• any spreads: everything read from it is any too. JSON.parse and response.json() give it back.
• unknown accepts every value, but you must check it, for example with typeof, before you use it.
• The error in a catch block is unknown; check it with instanceof Error.
• never has no values: a function that always throws, what's left after every check, an empty list inside an object with no type.
• noImplicitAny, part of strict, reports an any you didn't write, like a parameter with no type.

Coming next: Union types. A value can be one of several types, like string | number, and you'll see how to work with it safely.