Habits of Good TypeScript

Habits that let TypeScript help

TypeScript can only check what your types tell it. Here is a cart total with a typo in it, prise instead of price, and the type any on its items:

1function cartTotal(items: any) {2  return items.reduce((sum: number, item: any) => sum + item.price, 0);3}4 5const total = cartTotal([{ name: "Tea", prise: 3 }]);6console.log(total);

Line 1 says items is any, which means "anything at all, don't check it". Line 2 adds up item.price for each item. Line 5 passes an item with prise. There are no errors, and line 6 prints NaN, because item.price is undefined. Now the same code with a real type, and an error on purpose:

1type CartItem = { name: string; price: number };2 3function cartTotal(items: CartItem[]) {4  return items.reduce((sum, item) => sum + item.price, 0);5}6 7const total = cartTotal([{ name: "Tea", prise: 3 }]);8console.log(total);

Line 1 describes a CartItem. Line 3 says items is a list of them, and line 4 needs no types at all: TypeScript works out sum and item from line 3. Line 7 is marked: Object literal may only specify known properties, but 'prise' does not exist in type 'CartItem'. Did you mean to write 'price'? The code still prints NaN if you run it, but you'd fix it before anyone does.

Both versions are valid TypeScript. The difference is a habit. This lesson collects the habits that keep TypeScript checking, each with a before and an after, and links to the lesson that teaches it in full.

Let inference work, annotate the edges

You don't need to write a type on every name. TypeScript works out the type from the value, which is called inference. This code writes every type by hand:

1const taxRate: number = 0.2;2const items: string[] = ["Tea", "Cake"];3const count: number = items.length;4console.log(count);

Lines 1 to 3 each say a type the value already shows: 0.2 is a number, the list holds strings, and .length is a number. Line 4 prints 2. Here it is with no annotations, and a query under each name:

1const taxRate = 0.2;2//    ^?3const items = ["Tea", "Cake"];4//    ^?5const count = items.length;6//    ^?7console.log(count);

The query on line 2 answers const taxRate: 0.2, which is even more exact: a const can never change, so its type is the value itself. Line 4 answers const items: string[] and line 6 const count: number. Same checks, less to read. (Annotations and inference covers the rules.)

An annotation can even make a type worse. Switch line 4 between three versions:

1type Status = "paid" | "shipped";2function ship(status: Status) { console.log(`Order is ${status}`); }3 4const status: string = "paid";5ship(status);6//   ^?

With : string, line 5 is marked: Argument of type 'string' is not assignable to parameter of type 'Status'. The annotation threw away the fact that the value is exactly "paid" (Literal types). With no annotation, TypeScript keeps it, and the error is gone.

So where do you write types? At the edges: the places where values come in or go out, and where TypeScript has nothing to learn from.

• Function parameters. A parameter has no value until someone calls the function.
• The return type of a function other files use, so a mistake inside it is marked inside it.
• Data from outside your code, like a server reply (more on that below).

