Limits & soundness

The checker says yes, and the code still crashes

Control flow analysis showed a call that cleared a coupon while TypeScript said nothing. That wasn't a bug in TypeScript. It is one of a few places where TypeScript lets unsafe code through on purpose. Here is a more common one:

1type User = { name: string; cartCount: number };2 3const reply = '{"name":"Asha"}';4const user = JSON.parse(reply) as User;5console.log(`${user.name} has ${user.cartCount.toFixed(0)} items`);

Line 1 describes a User with a name and a number of cart items. Line 3 is a reply from a server, as text, and it has no cartCount. Line 4 parses it. JSON.parse returns any, a type that turns checking off, and as User tells TypeScript to treat the result as a User. TypeScript reports no errors. Line 5 reads user.cartCount, which is undefined, and toFixed throws a TypeError.

A type system is sound when every program it accepts is free of type errors when it runs: no value ever reaches a place whose type rules it out. TypeScript is not sound. That doesn't mean it's broken. It means it made a few choices, and knowing them tells you exactly where to add a check.

Soundness vs usefulness

The TypeScript team wrote down what the language aims for, on the TypeScript Design Goals page. After the goals comes a list of non-goals: things TypeScript deliberately doesn't try to do. The third non-goal is about soundness:

In plain words: a fully sound checker would reject a lot of everyday JavaScript, and people would stop using it. TypeScript accepts some risk so that it fits the code people already write. The handbook's note on soundness says the same: "The places where TypeScript allows unsound behavior were carefully considered".

The table below lists four lines from that page. Read each row as: what the page says, what it means, and what it means for soundness.

Goals 3 and 7 explain the last part of this lesson. Types are removed before the code runs (see How TypeScript works), so nothing checks the data your page receives.

Holes you open yourself

Some holes only open when you write them. Each one tells TypeScript to stop checking a value:

• any, which turns checking off (see any, unknown, and never);
• as, which asks TypeScript to trust you (see Type assertions);
• ! after a value, which removes null and undefined (see null and undefined);
• reading a list by index, which TypeScript assumes finds an item (see tsconfig strictness);
• passing a list where a wider list goes, which lets the wider name push into it (see Variance).

Pick a hole, then close it, and watch what TypeScript says:

1type User = { name: string; cartCount: number };2 3const saved: any = JSON.parse('{"name":"Asha"}');4const user: User = saved;5console.log(user.cartCount.toFixed(0));

Every version throws when it runs, closed or not: the types are removed first. Closing a hole doesn't make the code work. It makes TypeScript tell you it won't, while you write it, instead of a shopper finding out.

Holes built into the rules

Other holes need no any or as. They come from rules TypeScript chose so that common JavaScript fits. Variance showed two: lists are treated as covariant (the Push hole above), and methods are checked both ways:

1type Product = { name: string; price: number };2type SaleProduct = Product & { salePrice: number };3 4interface ListProps { onSelect(product: Product): void }5 6const props: ListProps = { onSelect: (item: SaleProduct) => console.log(item.salePrice.toFixed(2)) };7props.onSelect({ name: "Tea", price: 3 });

Line 4 writes onSelect as a method. Line 6 gives it a handler that needs a sale price. TypeScript allows it, because method parameters are checked both ways, even with strict on. Line 7 calls it with tea, which has no salePrice, and toFixed throws. Written as a property, onSelect: (product: Product) => void, line 6 would be an error.

A narrower type can also hide a property, and an optional property can then bring it back with the wrong type:

1type Profile = { name: string; age: number };2type Card = { name: string };3type Contact = { name: string; age?: string };4 5const profile: Profile = { name: "Asha", age: 31 };6const card: Card = profile;7const contact: Contact = card;8console.log(contact.age?.toUpperCase());

1. Line 5 makes a profile whose age is the number 31.
2. Line 6 stores it as a Card, which only lists name. That's allowed: extra properties are fine (see Structural typing). The type has forgotten the age, but the object hasn't.
3. Line 7 stores the card as a Contact. Contact's age is optional, and Card says nothing about an age, so that's allowed too.
4. Line 8 calls toUpperCase on contact.age, which is really 31. It throws contact.age?.toUpperCase is not a function.

Without the middle step, TypeScript catches it:

1type Profile = { name: string; age: number };2type Contact = { name: string; age?: string };3 4const profile: Profile = { name: "Asha", age: 31 };5const contact: Contact = profile;

Line 5 gets an error on purpose: Type 'Profile' is not assignable to type 'Contact', and the next line of the message gives the reason, Types of property 'age' are incompatible. The hole needs the Card step, which forgets the age. Excess property checks don't help: they only look at object literals written in place, and line 6 of the first example stores a variable.

