in & instanceof narrowing

Telling two kinds of object apart

A shop's cart holds two kinds of line: products, with a name and a price, and gift cards, with a code and an amount. A function that takes either one has a parameter typed Product | GiftCard, a union type. To read a price, you first have to find out which kind of line you have. The typeof check from the last lesson can't do it:

1type Product = { name: string; price: number };2type GiftCard = { code: string; amount: number };3 4function lineTotal(line: Product | GiftCard) {5  if (typeof line === "object") {6    return line.price;7  }8  return 0;9}

Lines 1 and 2 describe the two kinds of line. Line 4 takes either one. Line 5 checks typeof line === "object", but products and gift cards are both objects, so the check is true for both and rules nothing out. Line 6 gets an error, on purpose: Property 'price' does not exist on type 'Product | GiftCard'. In plain words: "this might be a gift card, and a gift card has no price".

JavaScript's in operator asks a different question: does this object have a property with this name? (The rest of the operators covers in.) TypeScript reads that check too:

1type Product = { name: string; price: number };2type GiftCard = { code: string; amount: number };3 4function lineTotal(line: Product | GiftCard) {5  if ("price" in line) {6    return line.price;7    //     ^?8  }9  return line.amount;10  //     ^?11}12console.log(lineTotal({ name: "Tea", price: 3 }));13console.log(lineTotal({ code: "GIFT-20", amount: 20 }));

Line 5 asks whether line has a price. Only a Product does, so inside the if, TypeScript treats line as a Product: the query on line 7 shows (parameter) line: Product. Line 6 returns the price. A product returns there, so after the if only a gift card is left, and the query on line 10 shows (parameter) line: GiftCard. Line 9 reads its amount. Line 12 prints 3 for the tea, and line 13 prints 20 for the gift card.

The in operator

Any property that only one of the types has can tell them apart. Pick the property line 5 looks for, and watch what TypeScript says inside and after the if:

1type Product = { name: string; price: number };2type GiftCard = { code: string; amount: number };3 4function lineTotal(line: Product | GiftCard) {5  if ("price" in line) {6    return line.price;7    //     ^?8  }9  return line.amount;10  //     ^?11}12console.log(lineTotal({ name: "Tea", price: 3 }));13console.log(lineTotal({ code: "GIFT-20", amount: 20 }));

"price" and "name" both belong only to Product, so both work. "code" and "amount" belong to GiftCard, so the branches swap: inside the if it's a gift card, and lines 6 and 9 now read the wrong property. TypeScript marks both, and when the code runs, both print undefined.

Things change when a property is optional, written with a ?. An optional property may be there or not, so an in check can't rule its type out:

1type EmailContact = { email: string };2type PhoneContact = { phone: string };3type AnyContact = { email?: string; phone?: string };4 5function contactKind(contact: EmailContact | PhoneContact | AnyContact) {6  if ("email" in contact) {7    return contact;8    //     ^?9  }10  return contact;11  //     ^?12}

Lines 1 to 3 describe three kinds of contact for a sign-up form. EmailContact always has an email, PhoneContact never does, and AnyContact may have either, because both are optional. Line 6 checks for email. The query on line 8 shows the types inside the if: EmailContact | AnyContact. The query on line 11 shows what's left after it: PhoneContact | AnyContact. AnyContact is on both sides, because it may or may not have an email.

An in check also only asks whether the property is there, not what it holds. A property can be there and hold undefined:

1type EmailContact = { email: string };2type PhoneContact = { phone: string };3type AnyContact = { email?: string; phone?: string };4 5function contactText(contact: EmailContact | PhoneContact | AnyContact) {6  if ("email" in contact) {7    return contact.email.toLowerCase();8  }9  return "Call us";10}11console.log(contactText({ email: "Asha@Shop.com" }));12console.log(contactText({ email: undefined, phone: "555-0100" }));

Inside the if, contact may be an AnyContact, whose email may be missing. So line 7 gets an error, on purpose: 'contact.email' is possibly 'undefined'. TypeScript is right. Line 11 prints asha@shop.com, but line 12 passes a contact whose email is there and holds undefined. The in check is true, and line 7 throws a TypeError.

instanceof

instanceof asks a different question: was this value made by this class, with new? (Checking types reliably covers how it works.) It's the check to use for JavaScript's own classes, like Date:

1function formatDate(value: Date | string) {2  if (value instanceof Date) {3    return value.toISOString().slice(0, 10);4    //     ^?5  }6  return value;7  //     ^?8}9console.log(formatDate(new Date(Date.UTC(2026, 9, 24))));10console.log(formatDate("2026-10-24"));

Line 1 takes an order date that is either a Date or text. Line 2 checks value instanceof Date. Inside, the query on line 4 shows (parameter) value: Date, so line 3 can call toISOString, and slice(0, 10) keeps the year, month, and day. After the if, the query on line 7 shows (parameter) value: string. Line 9 passes a real date and line 10 passes text, and both print 2026-10-24.

It works the same for a class you write yourself:

1class GiftCard {2  code: string;3  amount: number;4  constructor(code: string, amount: number) {5    this.code = code;6    this.amount = amount;7  }8}9 10function lineTotal(line: GiftCard | number) {11  if (line instanceof GiftCard) {12    return line.amount;13    //     ^?14  }15  return line;16}17console.log(lineTotal(new GiftCard("GIFT-20", 20)));18console.log(lineTotal(3));

Lines 1 to 8 are a GiftCard class (Class basics covers classes in JavaScript). Lines 2 and 3 list its fields with their types: every gift card has a code that is text and an amount that is a number. You'll see more about typing classes in TypeScript classes, later in the course. Line 10 takes a gift card or a plain number. Line 11 checks line instanceof GiftCard, and the query on line 13 shows (parameter) line: GiftCard, so line 12 can read the amount. Line 17 prints 20, and line 18 prints 3.

So why not write instanceof GiftCard when GiftCard is a type alias, like in the overview? Because instanceof runs while the page runs, and types are removed before that:

1type GiftCard = { code: string; amount: number };2 3function isGiftCard(line: object) {4  return line instanceof GiftCard;5}

Line 1 makes GiftCard a type alias. Line 4 uses it with instanceof, and gets an error, on purpose: 'GiftCard' only refers to a type, but is being used as a value here. In plain words: "GiftCard is only a type, and types don't exist when the code runs". A class is a real value that stays in the code, which is why instanceof needs one. For plain objects, like data from a server, use in.

The table below compares the two checks. Read each row as a question, then each check's answer.

Narrowing in else branches

Every check splits the type in two. The if gets the types the check keeps, and the else gets the rest. With a chain of checks, each else has fewer types left:

1type Product = { name: string; price: number };2type GiftCard = { code: string; amount: number };3type Discount = { label: string; percent: number };4 5function lineText(line: Product | GiftCard | Discount) {6  if ("price" in line) {7    return `${line.name}: $${line.price}`;8  } else if ("amount" in line) {9    return `Gift card: $${line.amount}`;10  } else {11    return `${line.label}: ${line.percent}% off`;12    //        ^?13  }14}15console.log(lineText({ name: "Tea", price: 3 }));16console.log(lineText({ code: "GIFT-20", amount: 20 }));17console.log(lineText({ label: "Welcome", percent: 10 }));

Line 3 adds a third kind of line, a Discount. Line 6 checks for a price, so line 7 has a Product. Line 8 checks the rest for an amount, so line 9 has a GiftCard. Nothing else is left for the last else on line 10, and the query on line 12 shows (parameter) line: Discount, so line 11 can read label and percent without a check. Lines 15 to 17 print Tea: $3, Gift card: $20, and Welcome: 10% off.

The else gets a smaller type only when the check can take a member out of a union. When the type isn't a union, like unknown, there's nothing to take out:

1function problemText(problem: unknown) {2  if (problem instanceof Error) {3    return problem.message;4    //     ^?5  }6  return String(problem);7  //            ^?8}9console.log(problemText(new Error("Offline")));10console.log(problemText("Request timed out"));

Line 1 takes a problem of type unknown, which means "could be any value, so check before you use it". Inside the if, the query on line 4 shows (parameter) problem: Error, so line 3 can read message. After it, the query on line 7 still shows (parameter) problem: unknown: everything that isn't an Error is still any value at all. String(problem) on line 6 works on any value. Line 9 prints Offline, and line 10 prints Request timed out.

Assignments narrow too

Checks aren't the only thing that narrows. When you store a value in a variable, TypeScript remembers what you stored, until the next assignment:

1let coupon: string | number = "TEA10";2console.log(coupon.toLowerCase());3//          ^?4coupon = 10;5console.log(coupon.toFixed(1));6//          ^?7coupon = true;

Line 1 says coupon may hold text or a number, and stores the text "TEA10". The query on line 3 shows let coupon: string, so line 2 can call toLowerCase without a check, and prints tea10. Line 4 stores 10. Now the query on line 6 shows let coupon: number, so line 5 can call toFixed, and prints 10.0.

Line 7 tries to store true and gets an error, on purpose: Type 'boolean' is not assignable to type 'string | number'. The type you wrote on line 1, the declared type, decides what you're allowed to store. What you last stored decides what TypeScript knows is in there now, the narrowed type.

Try it: type what line 4 stores, and watch the query on line 6 and the list under the code.

1let coupon: string | number = "TEA10";2console.log(coupon.toLowerCase());3 4coupon = 10;5console.log(coupon);6//          ^?

"SAVE5" makes coupon a string again, and Number("5") a number. coupon.length works because coupon still holds text on line 4, and length is a number. true and undefined aren't allowed by the declared type, so line 4 gets an error, and the query shows the declared type, string | number.

The table below compares the two types a variable has. Read each row as a question, then each type's answer.

Handling a failed request

A shop page loads its products from a server, and the request can fail. JavaScript lets you throw any value, not only errors, so TypeScript gives the variable in a catch block the type unknown (with strict on):

1try {2  JSON.parse("{ broken");3} catch (error) {4  console.log(error.message);5}

Line 2 parses broken JSON, which throws a SyntaxError, and line 3 catches it as error. Line 4 reads error.message and gets an error, on purpose: 'error' is of type 'unknown'. In plain words: "this could be anything, so check it first". When it runs, this error happens to be a real SyntaxError, so line 4 prints its message. The check is for the times it isn't.

instanceof is the check for errors, because errors are made by classes. Here a loader can fail with a custom HttpError class (Custom errors covers extends Error), a plain Error, or plain text. Pick what line 10 does:

1class HttpError extends Error {2  status: number;3  constructor(status: number) {4    super(`Request failed with status ${status}`);5    this.status = status;6  }7}8 9function loadProducts(): string[] {10  throw new HttpError(404);11}12 13try {14  console.log(loadProducts().join(", "));15} catch (error) {16  if (error instanceof HttpError) {17    console.log(`Server said ${error.status}`);18    //                         ^?19  } else if (error instanceof Error) {20    console.log(`Something broke: ${error.message}`);21    //                              ^?22  } else {23    console.log(`Unknown problem: ${String(error)}`);24    //                                     ^?25  }26}

Lines 16 and 19 check from the most specific class to the least, and line 22 takes everything else. An HttpError is also an Error, because its class extends Error, so the HttpError check has to come first. Inside each branch, the query shows the narrowed type: HttpError, then Error, then unknown for anything else. The last branch uses String(error), which works on any value.

Common mix-ups

• "typeof can tell two object types apart." No. Every object gives "object". Use in for a property only one type has, or instanceof for a class.
• "instanceof works with any type." No. It needs a class, which still exists when the code runs. A type alias or an interface is removed before then.
• "An in check proves the property holds a value." No. It only proves the property is there. An optional property, or one that holds undefined, still needs a check.
• "The else branch gets the declared type back." No. It gets what the check didn't keep: string from Date | string. From unknown, that's still unknown.
• "A variable's type never changes after you declare it." No. The declared type stays, but after coupon = 10 TypeScript knows coupon is a number until the next assignment.
• "The error in a catch block is always an Error." No. Any value can be thrown, so it's unknown until an instanceof Error check.

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.

1type Pickup = { store: string };2type Delivery = { address: string; fee: number };3 4function orderNote(order: Pickup | Delivery) {5  if ("store" in order) {6    return `Collect from ${order.store}`;7  }8  return `Deliver to ${order.address}`;9}10console.log(orderNote({ address: "12 Hill Road", fee: 4 }));

1type Pickup = { store: string };2type Delivery = { address: string; fee: number };3 4function orderNote(order: Pickup | Delivery) {5  if ("store" in order) {6    return `Collect from ${order.store}`;7  }8  return `Deliver to ${order.address}`;9  //                    ^?10}11console.log(orderNote({ address: "12 Hill Road", fee: 4 }));

type Coupon = { code: string; percent: number };

function couponText(coupon: Coupon | string) {
  if (coupon instanceof Coupon) {
    return `${coupon.percent}% off`;
  }
  return coupon;
}

1type Coupon = { code: string; percent: number };2 3function couponText(coupon: Coupon | string) {4  if (typeof coupon === "object") {5    return `${coupon.percent}% off`;6  }7  return coupon;8}9console.log(couponText({ code: "TEA10", percent: 10 }));

1type Pickup = { store: string };2type Delivery = { address: string; fee: number };3 4function shippingFee(order: Pickup | Delivery) {5  return order.fee;6}7console.log(shippingFee({ store: "Market Street" }));8console.log(shippingFee({ address: "12 Hill Road", fee: 4 }));

1type Pickup = { store: string };2type Delivery = { address: string; fee: number };3 4function shippingFee(order: Pickup | Delivery) {5  if ("fee" in order) {6    return order.fee;7  }8  return 0;9}10console.log(shippingFee({ store: "Market Street" }));11console.log(shippingFee({ address: "12 Hill Road", fee: 4 }));

1function orderYear(placed: Date | string) {2  return placed.getFullYear();3}4console.log(orderYear(new Date(2026, 9, 24)));5console.log(orderYear("2025-03-01"));

1function orderYear(placed: Date | string) {2  if (placed instanceof Date) {3    return placed.getFullYear();4  }5  return Number(placed.slice(0, 4));6}7console.log(orderYear(new Date(2026, 9, 24)));8console.log(orderYear("2025-03-01"));

1let selected: string | number = "Green tea";2console.log(selected.toUpperCase());3 4selected = 3;5console.log(selected.toUpperCase());

1let selected: string | number = "Green tea";2console.log(selected.toUpperCase());3 4selected = 3;5console.log(selected.toFixed(0));6//          ^?

1function loadCart(): string[] {2  throw "Network timeout";3}4 5try {6  console.log(loadCart());7} catch (error) {8  console.log(error.message);9}

1function loadCart(): string[] {2  throw "Network timeout";3}4 5try {6  console.log(loadCart());7} catch (error) {8  if (error instanceof Error) {9    console.log(error.message);10  } else {11    console.log(String(error));12  }13}

Check your understanding

For each question, ask: which types does the check keep, and which are left for the other branch? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• typeof gives "object" for every object, so it can't tell two object types apart.
• "price" in line keeps the types that have a price. A type with an optional price stays on both sides.
• value instanceof Date keeps values made by that class. It needs a class, not a type alias or an interface.
• The else branch gets what the check didn't keep. From unknown, that's still unknown.
• Storing a value narrows a variable to that value's type. The declared type only decides what you may store.
• A catch variable is unknown. Check it with instanceof Error, most specific class first.

Coming next: Discriminated unions. Instead of looking for a property only one type has, you give every type the same kind property with a different value, and check that.