Control flow analysis

A variable's type, line by line

When you check a value, TypeScript gives it a more precise type after the check. That is called narrowing, and Narrowing showed the checks that do it. This lesson shows how TypeScript keeps track: how it knows, on any line, which checks and assignments came before it. Here a shop shows a discount. The discount may be a saved coupon object, text the shopper typed, or null for none:

1type Coupon = { code: string; percent: number };2 3function discountText(coupon: Coupon | string | null) {4  if (coupon === null) {5    return "No coupon";6  }7  if (typeof coupon === "string") {8//           ^?9    coupon = { code: coupon.toUpperCase(), percent: 10 };10//                   ^?11  }12  return `${coupon.code}: ${coupon.percent}% off`;13//          ^?14}15 16console.log(discountText(null));17console.log(discountText("tea10"));18console.log(discountText({ code: "CAKE5", percent: 5 }));

Line 1 describes a Coupon: a code and a percent. Line 3 says coupon may be a Coupon, a string, or null. That is its declared type, the type written where it's declared. Line 4 handles null, and line 5 returns.

1. The query on line 8 points at coupon on line 7 and shows string | Coupon: null is gone.
2. Inside line 7's if, the query on line 10 shows string, so line 9 can call toUpperCase(). Line 9 then stores a new Coupon object in coupon.
3. The query on line 13 shows Coupon on line 12: every path that reaches line 12 brings a coupon object, so coupon.code is fine.

Lines 16 to 18 print No coupon, TEA10: 10% off, and CAKE5: 5% off.

One parameter has three different types on three lines, and TypeScript never ran the code to find them. It read the paths: the routes the code can take from the top of the function to each line. Working out types along those paths is called control flow analysis. "Control flow" is the order in which code can run. Here are the paths through discountText:

Flow nodes: a map of every path

The compiler does this in two parts:

• First, the binder, which Inside the compiler showed giving every name a symbol, walks your code once. On the same walk it records every path as a chain of small markers called flow nodes: where a function starts, the true and the false path of each check, each assignment, each place where paths meet, and where a path ends.
• Then the checker, the part that works out types and reports errors, uses them. When it needs coupon's type on a line, it starts at that line and walks back along the flow nodes to the declaration. On the way it applies each check and assignment it passes, and where paths meet, it follows each one and joins the answers.

The checker only does this for the lines that use a variable, and it keeps some answers it has already worked out, so it doesn't walk the same stretch of paths twice. The table below lists the kinds of flow node. Read each row as: this code, the step it adds to the flow, and what that step does to the type.

Here is discountText again, without the queries. Press each step to move through the flow nodes in the order the code runs, and watch coupon's type:

1type Coupon = { code: string; percent: number };2 3function discountText(coupon: Coupon | string | null) {4  if (coupon === null) {5    return "No coupon";6  }7  if (typeof coupon === "string") {8    coupon = { code: coupon.toUpperCase(), percent: 10 };9  }10  return `${coupon.code}: ${coupon.percent}% off`;11}

Two steps matter most. Step 6: an assignment replaces the narrowed type with the type of what was stored, so the string from line 7 is gone. Step 7: line 10 is a join, a place where paths meet. One path brings the Coupon stored on line 8, the other brings the Coupon left on line 7's false path, and the union of the two is Coupon. The path through line 5 ended, so its null never reaches line 10.

Joins and impossible branches

Every check from Narrowing, in and instanceof, and Type guards is the same kind of step for the checker: a split into a true path and a false path. &&, ||, ??, ? :, and each case of a switch split the flow the same way. This section looks at the other end: what happens where paths meet.

1function shippingFee(express: boolean) {2  let fee: number | string;3  if (express) {4    fee = 10;5  } else {6    fee = "free";7  }8  return fee;9//       ^?10}11 12console.log(shippingFee(true), shippingFee(false));

Line 2 declares fee as number | string with no value yet. On the true path, line 4 stores 10, so there fee is a number. On the false path, line 6 stores "free", a string. Line 8 is where both paths meet, and the query on line 9 shows let fee: string | number: the union of what each path brought. Line 12 prints 10 free.

How inference works showed let total;, with no type, becoming a number after its first assignment. That is this same machinery. A let with no type and no value has no declared type to start from, so the assignments on each path decide everything:

1function badgeText(count: number) {2  let label;3  if (count > 9) {4    label = "9+";5  } else {6    label = count;7  }8  return label;9//       ^?10}11 12console.log(badgeText(12), badgeText(3));

Line 2 declares label with nothing. Line 4 stores "9+" on one path and line 6 stores a number on the other. At line 8 the paths meet, and the query on line 9 shows let label: string | number. Line 12 prints 9+ 3. An empty array learns its type the same way: each push on it is a step in the flow too.

Checks work the other way: each one takes members out of a union. When every member has been taken out, no value can reach the next line:

1type Status = "loading" | "ready" | "failed";2 3function statusText(status: Status) {4  if (status === "loading") return "Loading";5  if (status === "ready") return "Ready";6  if (status === "failed") return "Try again";7  return status;8//       ^?9}10 11console.log(statusText("failed"));

Line 1 lists three statuses. Lines 4, 5, and 6 each handle one and return. No path is left for line 7, and the query on line 8 shows status: never. never is the type with no values: the checker's way of saying this line can't be reached with any status. Line 11 prints Try again. If you added a fourth status to line 1, it would be the only member to reach line 7. Exhaustiveness checking uses exactly this to catch a forgotten case.

Why narrowing resets in callbacks

A callback is a function you hand to other code to call later, like the function you pass to setTimeout (see Timers). It can read the variables of the function around it, because it is a closure. For the checker, that's a problem: the callback runs later, and by then the variable may hold something else.

Here a search waits before it runs. Line 2 returns when there's no query. Line 3 makes a callback that reads query on line 4. Pick what line 6 does, after the callback is made:

1function scheduleSearch(query: string | undefined) {2  if (query === undefined) return;3  setTimeout(() => {4    console.log(`Searching for ${query.toUpperCase()}`);5  }, 0);6  console.log("Search scheduled");7}8 9scheduleSearch("tea");

The rule TypeScript 5.4 added: inside a callback, a let variable or a parameter keeps its narrowing only if no assignment to it comes after the place where the callback is made, and none is inside another function. It looks at where the assignments are, not at what they store. A const can never be assigned again, so it always keeps its narrowing.

The rule covers arrow functions and function expressions. A function declaration inside the function never keeps the narrowing: it is hoisted, so it could be called before the check even ran.

Properties are stricter still. Their narrowing is never kept inside a callback:

1type Search = { query?: string };2 3function scheduleSearch(search: Search) {4  if (search.query === undefined) return;5  setTimeout(() => console.log(search.query.length), 0);6 7  const query = search.query;8  setTimeout(() => console.log(query.length), 0);9}

Line 4 returns when search.query is undefined. Line 5 reads it inside a callback, and TypeScript marks it on purpose: 'search.query' is possibly 'undefined'. In plain words: before the timer fires, any code that holds the search object could clear its query. Line 7 copies the value into a const after the check, and the callback on line 8 reads the copy, with no error. A const copy is the usual fix.

Properties, calls, and await

Outside callbacks, a check narrows a property the way it narrows a variable. The checker tracks cart.coupon as one thing, a reference: a variable followed by property names. Its narrowing lasts until something changes it. What counts as a change? Line 5 checks cart.coupon and line 7 uses it. Pick what happens on line 6:

1type Cart = { items: number; coupon?: string };2const clearCoupon = (cart: Cart) => { cart.coupon = undefined; };3 4function couponLabel(cart: Cart) {5  if (cart.coupon !== undefined) {6    console.log("Applying coupon");7    return cart.coupon.toUpperCase();8  }9  return "No coupon";10}11 12console.log(couponLabel({ items: 2, coupon: "tea10" }));

Assignments reset the narrowing: one to cart.coupon, or one to cart, which resets everything that starts with cart.. A function call doesn't, even one that clears the coupon. The checker doesn't look inside the functions you call; it assumes a call changes nothing. Resetting after every call would be safer, but you would have to check again after each console.log. TypeScript chose the useful rule over the strict one here, on purpose.

An await works the same way. While a function waits, other code can run (see async and await), but the checker keeps the narrowing:

1type Cart = { items: number; coupon?: string };2 3async function applyCoupon(cart: Cart, save: () => Promise<void>) {4  if (cart.coupon === undefined) return "No coupon";5  await save();6  return cart.coupon.toUpperCase();7}8 9applyCoupon({ items: 2, coupon: "tea10" }, async () => {}).then(console.log);

Line 4 returns when there's no coupon. Line 5 waits for save(). Line 6 still sees a string, with no error, and line 9 prints TEA10. If other code might change the coupon while you wait, copy it into a const before the await, as with callbacks.

Checks saved for later

A long check reads better with a name. Since TypeScript 4.4, a check saved in a const still narrows. TypeScript calls this an aliased condition: the const is another name, an alias, for the check.

1function priceLabel(name: string | undefined, price: number | undefined) {2  const ready = name !== undefined && price !== undefined;3  if (ready) {4    return `${name.toUpperCase()}: $${price.toFixed(2)}`;5  }6  return "Loading";7}8 9console.log(priceLabel("tea", 3));10console.log(priceLabel(undefined, 3));

Line 2 saves a check of both parameters in ready. Line 3 tests ready, and TypeScript narrows name and price as if the whole check were written there, so line 4 can call toUpperCase and toFixed. Lines 9 and 10 print TEA: $3.00 and Loading.

It works only when nothing can change between the check and the test:

• the saved check is in a const;
• what it checks is a const, a readonly property, or a parameter that is never assigned in the function.

1function priceLabel(name: string | undefined, price: number | undefined) {2  let ready = name !== undefined && price !== undefined;3  if (ready) {4    return `${name.toUpperCase()}: $${price.toFixed(2)}`;5  }6  return "Loading";7}

Only line 2 changed: let instead of const. Line 4 now gets two errors on purpose, 'name' is possibly 'undefined' and 'price' is possibly 'undefined'. A let could be given a new value between lines 2 and 3, so TypeScript doesn't trust what it holds.

A saved check also works for a discriminated union, a union whose members share a property with a different value in each:

1type Reply = { ok: true; items: string[] } | { ok: false; message: string };2 3function showReply(reply: Reply) {4  const { ok } = reply;5  if (ok) {6    return `${reply.items.length} results`;7  }8  return reply.message;9}10 11console.log(showReply({ ok: true, items: ["Tea", "Cake"] }));

Line 1 describes a reply that has ok: true and items, or ok: false and a message. Line 4 pulls ok out with destructuring. Line 5 tests it, and TypeScript narrows reply itself, so line 6 can read reply.items. Line 11 prints 2 results.

A function can save a check too. Type guards showed that since TypeScript 5.5, a simple check with no return type becomes a type predicate, like score is number. TypeScript decides by following both paths out of the function: true must mean the type, and false must mean not that type.

1const scores = [4, undefined, 0, 5];2 3const isScore = (score: number | undefined) => score !== undefined;4//    ^?5const isTruthy = (score: number | undefined) => !!score;6//    ^?7 8const kept = scores.filter(isScore);9//    ^?10console.log(kept);

1. Line 3: the query on line 4 shows (score: number | undefined) => score is number. When it returns true, score is a number. When it returns false, it's undefined. Both line up, so TypeScript writes the predicate for you.
2. Line 5: the query on line 6 shows plain boolean. When !!score is false, score could be undefined or 0, and 0 is a number. False doesn't mean "not a number", so there's no predicate.
3. Line 8 filters with isScore, and the query on line 9 shows number[]. Line 10 prints [ 4, 0, 5 ]: the zero stays.

Used before assigned, and code that never runs

The same paths answer two more questions: was a variable given a value before it's read, and can a line be reached at all? The first is called definite assignment analysis:

1function shippingFee(express: boolean) {2  let fee: number | string;3  if (express) {4    fee = 10;5  }6  return fee;7}

Line 2 declares fee with no value. Line 4 stores 10 only when express is true. Line 6 reads fee, and TypeScript marks it on purpose: Variable 'fee' is used before being assigned. In plain words: on the path where express is false, nothing was stored, so fee would be undefined, which isn't a number or a string.

Store a value on every path, with an else or a starting value, and the error goes. You can also write let fee!: number | string;. The ! after the name turns the check off for that variable. Like the non-null assertion after a value, it's a promise TypeScript can't check.

A path ends at return and throw, and also at a call to a function that returns never:

1function fail(message: string): never {2  throw new Error(message);3}4 5function priceText(price: number | undefined) {6  if (price === undefined) fail("No price");7  return price.toFixed(2);8}9 10console.log(priceText(3));

Line 1 says fail returns never: it always throws, so it never returns. Line 6 calls it when price is undefined. That call ends the path, like a throw, so line 7 sees a number. Line 10 prints 3.00.

1const fail = (message: string): never => {2  throw new Error(message);3};4 5function priceText(price: number | undefined) {6  if (price === undefined) fail("No price");7  return price.toFixed(2);8}

The same fail, written as an arrow function in a const. Line 7 now gets 'price' is possibly 'undefined', on purpose. So that it doesn't have to work out other types first, TypeScript only treats a call as the end of a path when the call is its own statement and the function's type is written where the function is declared. Line 1 writes the arrow's return type, but no type on const fail. function fail(message: string): never or const fail: (message: string) => never = … both work.

Finally, code that no path reaches at all:

1function cartTotal(prices: number[]) {2  return prices.reduce((sum, price) => sum + price, 0);3  console.log("Total worked out");4}5 6console.log(cartTotal([3, 4]));

Line 2 returns, so no path reaches line 3. By default, editors show such lines faded and TypeScript reports nothing. This example sets allowUnreachableCode: false, a tsconfig.json setting (see tsconfig strictness), so line 3 gets Unreachable code detected, on purpose. Line 6 prints 7.

A search box that waits before it searches

A search box often waits 300 milliseconds after the last key press before it sends a search, so it doesn't send one per letter. The waiting is a callback, and that's where narrowing goes missing. A first version:

1type Search = { query?: string; page: number };2 3function runSearch(search: Search, send: (text: string) => void) {4  if (search.query === undefined || search.query.trim() === "") {5    return "Type something to search";6  }7  setTimeout(() => send(`${search.query.trim()}, page ${search.page}`), 300);8  return `Searching for ${search.query.trim()}`;9}

Line 1 describes a search with an optional query and a page number. Line 4 returns early when there's no query, or only spaces. Line 7 sends the search 300 milliseconds later, from a callback, and reads search.query inside it. TypeScript marks line 7 on purpose: 'search.query' is possibly 'undefined', because a property check never reaches into a callback. Line 8 is fine: it isn't in a callback.

1type Search = { query?: string; page: number };2 3function runSearch(search: Search, send: (text: string) => void) {4  const query = search.query?.trim();5  const hasQuery = query !== undefined && query !== "";6  if (!hasQuery) {7    return "Type something to search";8  }9  setTimeout(() => send(`${query}, page ${search.page}`), 300);10  return `Searching for ${query}`;11}12 13console.log(runSearch({ page: 1 }, console.log));14console.log(runSearch({ query: " tea ", page: 2 }, console.log));

1. Line 4 copies the trimmed query into a const. ?. gives undefined when there's no query (see optional chaining).
2. Line 5 saves the check in a const, hasQuery, and line 6 returns early when it's false.
3. Line 9's callback reads query, a const that is a string after line 6, so there's no error.

Line 13 prints Type something to search. Line 14 prints Searching for tea, and 300 milliseconds later the callback sends tea, page 2, which this example prints with console.log.

Common mix-ups

The table below sums up what keeps a narrowing. Read each row as: what happens between a check and the place that uses it, whether the narrowing survives, and why.

• "TypeScript runs my code to find the types." No. It never runs it. It reads the paths the code can take and works out the types along them.
• "Once a variable is narrowed, it stays narrowed." No. An assignment replaces the narrowed type, and inside a callback the narrowing may not apply at all.
• "A call that changes a property resets its narrowing." No. The checker assumes calls change nothing, so the narrowing survives and the code can crash with no error. Copy the value into a const first.
• "Checking one variable narrows another that holds the same value." No. Each reference is tracked on its own. After let text = title, checking title doesn't narrow text.
• "A saved check works from any variable." No. It must be saved in a const, and what it checks must not be assigned in the function.
• "let fee!: number makes fee safe to read." No. The ! only turns the check off. If no path stores a value, reading it still gives undefined.

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. Follow the paths first, then use the hints.

1function sizeLabel(size: number | string | undefined) {2  if (size === undefined) {3    size = 0;4  }5  return size;6}7 8console.log(sizeLabel(undefined), sizeLabel("M"));

1function sizeLabel(size: number | string | undefined) {2  if (size === undefined) {3    size = 0;4  }5  return size;6//       ^?7}8 9console.log(sizeLabel(undefined), sizeLabel("M"));

function cartMessage(items: number) {
  let message: string;
  if (items === 0) {
    message = "Your cart is empty";
  } else if (items > 0) {
    message = `${items} items`;
  }
  return message;
}

1function cartMessage(items: number) {2  let message: string;3  if (items === 0) {4    message = "Your cart is empty";5  } else {6    message = `${items} items`;7  }8  return message;9}10 11console.log(cartMessage(0), cartMessage(3));

1type Profile = { name: string; nickname?: string };2 3function greetLater(profile: Profile) {4  if (profile.nickname === undefined) return;5  setTimeout(() => console.log(`Hi ${profile.nickname.toUpperCase()}`), 0);6}7 8greetLater({ name: "Asha", nickname: "ash" });

1type Profile = { name: string; nickname?: string };2 3function greetLater(profile: Profile) {4  const nickname = profile.nickname;5  if (nickname === undefined) return;6  setTimeout(() => console.log(`Hi ${nickname.toUpperCase()}`), 0);7}8 9greetLater({ name: "Asha", nickname: "ash" });

1function badge(count: number | undefined, label: string | undefined) {2  let show = count !== undefined && label !== undefined;3  if (show) {4    return `${label}: ${count + 1}`;5  }6  return "";7}8 9console.log(badge(2, "Cart"));

1function badge(count: number | undefined, label: string | undefined) {2  const show = count !== undefined && label !== undefined;3  if (show) {4    return `${label}: ${count + 1}`;5  }6  return "";7}8 9console.log(badge(2, "Cart"));

1type Cart = { items: number; coupon?: string };2 3function useCoupon(cart: Cart) {4  cart.coupon = undefined;5}6 7function checkout(cart: Cart) {8  if (cart.coupon === undefined) return "Paid in full";9  useCoupon(cart);10  return `Paid with ${cart.coupon.toUpperCase()}`;11}12 13console.log(checkout({ items: 2, coupon: "tea10" }));

1type Cart = { items: number; coupon?: string };2 3function useCoupon(cart: Cart) {4  cart.coupon = undefined;5}6 7function checkout(cart: Cart) {8  const coupon = cart.coupon;9  if (coupon === undefined) return "Paid in full";10  useCoupon(cart);11  return `Paid with ${coupon.toUpperCase()}`;12}13 14console.log(checkout({ items: 2, coupon: "tea10" }));

1const scores = [4, undefined, 0, 5];2 3const kept = scores.filter((score) => !!score);4console.log(kept.map((score) => score.toFixed(1)).join(", "));

1const scores = [4, undefined, 0, 5];2 3const kept = scores.filter((score) => score !== undefined);4console.log(kept.map((score) => score.toFixed(1)).join(", "));

Check your understanding

For each question, follow the paths that reach the line. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• TypeScript works out a variable's type on each line from the paths that reach it. It never runs your code.
• The binder records the paths as flow nodes. The checker walks back along them from each line that uses a variable.
• Checks split the flow, assignments replace the type, return and throw end a path, and joins take the union.
• Callbacks keep a const's narrowing, and a let's only when no assignment comes after them. Property narrowing is never kept there.
• Calls and await don't reset narrowing, even when they change the value. Copy into a const when that matters.
• A check saved in a const still narrows, and simple checks in functions become predicates.
• The same paths find variables used before they're assigned, and code no path reaches.

Coming next: Limits & soundness. It looks at the places where TypeScript lets unsafe code through on purpose, like the call that cleared the coupon here, and why.