A Cartwheel order has shippingFeeCents: number | null. null means the fee is not known yet (the address is incomplete). 0 means free shipping. Here is the label shown at checkout, as it was first written:
function shippingLabel(feeCents: number | null): string {\n if (!feeCents) return 'Calculated at checkout';\n if (feeCents === 0) return 'Free';\n return `$${(feeCents / 100).toFixed(2)}`;\n}Every free-shipping customer saw “Calculated at checkout”. TypeScript did not complain, because after the first line feeCents is number, and comparing a number with 0 is perfectly legal. The types were right; the narrowing was wrong. This lesson is about how TypeScript narrows, so you can make it work for you instead of trusting it blindly.
TypeScript tracks the type of each variable through every branch and return. The same name can have a different type on each line:
\nfunction shippingLabel(feeCents: number | null): string {\n // feeCents: number | null\n if (feeCents === null) return 'Calculated at checkout';\n // feeCents: number\n if (feeCents === 0) return 'Free';\n // feeCents: number\n return `$${(feeCents / 100).toFixed(2)}`;\n}This is control-flow analysis. Each check splits the flow into branches, and on each branch the variable’s type is the set of values that could still be there. When a branch returns, the code after it only sees what is left.
\nYou narrow with ordinary JavaScript checks; TypeScript understands each one:
\n| Check | \nNarrows | \nExample | \n
|---|---|---|
typeof x === 'string' | \nprimitives | \ntypeof amount === 'number' | \n
x === null, x !== undefined | \nliteral values | \ncoupon !== null | \n
'prop' in x | \nobject unions by property | \n'trackingNumber' in shipment | \n
x instanceof C | \nclass instances | \nerr instanceof TypeError | \n
Array.isArray(x) | \narrays | \nArray.isArray(input) | \n
Truthiness (if (x)) also narrows, and it is the one to be careful with. It removes null and undefined, but also 0, '', NaN and false. For an object or an array, a truthiness check is fine. For a number or a string where zero or empty means something, compare against null explicitly.
in and instanceof in practiceTwo checks deserve a closer look because the checkout client uses them constantly. The payment provider answers with one of two shapes, and only one has a receiptId:
type PaymentReply = { receiptId: string; capturedCents: number } | { declineCode: string };\n\nfunction summarize(reply: PaymentReply): string {\n if ('receiptId' in reply) return `Paid, receipt ${reply.receiptId}`;\n return `Declined (${reply.declineCode})`;\n}'receiptId' in reply keeps only the union members that declare receiptId. It works, but it narrows on the absence of a field in the other members, so adding receiptId? to the decline shape later would quietly break it. When you control the types, a literal discriminant (next lesson) is sturdier.
instanceof is the tool for errors. Under strict, the variable in a catch clause is unknown, because JavaScript lets you throw anything. You narrow before you touch it:
function describeFailure(err: unknown): string {\n if (err instanceof Error) return err.message;\n if (typeof err === 'string') return err;\n return 'Unknown error';\n}Narrowing is a fact about one point in the flow. A callback runs at some other time, so TypeScript is careful about what it carries inside:
\ntype Order = { id: number; couponCode: string | null };\n\nfunction couponBanner(order: Order, names: string[]): string[] {\n if (order.couponCode === null) return [];\n return names.map((n) => `${n}, ${order.couponCode.toUpperCase()} is applied`);\n // Error: 'order.couponCode' is possibly 'null'.\n}Outside the arrow function, order.couponCode is string. Inside it, the narrowing is gone, because couponCode is a mutable property and something could set it back to null before map calls the callback. The fix is to capture the narrowed value in a const, which can never change:
function couponBanner(order: Order, names: string[]): string[] {\n const code = order.couponCode;\n if (code === null) return [];\n return names.map((n) => `${n}, ${code.toUpperCase()} is applied`);\n}Since TypeScript 5.4, parameters and let variables also keep their narrowing inside callbacks, as long as they are not assigned again after the callback is created. Properties never do. Copying into a const works in every version and makes the intent obvious.
filter used to be a classic frustration: coupons.filter((c) => c !== null) still had type (string | null)[]. Since TypeScript 5.5, TypeScript infers a type predicate from simple arrow functions like this one, so the result is string[]:
const coupons: (string | null)[] = ['WELCOME10', null, 'LOYAL5'];\nconst codes = coupons.filter((c) => c !== null); // string[]The inference only happens when the check proves the type in both directions. (c) => !!c is not inferred as a predicate: a falsy result could mean '', not null, so TypeScript cannot conclude that a rejected value is null. The same goes for filter(Boolean). Write the explicit comparison and you get both the narrowing and the correct handling of empty strings.
The exercise below has all three bugs from this lesson in one file. In the next lesson you will design types that make narrowing almost automatic: discriminated unions.
\n","toc":[{"id":"sec-1","text":"Control-flow analysis","level":2},{"id":"sec-2","text":"The narrowing toolbox","level":2},{"id":"sec-3","text":"in and instanceof in practice","level":3},{"id":"sec-4","text":"Where narrowing gets lost","level":2},{"id":"sec-5","text":"Narrowing arrays with filter","level":2}],"takeaways":["Control-flow analysis gives a variable a different type at each point in the code, based on the checks and returns that came before.","Truthiness checks also remove0 and '', so check against null or undefined explicitly when those values are meaningful.","Narrowing of a mutable property is dropped inside callbacks; copy the value into a const before the callback to keep it.","Since TypeScript 5.5, a simple arrow like (c) => c !== null passed to filter is inferred as a type predicate, so the result is narrowed."],"further":[{"title":"Narrowing","url":"https://www.typescriptlang.org/docs/handbook/2/narrowing.html"},{"title":"TypeScript 5.5 release notes (inferred type predicates)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html"}],"quiz":[{"q":"shippingFeeCents is null when the fee is not known yet and 0 for free shipping. What does this return for a free-shipping order?
function label(fee: number | null) {\n if (!fee) return 'Calculated at checkout';\n return fee === 0 ? 'Free' : `${fee / 100}`;\n}'Free' branch is unreachable for 0, because !0 is true and the first return fires first."},{"text":"‘Calculated at checkout’","why":"Correct. The truthiness check treats 0 like null. Write if (fee === null) instead."},{"text":"‘0’","why":"The function never reaches the template string for 0; the truthiness check returns before that."},{"text":"It does not compile, because fee === 0 has no overlap after the check.","why":"After !fee returns, fee is still number, and comparing a number with 0 is allowed. The bug is silent."}],"answer":1},{"q":"Why is order.coupon an error inside the callback?
if (order.coupon !== null) {\n names.map((n) => `${n}: ${order.coupon.toUpperCase()}`);\n}map callbacks are not type-checked under strict.","why":"Callbacks are fully checked. The error exists precisely because they are."},{"text":"Because TypeScript cannot know when the callback runs, and order.coupon is a mutable property that could be null by then.","why":"Correct. Narrowing a mutable property does not carry into a function created inside the block. Copy it into a const first."},{"text":"Because !== null does not narrow; you need typeof order.coupon === 'string'.","why":"Comparing with null narrows fine outside the callback. The problem is the callback boundary, not the check."}],"answer":1},{"q":"Under TypeScript 5.9, what is the type of codes?
string[] when written as coupons.filter((c) => c !== null) with coupons: (string | null)[]","why":"Correct. TypeScript 5.5 and later infer (c) => c !== null as the predicate c is string, so filter narrows the array."},{"text":"string[] when written as coupons.filter(Boolean)","why":"Boolean is not a type predicate, and a truthiness check cannot be one anyway because it also removes ''. The result stays (string | null)[]."},{"text":"string[] when written as coupons.filter((c) => !!c)","why":"Truthiness is not inferred as a predicate, because a falsy result does not prove the value is null; it might be ''."}],"answer":0},{"q":"Which check narrows input: Order | Order[] to Order[]?
typeof input === 'array'","why":"typeof never returns 'array'; for arrays it returns 'object', and TypeScript flags the comparison."},{"text":"input instanceof Object","why":"Both an Order and an array are objects, so this check cannot tell them apart."},{"text":"'length' in input","why":"This narrows only if Order has no length property, which is fragile; a dedicated check is clearer and safer."},{"text":"Array.isArray(input)","why":"Correct. Array.isArray is declared as a type predicate, so the true branch sees Order[] and the false branch sees Order."}],"answer":3}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type Order = {\n id: number;\n couponCode: string | null;\n // null = not known yet (address incomplete); 0 = free shipping\n shippingFeeCents: number | null;\n};\n\nfunction shippingLabel(order: Order): string {\n if (!order.shippingFeeCents) return 'Calculated at checkout';\n if (order.shippingFeeCents === 0) return 'Free';\n return `$${(order.shippingFeeCents / 100).toFixed(2)}`;\n}\n\nfunction usedCoupons(orders: Order[]): string[] {\n return orders.map((o) => o.couponCode).filter((c) => c);\n}\n\nfunction couponBanner(order: Order, names: string[]): string[] {\n if (order.couponCode === null) return [];\n return names.map((n) => `${n}, ${order.couponCode.toUpperCase()} is applied`);\n}\n\nconst orders: Order[] = [\n { id: 1001, couponCode: 'welcome10', shippingFeeCents: 0 },\n { id: 1002, couponCode: null, shippingFeeCents: null },\n { id: 1003, couponCode: 'loyal5', shippingFeeCents: 499 },\n];\nconsole.log(orders.map(shippingLabel), usedCoupons(orders));\n"},"solution":{"ts":"type Order = {\n id: number;\n couponCode: string | null;\n // null = not known yet (address incomplete); 0 = free shipping\n shippingFeeCents: number | null;\n};\n\nfunction shippingLabel(order: Order): string {\n const fee = order.shippingFeeCents;\n if (fee === null) return 'Calculated at checkout';\n if (fee === 0) return 'Free';\n return `$${(fee / 100).toFixed(2)}`;\n}\n\nfunction usedCoupons(orders: Order[]): string[] {\n return orders.map((o) => o.couponCode).filter((c) => c !== null);\n}\n\nfunction couponBanner(order: Order, names: string[]): string[] {\n const code = order.couponCode;\n if (code === null) return [];\n return names.map((n) => `${n}, ${code.toUpperCase()} is applied`);\n}\n\nconst orders: Order[] = [\n { id: 1001, couponCode: 'welcome10', shippingFeeCents: 0 },\n { id: 1002, couponCode: null, shippingFeeCents: null },\n { id: 1003, couponCode: 'loyal5', shippingFeeCents: 499 },\n];\nconsole.log(orders.map(shippingLabel), usedCoupons(orders));\n"},"checks":[{"id":"types","typecheck":true},{"id":"free-shipping","test":"const o = (fee) => ({ id: 1, couponCode: null, shippingFeeCents: fee }); return shippingLabel(o(0)) === 'Free' && shippingLabel(o(null)) === 'Calculated at checkout' && shippingLabel(o(499)) === '$4.99';"},{"id":"used-coupons","test":"const r = usedCoupons([{ id: 1, couponCode: 'A', shippingFeeCents: 0 }, { id: 2, couponCode: null, shippingFeeCents: 0 }, { id: 3, couponCode: 'B', shippingFeeCents: 0 }]); return JSON.stringify(r) === '[\"A\",\"B\"]';"},{"id":"banner","test":"const r = couponBanner({ id: 1, couponCode: 'loyal5', shippingFeeCents: 0 }, ['Mona']); return r.length === 1 && r[0].includes('LOYAL5') && couponBanner({ id: 2, couponCode: null, shippingFeeCents: 0 }, ['Mona']).length === 0;"}],"title":"Fix three narrowing bugs","prompt":"This file has the three narrowing problems from the lesson. Fix them without using the non-null assertion !, as or any:
shippingLabel must return 'Free' when shippingFeeCents is 0, 'Calculated at checkout' when it is null, and a dollar amount like '$4.99' otherwise.usedCoupons must return a real string[] of the non-null coupon codes.couponBanner must compile and still upper-case the code inside the callback.null instead of relying on truthiness.","For 2, TypeScript 5.5+ infers a type predicate from (c) => c !== null, but not from (c) => c.","For 3, copy order.couponCode into a const before you check it, and use that const inside the arrow function."],"explanation":"!fee is true for 0, so free shipping fell into the null branch; checking === null keeps the two meanings apart. filter((c) => c !== null) is inferred as the predicate c is string, so the array is narrowed to string[], while a truthiness callback is not a predicate. In couponBanner, the narrowing of the mutable property order.couponCode does not survive into the callback, but a const can never change, so its narrowed type does.
shippingLabel returns ‘Free’ for 0, ‘Calculated at checkout’ for null and ‘$4.99’ for 499","used-coupons":"usedCoupons keeps only the non-null codes, in order","banner":"couponBanner upper-cases the code and returns [] when there is no coupon"}},"words":744,"readMinutes":4}