Parameters have a hole too. A function with fewer parameters fits where more are passed. That one is safe, and you use it all the time:

1const prices = [3, 4, 5];2prices.forEach((price) => console.log(price));

forEach calls the callback with three arguments: the item, its index, and the list. The callback on line 2 takes only the first and ignores the rest, so it prints 3, 4, and 5. Optional parameters are where it isn't safe. The handbook calls the rule for them "unsound from a type system perspective":

1const formatPrice = (price: number, currency?: string) =>2  `${price} ${currency?.toUpperCase() ?? "USD"}`;3 4const short: (price: number) => string = formatPrice;5const withSale: (price: number, onSale: boolean) => string = short;6console.log(withSale(3, true));

Lines 1 and 2 make formatPrice, which takes a price and an optional currency. Line 4 stores it as a function that takes only a price: fine. Line 5 stores that as a function that takes a price and a boolean: also fine, because a function with fewer parameters fits. But the function is still formatPrice, so line 6 passes true as its currency, and currency?.toUpperCase is not a function.

Where TypeScript stays strict: Object.keys

Sometimes the choice goes the other way, and TypeScript is stricter than you'd like. Object.keys is the best-known case:

1type Prices = { tea: number; cake: number };2const prices: Prices = { tea: 3, cake: 4 };3 4for (const key of Object.keys(prices)) {5  console.log(prices[key]);6}

Line 4 loops over Object.keys(prices), and line 5 reads prices[key]. TypeScript marks line 5 on purpose: Element implicitly has an 'any' type because expression of type 'string' can't be used to index type 'Prices'. In plain words: key is any string, and Prices has no entry for any string. Object.keys returns string[], not ("tea" | "cake")[], because an object can have more keys than its type lists:

1type Prices = { tea: number; cake: number };2const menu = { tea: 3, cake: 4, note: "Fresh today" };3const prices: Prices = menu;4 5let total = 0;6for (const key of Object.keys(prices) as (keyof Prices)[]) {7  total += prices[key];8}9console.log(total);

Line 2's menu has an extra note. Line 3 stores it as Prices, which is allowed: extra properties fit. Line 6 casts the keys to (keyof Prices)[], which is what people wish Object.keys returned, and TypeScript reports nothing. But the loop also visits note, so line 7 adds "Fresh today" to the total, and line 9 prints 7Fresh today.

When you know the keys you want, list them yourself:

1type Prices = { tea: number; cake: number };2const menu = { tea: 3, cake: 4, note: "Fresh today" };3const prices: Prices = menu;4 5const items = ["tea", "cake"] as const;6let total = 0;7for (const key of items) {8  total += prices[key];9}10console.log(total);

Line 5 lists the keys with as const (see const assertions and satisfies), so key is "tea" | "cake". Lines 7 and 8 add only those two prices, and line 10 prints 7. Here TypeScript's strictness was right, and the cast was the hole.

How deep a type can go

A recursive type refers to itself, the way a recursive function calls itself. Writing utility types showed how to write them. The checker has to stop somewhere, or a type that never ends would freeze your editor:

1type Tuple<Item, Length extends number, Items extends Item[] = []> =2  Items["length"] extends Length ? Items : Tuple<Item, Length, [...Items, Item]>;3 4type Week = Tuple<number, 7>;5//   ^?6type Huge = Tuple<number, 1000>;

Lines 1 and 2 describe Tuple: if the list Items already has Length items, that's the answer; if not, call Tuple again with one more item. Line 4 asks for 7 numbers, like a week of daily sales, and the query on line 5 shows [number, number, number, number, number, number, number]. Line 6 asks for 1,000, and TypeScript stops with an error, on purpose: Type instantiation is excessively deep and possibly infinite (error 2589). "Instantiation" means filling in a generic type's parameters. In TypeScript 5.9 this type works up to 999 items and fails at 1,000.

Tuple is tail-recursive: when it calls itself, that call is the whole answer of the branch, with nothing added around it. Since TypeScript 4.5, the checker handles such types without keeping every step, so they can go much deeper. The same type written so that each step adds to the next step's result fails far sooner:

1type Tuple<Item, Length extends number, Count extends unknown[] = []> =2  Count["length"] extends Length ? [] : [Item, ...Tuple<Item, Length, [...Count, unknown]>];3 4type Week = Tuple<number, 7>;5type Row = Tuple<number, 60>;