1type Summary = { count: number; total: number };2 3export function summarize(prices: number[]): Summary {4  const total = prices.reduce((sum, price) => sum + price, 0);5  //    ^?6  return { count: prices.length, total };7}8 9console.log(summarize([3, 4]));

Line 1 names the result's type. Line 3 writes the two edges: the parameter prices: number[] and the return type Summary. Line 4 has no annotation, and the query on line 5 shows const total: number. Line 6 returns the count and the total, and line 9 prints { count: 2, total: 7 }. If line 6 spelled totl, the return type would mark it right there, as Reading type errors showed.

Handle a value instead of silencing the error

Three things turn TypeScript's checks off: the type any, a type assertion like value as Product, and the non-null assertion value!. Each one tells TypeScript "trust me". None of them runs any code: they're removed with the types.

Start with any. When you don't know a value's type yet, like the result of JSON.parse, use unknown instead. It means "could be anything, so check it first". This reply is used without a check, and TypeScript marks it on purpose:

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

Line 1 parses the reply and gives it the type unknown. Line 2 reads data.price, and TypeScript says 'data' is of type 'unknown': prove what it is first. With any, line 2 would pass, and so would data.prise. Add the proof:

1const data: unknown = JSON.parse('{"name":"Tea","price":3}');2if (typeof data === "object" && data !== null && "price" in data) {3  console.log(data.price);4}

Line 2 checks that data is an object, isn't null, and has a price. Inside the if, TypeScript allows data.price, and line 3 prints 3. This is narrowing: a check that TypeScript understands and that really runs. any, unknown, and never compares the two types.

Now ! and as. A Map gives back undefined for a key it doesn't have (Map and Set). Try four ways to deal with that on line 5:

1const stock = new Map([["tea", 5]]);2 3function nextCount(id: string) {4  const count = stock.get(id);5  return count + 1;6}7console.log(nextCount("cake"));

Read the output, not just the error list. count! + 1 and (count as number) + 1 both have no errors and still print NaN: they changed what TypeScript believes, not what the code does. Only (count ?? 0) + 1 handles the missing count, and prints 1 (Nullish coalescing). Use ! and as only when you know something TypeScript can't, and say why in a comment. Type assertions covers the few places they belong.

Make wrong states impossible

A product list loads from a server. It can be loading, failed, or done. A common first type uses a flag and two optional properties:

1type ProductsRequest = {2  loading: boolean;3  error?: string;4  products?: string[];5};6 7const request: ProductsRequest = { loading: true, error: "Timed out", products: ["Tea"] };8console.log(request.loading);

Lines 1 to 5 say a request has a loading flag, maybe an error, and maybe some products. Line 7 makes a request that is loading, failed, and done at the same time. That can't happen, but the type allows it, so there's no error. Every piece of code that reads a request has to guess which mix it got. Line 8 prints true.

Instead, list the states. Give each one a status with its own exact value, and only the properties that state has. This is a discriminated union:

1type ProductsRequest =2  | { status: "loading" }3  | { status: "error"; error: string }4  | { status: "success"; products: string[] };5 6const request: ProductsRequest = { status: "loading", error: "Timed out" };7console.log(request.status);

Lines 1 to 4 say a request is exactly one of three things. Only an error has an error, and only a success has products. Line 6 tries the impossible mix again, and TypeScript marks it: Object literal may only specify known properties, and 'error' does not exist in type '{ status: "loading"; }'. A loading request has no error. The wrong state can't be written.

A union pays off again when you add a state. A switch can end with a default that stores the value in a variable of type never, the type with no values. If every state has a case, nothing reaches default, and that's fine. Add a state and watch:

1type ProductsRequest =2  | { status: "loading" }3  | { status: "error"; error: string }4  | { status: "success"; products: string[] };5 6function message(request: ProductsRequest): string {7  switch (request.status) {8    case "loading":9      return "Loading…";10    case "error":11      return `Failed: ${request.error}`;12    case "success":13      return `${request.products.length} products`;14    default: {15      const unhandled: never = request;16      return unhandled;17    }18  }19}20console.log(message({ status: "success", products: ["Tea", "Cake"] }));

At step 2, the union gets an "empty" state on line 5, and line 16 is marked: Type '{ status: "empty"; }' is not assignable to type 'never'. The error names the state the switch forgot. Step 3 adds its case, and the error is gone. In a real app, this finds every switch that needs the new state, across every file. (Exhaustiveness checking shows other ways to write it.)

Small, precise types

A precise type says exactly what's allowed: "light" | "dark" rather than string. Three tools help keep types precise.

satisfies for config objects

For a settings object, you want two things: a check against Settings, and the exact values you wrote. An annotation gives only the first. satisfies gives both:

1type Theme = "light" | "dark";2type Settings = { theme: Theme; pageSize: number };3 4const settings = {5  theme: "dark",6  pageSize: 20,7} satisfies Settings;8const theme = settings.theme;9//    ^?10console.log(theme);

Lines 1 and 2 describe the settings. Lines 4 to 7 make them and check them with satisfies Settings. Line 8 reads the theme, and the query on line 9 answers const theme: "dark", the exact value. With const settings: Settings, it would be the wider Theme. The check still works, on purpose here:

1type Theme = "light" | "dark";2type Settings = { theme: Theme; pageSize: number };3 4const settings = {5  theme: "drak",6  pageSize: 20,7} satisfies Settings;

Line 5 spells "drak", and TypeScript marks it: Type '"drak"' is not assignable to type 'Theme'. (as const and satisfies covers both.)

readonly where a change would be a bug

A function that gets an array from someone else shouldn't change it. Say so with readonly, and TypeScript holds you to it, on purpose here:

1function halfPrice(prices: readonly number[]) {2  for (let i = 0; i < prices.length; i++) {3    prices[i] = prices[i] / 2;4  }5  return prices;6}7 8const menu = [4, 6];9console.log(halfPrice(menu), menu);

Line 1 takes prices as a readonly number[]. Line 3 writes a new price into it, and TypeScript says Index signature in type 'readonly number[]' only permits reading. The bug is real: run it, and line 9 prints the halved prices and a menu that is halved too, [2, 3]. Return a new array instead:

1function halfPrice(prices: readonly number[]) {2  return prices.map((price) => price / 2);3}4 5const menu = [4, 6];6console.log(halfPrice(menu), menu);

Line 2 builds a new array with map (map, filter, and reduce). No errors, and line 6 prints [2, 3] and the menu unchanged, [4, 6]. (Arrays and tuples covers readonly arrays.)

An as const object instead of an enum

An enum is one of the few TypeScript features that adds JavaScript of its own, so tools that only remove types can't run it (Enums explains this). A plain object with as const gives you the same names, and a union type from its values:

1const OrderStatus = {2  Paid: "paid",3  Shipped: "shipped",4} as const;5type OrderStatus = (typeof OrderStatus)[keyof typeof OrderStatus];6//   ^?7 8function label(status: OrderStatus) {9  return status === OrderStatus.Paid ? "Paid" : "On its way";10}11console.log(label("shipped"));

Lines 1 to 4 are an ordinary object, made as const so each value keeps its exact text. Line 5 builds a type from its values, and the query on line 6 answers type OrderStatus = "paid" | "shipped". Line 9 compares with OrderStatus.Paid, as an enum would. Line 11 prints On its way.

Check data where it comes in

First, turn "strict": true on in tsconfig.json. It turns on the checks this lesson relies on, like strictNullChecks (which reports values that may be null or undefined) and noImplicitAny (which asks for parameter types). Strict mode options lists them all.

Strict checks can't see inside data that arrives while the page runs: a server reply, localStorage, a form, the address bar. That data is a boundary. Check it once, there, and the rest of your code can trust it. Compare a promise with a check:

1type Product = { name: string; price: number };2 3function isProduct(data: unknown): data is Product {4  return (5    typeof data === "object" && data !== null &&6    "name" in data && typeof data.name === "string" &&7    "price" in data && typeof data.price === "number"8  );9}10 11const text = '{"name":"Tea","price":"3"}';12const product = JSON.parse(text) as Product;13console.log(product.price + 1);

Lines 3 to 9 are isProduct, a type guard: a function whose return type data is Product tells TypeScript what a true answer means. With as Product, every reply has no errors, and a price sent as text prints 31. With isProduct check, the same reply prints Not a product, and only a real number reaches data.price + 1.

Larger apps often use a library that builds these checks from a description of the data. Typing fetch and JSON shows both ways.

Types that stay fast to check

In a big project, the editor can slow down: errors take a while to appear, and hovering lags. Most small apps never get there. When yours does, measure first. This command prints how much work the check did:

npx tsc --noEmit --extendedDiagnostics

Its report includes counts like Types and Instantiations, and times like Check time. Run it before and after a change to see whether the change helped. The TypeScript team's performance guide suggests a few habits. The first one also gives better errors. Compare an intersection, &, with an interface that extends another:

1type Product = { id: number; name: string };2type CartLine = Product & { id: string; quantity: number };3 4const line: CartLine = { id: "7", name: "Tea", quantity: 2 };

Line 2 combines Product with a type whose id is a string, but Product's id is a number. Nothing is reported there. A value can't be both, so the combined id is never, and line 4 gets the confusing Type 'string' is not assignable to type 'never'.

1interface Product { id: number; name: string }2interface CartLine extends Product { id: string; quantity: number }3 4const line: CartLine = { id: "7", name: "Tea", quantity: 2 };

Now line 2 itself is marked: Interface 'CartLine' incorrectly extends interface 'Product', ending in Type 'string' is not assignable to type 'number'. The error is where the mistake is. The interface is also one flat type, which the performance guide says the compiler checks faster than an intersection. (Intersection types compares the two.)

Reviewing a checkout module

Here is a checkout screen as it might arrive in a code review. It has no type errors, and it throws when it runs:

1type Checkout = { paid: boolean; failed?: boolean; receipt?: string };2 3function show(checkout: Checkout) {4  if (checkout.paid) return `Receipt ${checkout.receipt!.toUpperCase()}`;5  return checkout.failed ? "Payment failed" : "Waiting";6}7 8const saved: any = JSON.parse('{"paid":true}');9console.log(show(saved));

Line 1 uses flags. Line 4 reads checkout.receipt!, promising the receipt is there. Line 8 parses saved data as any. The saved checkout says it's paid but has no receipt, so line 4 throws a TypeError. Each habit from this lesson removes one way this can happen:

1type Checkout =2  | { status: "waiting" }3  | { status: "failed" }4  | { status: "paid"; receipt: string };5 6function show(checkout: Checkout): string {7  switch (checkout.status) {8    case "paid":9      return `Receipt ${checkout.receipt.toUpperCase()}`;10    case "failed":11      return "Payment failed";12    case "waiting":13      return "Waiting";14  }15}16 17function isCheckout(data: unknown): data is Checkout {18  if (typeof data !== "object" || data === null || !("status" in data)) return false;19  if (data.status === "paid") return "receipt" in data && typeof data.receipt === "string";20  return data.status === "waiting" || data.status === "failed";21}22 23const saved: unknown = JSON.parse('{"status":"paid"}');24console.log(isCheckout(saved) ? show(saved) : "Unknown checkout");

Lines 1 to 4 list the states, and only a paid checkout has a receipt. Line 6 writes the return type. The switch on lines 7 to 14 reads checkout.receipt with no !, because inside case "paid" TypeScript knows it exists. Lines 17 to 21 check saved data, and line 23 types it unknown. The same broken data now prints Unknown checkout instead of throwing.

The whole lesson in one table. Read each row as: what to look for, what to write instead, and the lesson that teaches it.

Now sort some lines from a review. Does each one keep TypeScript checking, or switch it off?

Common mix-ups

• "More annotations make code safer." No. Inside your code they repeat what TypeScript already knows, and a wide one like : string can throw away precision. Write types at the edges.
• "as converts a value." No. It only changes what TypeScript believes. Nothing runs.
• "! checks for null." No. It tells TypeScript not to check. If the value is missing, the code goes on with it.
• "unknown is just a stricter any, so it doesn't matter which." It matters: any turns checks off for everything made from the value, and unknown keeps them on until you check.
• "Optional properties are the easy way to model states." They allow every mix, including impossible ones. A union with a status allows only real states.
• "A slow editor means you need fewer types." No. It usually means some types are built in a costly way. Measure, then use interfaces, names, and base types.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code to change it: the errors update as you type, and the console shows what it prints. Several starters have no errors at all. That's the point: find what the habit would catch.

1type Size = "small" | "large";2function pour(size: Size) {3  console.log(`A ${size} tea`);4}5 6const size: string = "large";7pour(size);

1type Size = "small" | "large";2function pour(size: Size) {3  console.log(`A ${size} tea`);4}5 6const size = "large";7//    ^?8pour(size);

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

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

1const prices = new Map([["tea", 3], ["cake", 4]]);2const scone = prices.get("scone")!;3console.log(scone * 2);

1const prices = new Map([["tea", 3], ["cake", 4]]);2const scone = prices.get("scone");3console.log(scone === undefined ? "No scones today" : scone * 2);

1type Visitor = { loggedIn: boolean; name?: string };2 3function greet(visitor: Visitor) {4  return visitor.loggedIn ? `Hi, ${visitor.name}` : "Hi, guest";5}6console.log(greet({ loggedIn: true }));

1type Visitor = { loggedIn: false } | { loggedIn: true; name: string };2 3function greet(visitor: Visitor) {4  return visitor.loggedIn ? `Hi, ${visitor.name}` : "Hi, guest";5}6console.log(greet({ loggedIn: true, name: "Asha" }));

1type Payment =2  | { method: "card"; last4: string }3  | { method: "cash" }4  | { method: "voucher"; code: string };5 6function receipt(payment: Payment) {7  switch (payment.method) {8    case "card":9      return `Card ending ${payment.last4}`;10    case "cash":11      return "Paid in cash";12  }13}14console.log(receipt({ method: "voucher", code: "TEA10" }));

1type Payment =2  | { method: "card"; last4: string }3  | { method: "cash" }4  | { method: "voucher"; code: string };5 6function receipt(payment: Payment): string {7  switch (payment.method) {8    case "card":9      return `Card ending ${payment.last4}`;10    case "cash":11      return "Paid in cash";12    case "voucher":13      return `Voucher ${payment.code}`;14    default: {15      const unhandled: never = payment;16      return unhandled;17    }18  }19}20console.log(receipt({ method: "voucher", code: "TEA10" }));

1type Order = { id: number; total: number };2 3const order = JSON.parse('{"id":7,"total":"12"}') as Order;4console.log(order.total + 3);

1type Order = { id: number; total: number };2 3function isOrder(data: unknown): data is Order {4  return (5    typeof data === "object" && data !== null &&6    "id" in data && typeof data.id === "number" &&7    "total" in data && typeof data.total === "number"8  );9}10 11const data: unknown = JSON.parse('{"id":7,"total":"12"}');12console.log(isOrder(data) ? data.total + 3 : "Not an order");

Check your understanding

The quiz shows its code without the checker, so the error list doesn't give the answers away. For each question, ask what TypeScript checks, and what really happens when the code runs.

Key takeaways

• Let TypeScript work out types inside your code. Write them on parameters, exported return types, and outside data.
• Use unknown for values you haven't checked, and narrow them. any switches checking off.
• as and ! change what TypeScript believes, not the value. Prefer a check: if, ??, ?., or a type guard.
• Model states as a union with a status, and end each switch with a never check.
• Keep types precise: satisfies for config, readonly for inputs you mustn't change, and as const objects instead of enums.
• Keep strict on, and check outside data once, where it comes in.
• For speed, measure first, then prefer interfaces that extend, named types, and base types over huge unions.

Coming next: Inside the compiler. It follows your code through TypeScript's scanner, parser, binder, checker, and emitter, and shows what each one does.