Narrowing with typeof & truthiness

One check, a more precise type

A shop page shows prices. Most prices are numbers, but some arrive as text from a form, like "4.50". So the function that shows a price takes either one. In TypeScript you write that as string | number. The | means "or": the price is a string or a number. A type like this is called a union type (the Union types lesson covers it).

1function formatPrice(price: string | number) {2  return price.toFixed(2);3}4console.log(formatPrice(3));5console.log(formatPrice("4.50"));

Line 1 says price is a string or a number. Line 2 calls toFixed(2), a number method that writes a number with two decimal places, like 3.00. TypeScript marks line 2, on purpose here:

• Property 'toFixed' does not exist on type 'string | number' means "price might be text, and text has no toFixed". A method has to work for every type in the union before TypeScript allows it.

TypeScript is right. Line 4 prints 3.00, but line 5 passes the text "4.50", and the code stops with a TypeError. The fix is a check you already know from JavaScript, typeof:

1function formatPrice(price: string | number) {2  if (typeof price === "number") {3    return price.toFixed(2);4    //     ^?5  }6  return price;7  //     ^?8}9console.log(formatPrice(3));10console.log(formatPrice("4.50"));

Line 2 asks whether price is a number. Inside the if, on line 3, it must be, so TypeScript allows toFixed. The query on line 4 shows the type there: price: number. (A comment like // ^? asks the page "what type is the name my ^ points at?", and the answer appears after it. In your editor, you point at the name instead.) Every number returns on line 3, so only text reaches line 6, and the query on line 7 says price: string. Lines 9 and 10 print 3.00 and 4.50.

You didn't write a new type anywhere. TypeScript read your if and worked out a smaller type for each branch. This is called narrowing.

typeof checks

In JavaScript, typeof gives back a short piece of text that names a value's kind (the Checking types reliably lesson covers it). It can give eight answers: "string", "number", "bigint", "boolean", "symbol", "undefined", "object", and "function". TypeScript knows what each answer means, so comparing typeof with one of them narrows the value. A check that narrows is called a type guard.

The table below lists the common checks. Read each row as: this check, then what the value can be inside the if.

Try it on the price formatter. Each button puts a different check on line 2. Watch the list under the code and the type the query on line 4 shows.

1function formatPrice(price: string | number) {2  if (typeof price === "number") {3    return price.toFixed(2);4    //     ^?5  }6  return price;7}8console.log(formatPrice(3));9console.log(formatPrice("4.50"));

Only typeof price === "number" leaves a type that has toFixed. With "string", the if holds text instead. With price alone, the if only asks whether price is something other than an empty value like 0 or "". A number and text can both pass, so nothing is ruled out. With "object", nothing can get in, and TypeScript calls that type never: a type with no possible values.

One answer needs care. In JavaScript, typeof null is "object", an old mistake the language kept. TypeScript knows this:

1function tagList(tags: string[] | null) {2  if (typeof tags === "object") {3    return tags.join(", ");4  }5  return "No tags";6}7console.log(tagList(["tea", "green"]));8console.log(tagList(null));

Line 1 says a product's tags are a list of text, or null when it has none. Line 2 checks for "object", hoping to find the array. But null passes that check too, so TypeScript marks line 3, on purpose here: 'tags' is possibly 'null' means "tags could still be null here, and you can't read join from null". Line 7 prints tea, green, and line 8 stops with a TypeError. The next section shows a check that does rule out null.

Truthiness checks

An if doesn't need true or false. It turns any value into one. These values count as false and are called falsy: 0, NaN, the empty text "", 0n, null, undefined, and false itself. Every other value is truthy. (Booleans & truthiness covers this.) Checking a value this way is called a truthiness check, and TypeScript narrows with it:

1function greet(name: string | undefined) {2  if (name) {3    return `Hello, ${name.toUpperCase()}`;4    //               ^?5  }6  return "Hello, guest";7}8console.log(greet("Asha"));9console.log(greet(undefined));10console.log(greet(""));

Line 1 says name is a string or undefined. Line 2 checks if (name). undefined is falsy, so it can't get inside, and the query on line 4 shows name: string. That's why toUpperCase on line 3 is allowed. Line 8 prints Hello, ASHA. Line 9 prints Hello, guest. So does line 10: the empty text is falsy too.

The same kind of check fixes the tag list from the last section:

1function tagList(tags: string[] | null) {2  if (tags) {3    return tags.join(", ");4    //     ^?5  }6  return "No tags";7}8console.log(tagList(["tea", "green"]));9console.log(tagList(null));

null is falsy, and every array is truthy, even an empty one. So inside if (tags) the query on line 4 shows tags: string[], and the error is gone. Line 8 prints tea, green and line 9 prints No tags.

The ! operator, which means "not", flips a check. TypeScript follows that too. Here the empty case is handled first:

1function greet(name: string | undefined) {2  if (!name) {3    return "Hello, guest";4  }5  return `Hello, ${name.toUpperCase()}`;6  //               ^?7}8console.log(greet("Asha"));

Line 2 reads "if there is no name". That branch returns on line 3, so line 5 only runs with a real name, and the query on line 6 shows name: string. Line 8 prints Hello, ASHA.

A truthiness check has one trap. It removes every falsy value, not only the missing ones. Here an order's quantity may be missing:

1function itemsLabel(quantity: number | undefined) {2  if (quantity) {3    return `${quantity} items`;4  }5  return "Quantity missing";6}7console.log(itemsLabel(3));8console.log(itemsLabel(0));

TypeScript reports nothing, because the code is allowed. But line 7 prints 3 items and line 8 prints Quantity missing. Zero is a real quantity, yet 0 is falsy, so it goes to the same branch as undefined.

When 0 or "" is a real answer, check for the missing value itself. That's an equality check, which the next section covers:

1function itemsLabel(quantity: number | undefined) {2  if (quantity !== undefined) {3    return `${quantity} items`;4    //        ^?5  }6  return "Quantity missing";7}8console.log(itemsLabel(3));9console.log(itemsLabel(0));

Line 2 now asks quantity !== undefined. The query on line 4 still shows quantity: number, so the type is just as precise. But 0 stays in the if: line 9 prints 0 items.

Equality checks

TypeScript also narrows with the equality operators ===, !==, ==, and != (Equality & sameness explains the difference between them). Comparing with an exact value is the clearest way to rule out null:

1function searchFor(query: string | null) {2  if (query === null) {3    return "Nothing to search";4  }5  return `Searching for ${query.trim()}`;6  //                      ^?7}8console.log(searchFor("  tea "));9console.log(searchFor(null));

Line 1 says query is text or null, for "the visitor hasn't searched yet". Line 2 checks query === null, and that branch returns on line 3. So on line 5 query can only be text: the query on line 6 shows query: string, and trim(), which removes spaces at both ends, is allowed. Line 8 prints Searching for tea and line 9 prints Nothing to search.

Some values can be both null and undefined. A strict check for one of them leaves the other:

1function nicknameOf(nickname: string | null | undefined) {2  if (nickname !== null) {3    return nickname.toUpperCase();4  }5  return "No nickname";6}7console.log(nicknameOf("Ash"));8console.log(nicknameOf(undefined));

Line 1 says a nickname is text, null, or undefined. Line 2 rules out null only. TypeScript marks line 3, on purpose here: 'nickname' is possibly 'undefined'. Line 7 prints ASH, and line 8 stops with a TypeError. The loose != fixes it, because it treats null and undefined as equal:

1function nicknameOf(nickname: string | null | undefined) {2  if (nickname != null) {3    return nickname.toUpperCase();4    //     ^?5  }6  return "No nickname";7}8console.log(nicknameOf("Ash"));9console.log(nicknameOf(undefined));10console.log(nicknameOf(null));

Line 2 now says nickname != null. That one check removes both, and the query on line 4 shows nickname: string. Line 8 prints ASH, and lines 9 and 10 both print No nickname. This is the one place many teams use != on purpose.

You can also compare two values. If they're equal, they must share a type:

1function sameSetting(saved: string | number, picked: string | boolean) {2  if (saved === picked) {3    return saved.toUpperCase();4    //     ^?5  }6  return "Different";7}8console.log(sameSetting("dark", "dark"));9console.log(sameSetting(1, true));

Line 1 takes a saved setting that is text or a number, and a picked one that is text or a boolean. Line 2 checks that they're the same value. The only type both can be is string, so the query on line 4 shows saved: string, and toUpperCase is allowed. Line 8 prints DARK and line 9 prints Different.

The table below compares the checks for a value that may be missing. Read each row as: this check, what it rules out, and what happens to 0 and "".

Now write a check yourself. Line 3 reads query.trim(), so line 2 has to rule out null first. Type a check in the box and watch the list under the code as you type.

1function searchFor(query: string | null) {2  if (query.length > 0) {3    return `Searching for ${query.trim()}`;4  }5  return "Nothing to search";6}7console.log(searchFor("  tea "));8console.log(searchFor(""));9console.log(searchFor(null));

query.length > 0 reads from query before anything checks it, so it fails on line 2 as well. query, query !== null, query != null, and typeof query === "string" all work. They differ only for the empty search: the truthiness check sends it to Nothing to search, and the others let it in. query !== "" rules out the wrong thing, so null still gets through.

TypeScript follows every path

A check doesn't only narrow inside its own if. TypeScript follows every path the code can take, from top to bottom. When a branch ends with return, the rest of the function knows that branch's types are gone. This is called control flow analysis: "control flow" is the order in which code runs.

1function discountLabel(discount: string | number | undefined) {2  if (discount === undefined) {3    return "No discount";4  }5  if (typeof discount === "string") {6  //         ^?7    return `Coupon ${discount.toUpperCase()}`;8  }9  return `${discount}% off`;10  //        ^?11}12console.log(discountLabel(undefined));13console.log(discountLabel("tea10"));14console.log(discountLabel(20));

Line 1 takes a discount that is a coupon code (text), a percent (a number), or undefined for none. Line 2 handles undefined and returns. So by line 5, the query on line 6 shows discount: string | number. Line 5 handles text and returns on line 7. So line 9 only sees a number: the query on line 10 says discount: number. Lines 12 to 14 print No discount, Coupon TEA10, and 20% off.

Returning early like this is the most common way to narrow. Here a cart badge needs a signed-in user. Line 1 is a type alias: it gives the name User to an object type with a name and a number of cartItems.

1type User = { name: string; cartItems: number };2 3function cartBadge(user: User | null) {4  if (user === null) {5    return "Sign in";6  }7  return `Cart: ${user.cartItems} items`;8  //               ^?9}10console.log(cartBadge({ name: "Asha", cartItems: 2 }));11console.log(cartBadge(null));

Line 3 takes a User or null. Line 4 handles null, and line 5 returns. So on line 7 the query on line 8 shows user: User. Line 10 prints Cart: 2 items and line 11 prints Sign in.

What matters is that line 5 ends the path. Try other things on line 5 and watch the type on line 7:

1type User = { name: string; cartItems: number };2 3function cartBadge(user: User | null) {4  if (user === null) {5    return "Sign in";6  }7  return `Cart: ${user.cartItems} items`;8  //               ^?9}10console.log(cartBadge({ name: "Asha", cartItems: 2 }));11console.log(cartBadge(null));

return and throw both end the path, so line 7 sees only a User. A console.log doesn't, so null flows on to line 7 and TypeScript marks it. The same following works inside ? : and after &&: the part after a check sees the narrower type.

A search box on a real page

In the browser, document.querySelector("input") looks for an <input> on the page. It gives back HTMLInputElement | null: the input, or null when there isn't one. So code that reads a search box starts with a check:

1function searchText(box: HTMLInputElement | null) {2  if (!box) {3    return "No search box on this page";4  }5  const text = box.value.trim();6  //           ^?7  if (text === "") {8    return "Type something to search";9  }10  return `Searching for ${text}`;11}12 13const searchInput = document.createElement("input");14searchInput.value = "  green tea ";15console.log(searchText(searchInput));16console.log(searchText(null));

Line 1 takes the box, or null. Line 2 returns early when there's no box. On line 5, the query on line 6 shows box: HTMLInputElement, so reading box.value is allowed. Line 7 compares the text with "" to catch an empty search. Lines 13 and 14 make an input and fill it, as if the visitor typed "green tea" with extra spaces. Line 15 prints Searching for green tea, and line 16 prints No search box on this page.

Each check sits right where the value is used, and TypeScript follows every one. Now sort some one-line functions: does TypeScript accept each one?

Common mix-ups

• "Narrowing changes the value." No. The value stays exactly as it was. Only TypeScript's idea of its type changes, and your check is plain JavaScript that runs as usual.
• "I need a new annotation to narrow a value." No. TypeScript reads the typeof, if, and === checks you already write.
• "typeof value === "object" means it's a real object." No. typeof null is "object" too, so null is still possible.
• "if (value) only removes null and undefined." No. It removes every falsy value, including 0 and "", which may be real answers.
• "!== null also rules out undefined." No. The strict check rules out only null. Use != null to rule out both.
• "TypeScript forgets my check after the if." No. If the if returns or throws, the rest of the function keeps the narrower type.

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.

1function shortLabel(label: string | number) {2  if (typeof label === "string") {3    return label.slice(0, 3);4  }5  return label;6}7console.log(shortLabel("Green tea"));

1function shortLabel(label: string | number) {2  if (typeof label === "string") {3    return label.slice(0, 3);4  }5  return label;6  //     ^?7}8console.log(shortLabel("Green tea"));

function totalText(total: string | number) {
  if (typeof total === "string") {
    return total.toUpperCase();
  }
  return total.toUpperCase();
}

1function totalText(total: string | number) {2  if (typeof total === "string") {3    return total.toUpperCase();4  }5  return total.toFixed(2);6}7console.log(totalText(7));

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

1function formatPrice(price: string | number) {2  if (typeof price === "string") {3    return "$" + Number(price).toFixed(2);4  }5  return "$" + price.toFixed(2);6}7console.log(formatPrice(3));8console.log(formatPrice("4.5"));

1function discountText(percent: number | undefined) {2  if (percent) {3    return `${percent}% off`;4  }5  return "No discount set";6}7console.log(discountText(20));8console.log(discountText(0));

1function discountText(percent: number | undefined) {2  if (percent !== undefined) {3    return `${percent}% off`;4  }5  return "No discount set";6}7console.log(discountText(20));8console.log(discountText(0));

1type Order = { id: number; items: string[] };2 3function orderSummary(order: Order | undefined) {4  if (order === undefined) {5    console.log("No order yet");6  }7  return `Order ${order.id}: ${order.items.length} items`;8}9console.log(orderSummary({ id: 7, items: ["tea", "cake"] }));

1type Order = { id: number; items: string[] };2 3function orderSummary(order: Order | undefined) {4  if (order === undefined) {5    return "No order yet";6  }7  return `Order ${order.id}: ${order.items.length} items`;8}9console.log(orderSummary({ id: 7, items: ["tea", "cake"] }));10console.log(orderSummary(undefined));

1function displayName(nickname: string | null | undefined, name: string) {2  if (nickname !== null) {3    return nickname.trim();4  }5  return name;6}7console.log(displayName(" Ash ", "Asha"));8console.log(displayName(null, "Asha"));

1function displayName(nickname: string | null | undefined, name: string) {2  if (nickname != null) {3    return nickname.trim();4  }5  return name;6}7console.log(displayName(" Ash ", "Asha"));8console.log(displayName(null, "Asha"));9console.log(displayName(undefined, "Asha"));

Check your understanding

For each question, follow the code from top to bottom and ask which types can still reach the line. The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• A union like string | number only allows what works for every type in it.
• Narrowing is TypeScript reading your checks to work out a smaller type in each branch. You write no new types.
• typeof checks narrow to one kind of value, but "object" still lets null through.
• A truthiness check removes every falsy value, including 0 and "".
• === null and !== undefined rule out one value. != null rules out both null and undefined.
• After an if that returns or throws, the rest of the function keeps the narrower type.

Coming next: in & instanceof narrowing. It tells object types apart by a property they have or the class that made them.