Line 2 now puts an Item in front of what the next call gives back: [Item, ...Tuple<…>]. Line 4 still works, but line 5 asks for only 60 items and gets the same error 2589.

A different limit is about size:

1type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";2 3type Pin = `${Digit}${Digit}${Digit}${Digit}`;4type LongPin = `${Digit}${Digit}${Digit}${Digit}${Digit}`;

Line 1 lists the ten digits as text. Line 3's Pin is every 4-digit text, a union of 10,000 members, and that's fine. Line 4 would need 100,000, and TypeScript marks it on purpose: Expression produces a union type that is too complex to represent (error 2590).

Neither limit is a setting you can raise. When you hit one, it's usually time to stop making the type fancier:

• Prefer a plainer type and a check while the code runs: number[] and a length check, not a 1,000-item tuple.
• If you need recursion, end each branch with the call itself, and carry the result in an extra type parameter, as Tuple carries Items.
• Ask what the type catches that a simpler type and a test wouldn't. Deep types also slow down every check in your editor. Habits of good TypeScript covers type performance.

Runtime checks still matter

Every hole so far ends the same way: a value that doesn't match its type, found while the code runs. The design goals explain why TypeScript can't help then: the types are gone. Anything that arrives from outside, like a server reply, localStorage, or the URL, is unchecked. Check it yourself, at the edge, where it enters your code:

1type User = { name: string; cartCount: number };2 3function isUser(value: unknown): value is User {4  return (5    typeof value === "object" && value !== null &&6    "name" in value && typeof value.name === "string" &&7    "cartCount" in value && typeof value.cartCount === "number"8  );9}10 11const saved: unknown = JSON.parse('{"name":"Asha"}');12if (isUser(saved)) {13  console.log(`${saved.name} has ${saved.cartCount} items`);14} else {15  console.log("The saved user is out of date");16}

Line 3's isUser is a type guard: it takes unknown and returns value is User. Lines 5 to 7 check that the value is an object with a text name and a number cartCount. Line 11 parses the saved user as unknown, so nothing can use it unchecked. Line 12 runs the check. This saved user has no cartCount, so line 15 prints The saved user is out of date instead of crashing. Inside line 13, saved is a User.

Writing guards by hand gets long for big replies. Typing fetch and JSON shows more ways to check a server's reply.

Auditing a settings loader

This project turns on noUncheckedIndexedAccess. Here is a settings loader that still passes the checker with three holes in it:

1type Settings = { theme: "light" | "dark"; fontSizes: number[] };2 3function loadSettings(text: string) {4  const settings = JSON.parse(text) as Settings;5  const largest = settings.fontSizes[settings.fontSizes.length]!;6  return `${settings.theme}, ${largest.toFixed(0)}px`;7}8 9console.log(loadSettings('{"theme":"dark","fontSizes":[14,16]}'));

1. Line 4: as Settings trusts whatever the text holds.
2. Line 5 reads index length, one past the end: the last item is at length - 1. The setting would mark it as possibly undefined, but the ! turns that check off.
3. Line 6 calls toFixed on undefined, and line 9's call throws a TypeError.

1type Settings = { theme: "light" | "dark"; fontSizes: number[] };2 3function isSettings(value: unknown): value is Settings {4  return (5    typeof value === "object" && value !== null &&6    "theme" in value && (value.theme === "light" || value.theme === "dark") &&7    "fontSizes" in value && Array.isArray(value.fontSizes) &&8    value.fontSizes.every((size) => typeof size === "number")9  );10}11 12function loadSettings(text: string) {13  const settings: unknown = JSON.parse(text);14  if (!isSettings(settings)) return "default settings";15  const largest = settings.fontSizes.at(-1);16  if (largest === undefined) return `${settings.theme}, no sizes`;17  return `${settings.theme}, ${largest.toFixed(0)}px`;18}19 20console.log(loadSettings('{"theme":"dark","fontSizes":[14,16]}'));21console.log(loadSettings('{"theme":"blue"}'));

1. Lines 3 to 10 are a guard: the theme must be "light" or "dark", and fontSizes must be a list of numbers.
2. Line 13 parses the text as unknown, and line 14 falls back to the defaults when the guard says no.
3. Line 15's .at(-1) gives the last size, or undefined for an empty list, and line 16 handles that.

Line 20 prints dark, 16px. Line 21 prints default settings, because "blue" isn't a theme.

Common mix-ups

The table below sums up the holes in this lesson. Read each row as: the hole, what slips through it, and how to close it.

• "No type errors means no type problems when the code runs." No. TypeScript is not sound. Values from any, as, index reads, and outside data can still be the wrong type.
• "Every unsound spot is a bug in TypeScript." No. Most are choices, made so that everyday JavaScript fits. The design goals say soundness is not a goal.
• "as turns a value into another type." No. It changes only what TypeScript believes. Nothing happens when the code runs.
• "strict closes every hole." No. noUncheckedIndexedAccess is a separate setting, methods are still checked both ways, and any, as, and ! still work.
• "Object.keys returning string[] is a mistake." No. An object can have more keys than its type lists, so string[] is the true answer.
• "A fancier type is always safer." No. Deep types hit the checker's limits and slow your editor. A simple type and a runtime check often catch more.

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. Find where checking stopped, then use the hints.

1type Settings = { theme: string; fontSize: number };2 3const settings = JSON.parse('{"theme":"dark"}') as Settings;4console.log(settings.fontSize + 2);

1type Settings = { theme: string; fontSize: number };2 3const saved: unknown = JSON.parse('{"theme":"dark"}');4const fontSize =5  typeof saved === "object" && saved !== null && "fontSize" in saved && typeof saved.fontSize === "number"6    ? saved.fontSize7    : 16;8console.log(fontSize + 2);

const sizes = ["S", "M", "L"];
const first = sizes[0];
const label = first.toLowerCase();
console.log(label);

1const sizes = ["S", "M", "L"];2const first = sizes[0];3const label = first?.toLowerCase() ?? "none";4console.log(label);

1function cartCount(saved: any) {2  return saved.items.length;3}4 5console.log(cartCount(JSON.parse('{"items":[1,2]}')));6console.log(cartCount(JSON.parse("{}")));

1function cartCount(saved: unknown) {2  if (typeof saved === "object" && saved !== null && "items" in saved && Array.isArray(saved.items)) {3    return saved.items.length;4  }5  return 0;6}7 8console.log(cartCount(JSON.parse('{"items":[1,2]}')));9console.log(cartCount(JSON.parse("{}")));

1type Prices = { tea: number; cake: number };2const prices: Prices = { tea: 3, cake: 4 };3 4let total = 0;5for (const key of Object.keys(prices)) {6  total += prices[key];7}8console.log(total);

1type Prices = { tea: number; cake: number };2const prices: Prices = { tea: 3, cake: 4 };3 4const items = ["tea", "cake"] as const;5let total = 0;6for (const key of items) {7  total += prices[key];8}9console.log(total);

1type Profile = { name: string; age: number };2type Card = { name: string };3type Contact = { name: string; age?: string };4 5const profile: Profile = { name: "Asha", age: 31 };6const card: Card = profile;7const contact: Contact = card;8console.log(typeof contact.age);

1type Profile = { name: string; age: number };2type Card = { name: string };3type Contact = { name: string; age?: string };4 5const profile: Profile = { name: "Asha", age: 31 };6const card: Card = { name: profile.name };7const contact: Contact = card;8console.log(typeof contact.age);

1type Seat = { row: string; seat: number };2 3type Row<Length extends number, Count extends unknown[] = []> =4  Count["length"] extends Length ? [] : [Seat, ...Row<Length, [...Count, unknown]>];5 6type BigRow = Row<60>;7type SeatCount = BigRow["length"];

1type Seat = { row: string; seat: number };2 3type Row<Length extends number, Seats extends Seat[] = []> =4  Seats["length"] extends Length ? Seats : Row<Length, [...Seats, Seat]>;5 6type BigRow = Row<60>;7type SeatCount = BigRow["length"];8//   ^?

Check your understanding

For each question, ask where the value comes from and whether anything checked it. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A sound checker never accepts code with a type error. TypeScript is not sound, on purpose: its design goals trade some correctness for productivity.
• any, as, !, index reads, and lists passed as wider lists stop checks. unknown, annotations, noUncheckedIndexedAccess, and readonly close them.
• Methods, hidden optional properties, and optional parameters let some unsafe code through with no cast at all.
• Object.keys gives string[] because objects can have more keys than their types list.
• Recursive types stop at a limit (error 2589), and huge unions too (error 2590). A simpler type is usually the answer.
• Types are gone when the code runs. Check outside data at the edge, with a guard.

This is the last lesson of the TypeScript track. Where to go next:

• Type a small project in the code editor, with strict and noUncheckedIndexedAccess on, and search it for as, any, and !.
• Review Habits of good TypeScript and Reading type errors with this lesson in mind.
• Read the types of a library you use: its .d.ts files (see Declaration files).
• Keep the TypeScript release notes handy: each version changes what the checker can follow.

Coming next: you've finished the track. Go back to the TypeScript track to review any stage.