Unions, Narrowing & Type Guards

A union type A | B says "this value is one of these, and right now I don't know which". It's easiest to think of types as sets of values: string is the set of every string, number the set of every number, and string | number is the bigger set that holds both. Unions exist because real JavaScript values are often one of several things: an ID that might be a string or a number, a parameter that accepts a selector or an element, an API result that is either data or an error, or simply User | null for "might be missing".

The price of that flexibility: while you hold a union, TypeScript only lets you do what is safe for every member. If id might be a number, id.toUpperCase() could crash, so it's refused. To use something member-specific you narrow: you write an ordinary runtime check (typeof, ===, instanceof, in …), and the compiler follows your ifs, returns and switches and works out a more precise type for the variable in each branch. This is called control flow analysis. A variable has one declared type, but at every point in the code it also has a narrowed type: whatever is left after the checks that must have passed to get there.

A mental model: a union is a sealed envelope that holds one of several things. Outside the if, you can only do what works for anything that might be inside. The check is you opening the envelope; inside each branch you know exactly what you're holding.

The example from my notes — I added toUpperCase() and toFixed() so each branch uses something only its member has:

function printId(id: string | number): void {
  if (typeof id === "string") {
    console.log(`ID is a string: ${id.toUpperCase()}`);
  } else {
    console.log(`ID is a number: ${id.toFixed(2)}`);
  }
}

printId("abc-123"); // ID is a string: ABC-123
printId(42); // ID is a number: 42.00

function shout(id: string | number) {
  console.log(id.toString()); // fine: both string and number have toString()
  return id.toUpperCase(); // ❌ Property 'toUpperCase' does not exist on type 'string | number'.
}

function initials(name: string | null | undefined): string {
  if (name == null) return "?";
  // from here on, name is string
  return name
    .split(" ")
    .map((part) => part[0])
    .join("");
}

console.log(initials("Ada Lovelace")); // AL
console.log(initials(undefined)); // ?

An intersection type A & B describes a value that is an A and a B at the same time — it has to satisfy both. For object types that means it has every property of A plus every property of B. In set terms it's the overlap: the values that belong to both sets, and an object with all four properties is in the "has street and city" set and the "has name and phone" set.

Intersections are how you compose types from smaller pieces with type aliases — the type equivalent of interface … extends (see Extending interfaces and intersecting types). They're also how you add properties to a type you don't own, like Props & { onClose(): void }, or describe what a mixin returns.

From my notes:

type Address = { street: string; city: string };
type Contact = { name: string; phone: string };
type Person = Address & Contact;

const ana: Person = {
  street: "1 Main St",
  city: "Toronto",
  name: "Ana",
  phone: "555-0100",
};

const noPhone: Person = { street: "1 Main St", city: "Toronto", name: "Ana" }; // ❌ Property 'phone' is missing

interface Car {
  drive(): void;
}
interface Boat {
  sail(): void;
}
type AmphibiousVehicle = Car & Boat;

const vehicle: AmphibiousVehicle = {
  drive: () => console.log("Driving on land!"),
  sail: () => console.log("Sailing on water!"),
};

vehicle.drive(); // Driving on land!
vehicle.sail(); // Sailing on water!

function park(car: Car) {
  car.drive();
}
park(vehicle); // Driving on land! — accepted because every AmphibiousVehicle is also a Car

type WithStringId = { id: string };
type WithNumberId = { id: number };
type Both = WithStringId & WithNumberId;
// Both["id"] is string & number, which is never

const record: Both = { id: "abc" }; // ❌ Type 'string' is not assignable to type 'never'.

This is the counterintuitive part. Read | as "or" and & as "and", and you'd expect a union of two object types to have the properties of either, and an intersection to have only the common ones. It's the other way round.

The names describe sets of values, not sets of properties. A union is a bigger set of values: any value of A | B could be an A or a B, so you know less about it and can only touch the properties they all share. An intersection is a smaller set of values: every value of A & B satisfies both, so you know more about it and can use every property. More possible values means fewer guaranteed properties.

type HasName = { name: string };
type HasAge = { age: number };

const a: HasName | HasAge = { name: "Ana" }; // OK: it's a HasName
const b: HasName | HasAge = { name: "Ana", age: 30 }; // OK: extra members are allowed
const c: HasName & HasAge = { name: "Ana", age: 30 }; // must have both

function greet(p: HasName | HasAge) {
  return p.name; // ❌ Property 'name' does not exist on type 'HasAge | HasName'.
}

type UnionKeys = keyof (HasName | HasAge); // never — no key is common to both
type IntersectionKeys = keyof (HasName & HasAge); // "name" | "age"

type StrOrNum = string | number; // any string or any number
type StrAndNum = string & number; // never — no value is both

type Common = ("a" | "b" | "c") & ("b" | "c" | "d"); // "b" | "c"
type OnlyNumber = (string | number) & (number | boolean); // number

type HasName = { name: string };
type HasAge = { age: number };

const u: HasName | HasAge = { name: "Ana" };
u.name; // ?

const v: HasName | HasAge = { name: "Ana", age: 30 };
v.age; // ?

JavaScript's typeof operator returns one of eight strings: "string", "number", "bigint", "boolean", "symbol", "undefined", "object" or "function". TypeScript recognises typeof x === "…" (and !==, and switch (typeof x)) as a type guard and narrows x to the matching type.

It's the right tool for primitives and for telling functions apart from other values. It can't tell one object type from another — every object, array, Date and null is just "object" — so for objects you use instanceof, in or a discriminant.

From my notes:

function formatInput(input: string | number | boolean): string {
  if (typeof input === "string") {
    return input.toUpperCase();
  } else if (typeof input === "number") {
    return input.toFixed(2);
  } else {
    return input ? "True" : "False";
  }
}

console.log(formatInput("hi")); // HI
console.log(formatInput(3.14159)); // 3.14
console.log(formatInput(false)); // False

function count(items: string[] | null): number {
  if (typeof items === "object") {
    return items.length; // ❌ 'items' is possibly 'null'.
  }
  return 0;
}

TypeScript has two different typeofs that share a keyword, and which one you get depends on where you write it:

• In a value position (inside an expression), it's JavaScript's runtime operator. It runs when the code runs, returns a string like "object", and stays in the compiled output. This is the one that narrows.
• In a type position (after a :, in a type X = …, inside <…>), it's TypeScript's type query: "give me the static type of this variable". It runs at compile time and is erased completely.

const config = {
  host: "localhost",
  port: 8080,
  secure: false,
};

// Type position: a type query, erased at compile time
type Config = typeof config;
// type Config = { host: string; port: number; secure: boolean; }

type Port = typeof config.port; // number — property paths are allowed

// Value position: the JavaScript operator, runs at runtime
const kind = typeof config;
console.log(kind); // object

x instanceof C is a runtime check: it walks x's prototype chain looking for C.prototype. TypeScript treats it as a type guard: in the true branch x is narrowed to the instance type of C, and in the else branch that type is removed from the union.

The important limit, from my notes: you can't use instanceof with types or interfaces, because they don't exist at runtime — there's no Animal.prototype to look for after compilation. It only works with classes (or old-style constructor functions), which are real values.

From my notes:

class Dog {
  bark() {
    console.log("Woof!");
  }
}
class Cat {
  meow() {
    console.log("Meow!");
  }
}

function makeNoise(animal: Dog | Cat) {
  if (animal instanceof Dog) {
    animal.bark();
  } else {
    animal.meow();
  }
}

makeNoise(new Dog()); // Woof!
makeNoise(new Cat()); // Meow!

interface Animal {
  name: string;
}

function check(x: unknown) {
  if (x instanceof Animal) { // ❌ 'Animal' only refers to a type, but is being used as a value here.
    console.log("an animal");
  }
}

function toMessage(err: unknown): string {
  if (err instanceof Error) return err.message;
  if (typeof err === "string") return err;
  return "Unknown error";
}

function toDate(input: Date | string | number): Date {
  return input instanceof Date ? input : new Date(input);
}

console.log(toMessage(new TypeError("bad input"))); // bad input
console.log(toDate("2026-01-15").getUTCFullYear()); // 2026

"key" in obj is a runtime check that's true when obj has a property called key — its own or inherited from the prototype chain. TypeScript uses it to narrow a union of object types: in the true branch it keeps the members that declare that key; in the false branch it keeps the members that don't require it.

It's the simple, everyday way to tell interfaces apart, because it checks the data, not the type — so it works with interfaces, type aliases and plain objects from JSON, where instanceof can't.

interface Fish {
  swim(): void;
}
interface Bird {
  fly(): void;
}

function move(animal: Fish | Bird) {
  if ("swim" in animal) {
    animal.swim(); // animal: Fish
  } else {
    animal.fly(); // animal: Bird
  }
}

move({ swim: () => console.log("splash") }); // splash
move({ fly: () => console.log("flap") }); // flap

interface Fish {
  swim(): void;
}
interface Bird {
  fly(): void;
}
interface Human {
  swim?(): void;
  fly?(): void;
}

function move(animal: Fish | Bird | Human) {
  if ("swim" in animal) {
    // animal: Fish | Human
    animal.swim?.();
  } else {
    // animal: Bird | Human
    animal.fly?.();
  }
}

function getName(data: unknown): string | undefined {
  if (typeof data === "object" && data !== null && "name" in data) {
    // data: object & Record<"name", unknown>
    if (typeof data.name === "string") {
      return data.name; // string
    }
  }
  return undefined;
}

console.log(getName(JSON.parse('{"name":"Ana"}'))); // Ana
console.log(getName(JSON.parse('{"name":42}'))); // undefined

Sometimes the built-in checks can't express the test you need, or you want to give a check a name and reuse it. A custom type guard (or user-defined type guard) is a function whose return type is a type predicate: paramName is SomeType.

At runtime it's just a function that returns a boolean. At compile time, the predicate links that boolean to the argument: when the call returns true, the argument is narrowed to SomeType at the call site; when it returns false, SomeType is removed from it. Think of it as teaching the compiler a new kind of typeof.

The example from my notes:

interface Fish {
  swim: () => void;
}
interface Bird {
  fly: () => void;
}

function isFish(animal: Fish | Bird): animal is Fish {
  return (animal as Fish).swim !== undefined;
}

function move(animal: Fish | Bird) {
  if (isFish(animal)) {
    animal.swim();
  } else {
    animal.fly();
  }
}

interface User {
  id: number;
  name: string;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    typeof value.id === "number" &&
    "name" in value &&
    typeof value.name === "string"
  );
}

const body: unknown = JSON.parse('{"id": 1, "name": "Ana"}');
if (isUser(body)) {
  console.log(body.name.toUpperCase()); // ANA
}

const rows: unknown[] = [{ id: 1, name: "Ana" }, { id: "2" }, null];
const users = rows.filter(isUser); // users: User[]
console.log(users.length); // 1

The compiler trusts a type predicate. It checks that the body returns a boolean and that the predicate type fits the parameter — and that's it. It never checks whether your runtime logic actually proves the claim. A type guard is a type assertion wrapped in a function: if the body is wrong, the narrowing is wrong, and the compiler will confidently let you call things that don't exist.

There are two ways for a guard to lie, and they crash in different branches:

• Too loose — returns true for values that aren't T. The crash is in the true branch.
• Too strict — returns false for values that are T. The crash is in the else branch, because else narrows to "everything except T".

A too-loose guard: it says "this is a User" after checking only one of the two fields.

type User = { name: string; email: string };

function isUser(value: unknown): value is User {
  return typeof value === "object" && value !== null && "name" in value; // never checks email
}

const data: unknown = JSON.parse('{"name":"Ana"}');

if (isUser(data)) {
  console.log(`Hello ${data.name}`); // Hello Ana
  console.log(data.email.toLowerCase()); // TypeError: Cannot read properties of undefined (reading 'toLowerCase')
}

interface Fish {
  swim: () => void;
}
interface Bird {
  fly: () => void;
}

function isFish(animal: Fish | Bird): animal is Fish {
  return "swin" in animal; // typo: should be "swim"
}

function move(animal: Fish | Bird) {
  if (isFish(animal)) {
    animal.swim();
  } else {
    animal.fly();
  }
}

move({ fly: () => console.log("flap flap") }); // flap flap
move({ swim: () => console.log("splash") }); // TypeError: animal.fly is not a function

function isString(value: unknown): value is string {
  return true; // compiles — nothing compares this to the claim
}

const values = [1, null, 2, undefined, 3]; // (number | null | undefined)[]

const a = values.filter((x) => x !== null); // (number | undefined)[]
const b = values.filter((x) => x != null); // number[]
const c = values.filter((x) => !!x); // (number | null | undefined)[] — no predicate inferred

const isNumber = (x: unknown) => typeof x === "number";
// const isNumber: (x: unknown) => x is number

An assertion function is the throwing cousin of a type guard. Instead of returning true or false, it throws if the check fails. If it returns normally, the compiler narrows the argument for the rest of the scope — no if block needed. They were added in TypeScript 3.7 and come in two forms:

• asserts condition — "if I return, the expression you passed me was truthy", so whatever that expression narrows, stays narrowed.
• asserts value is T — "if I return, value is a T".

They fit code that should simply stop when an assumption is broken: validating config at startup, invariants inside a function, and tests. Node's own assert is typed this way.

function assert(condition: unknown, message = "Assertion failed"): asserts condition {
  if (!condition) throw new Error(message);
}

function assertIsString(value: unknown): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`Expected a string, got ${typeof value}`);
  }
}

function greet(user: { name: string } | null, input: unknown): string {
  assert(user !== null, "No user");
  // user: { name: string } from here to the end of the function
  assertIsString(input);
  // input: string
  return `${user.name}: ${input.toUpperCase()}`;
}

console.log(greet({ name: "Ana" }, "hi")); // Ana: HI
greet(null, "hi"); // throws Error: No user

const assertIsNumber = (value: unknown): asserts value is number => {
  if (typeof value !== "number") throw new TypeError("Not a number");
};

declare const input: unknown;
assertIsNumber(input); // ❌ Assertions require every name in the call target to be declared with an explicit type annotation.

import assert from "node:assert";

function parsePort(raw: string | undefined): number {
  assert(raw, "PORT is not set"); // raw: string after this line
  const port = Number(raw);
  assert(Number.isInteger(port) && port > 0, `Invalid port: ${raw}`);
  return port;
}

console.log(parsePort("8080")); // 8080

A discriminated union (also called a tagged union) is a union of object types where every member has one common property — the discriminant or tag — with a different literal type in each: kind: "circle", kind: "square", and so on. Checking that one property tells TypeScript which member you have, so it narrows the whole object. My notes put it as "1 common property in all of them to differentiate them".

It's the most reliable way to narrow objects. It doesn't depend on keys happening to be different (like in), it doesn't need classes (like instanceof), and it works with plain JSON from an API. The mental model: every envelope has a label printed on the outside, so you read the label instead of guessing from the contents.

The shapes example from my notes:

interface Circle {
  kind: "circle";
  radius: number;
}
interface Square {
  kind: "square";
  sideLength: number;
}
interface Rectangle {
  kind: "rectangle";
  width: number;
  height: number;
}
type Shape = Circle | Square | Rectangle;

function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.sideLength ** 2;
    case "rectangle":
      return shape.width * shape.height;
    default:
      const _exhaustiveCheck: never = shape;
      return _exhaustiveCheck;
  }
}

console.log(getArea({ kind: "circle", radius: 1 })); // 3.141592653589793
console.log(getArea({ kind: "rectangle", width: 2, height: 3 })); // 6

interface LooseShape {
  kind: "circle" | "square";
  radius?: number;
  sideLength?: number;
}

function area(shape: LooseShape): number {
  if (shape.kind === "circle") {
    return Math.PI * shape.radius ** 2; // ❌ 'shape.radius' is possibly 'undefined'.
  }
  return 0;
}

type RequestState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; error: Error };

function render(state: RequestState): string {
  if (state.status === "loading") return "Loading…";
  if (state.status === "error") return `Failed: ${state.error.message}`;
  if (state.status === "success") return state.data.join(", ");
  return "Click to load"; // state: { status: "idle" }
}

console.log(render({ status: "success", data: ["a", "b"] })); // a, b
console.log(render({ status: "idle" })); // Click to load

type RequestState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; error: Error };

function describe(state: RequestState): string {
  const { status } = state;
  if (status === "success") {
    return `${state.data.length} items`; // narrowed via the destructured const
  }

  const isError = state.status === "error";
  if (isError) {
    return state.error.message; // narrowed via the saved condition
  }

  return status;
}

Discriminated unions grow: you add a Triangle to Shape, and every switch over shape.kind now has a case it doesn't handle. Exhaustiveness checking makes the compiler find all of them for you. My notes flag this one as important, and it's a favourite interview follow-up.

The trick uses the fact that narrowing removes a member for each case you handle. After the last case, nothing is left, so the variable's type is never — the empty type. And only never is assignable to never. So if you assign the leftover to a never-typed variable, it compiles only when every case is handled; if one is missing, the leftover isn't empty, and the error names exactly what you forgot.

Add Triangle to the shapes from the previous topic without updating the switch:

interface Circle {
  kind: "circle";
  radius: number;
}
interface Square {
  kind: "square";
  sideLength: number;
}
interface Rectangle {
  kind: "rectangle";
  width: number;
  height: number;
}
interface Triangle {
  kind: "triangle";
  base: number;
  height: number;
}
type Shape = Circle | Square | Rectangle | Triangle;

function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.sideLength ** 2;
    case "rectangle":
      return shape.width * shape.height;
    default:
      const _exhaustiveCheck: never = shape; // ❌ Type 'Triangle' is not assignable to type 'never'.
      return _exhaustiveCheck;
  }
}

interface Circle {
  kind: "circle";
  radius: number;
}
interface Square {
  kind: "square";
  sideLength: number;
}
type Shape = Circle | Square;

function assertNever(value: never): never {
  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);
}

function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.sideLength ** 2;
    default:
      return assertNever(shape);
  }
}

const fromServer = JSON.parse('{"kind":"hexagon","side":2}') as Shape;
getArea(fromServer); // throws Error: Unhandled value: {"kind":"hexagon","side":2}

type Shape = { kind: "circle"; radius: number } | { kind: "square"; sideLength: number };

function describe(shape: Shape): string {
  switch (shape.kind) {
    case "circle":
      return "round";
    case "square":
      return "boxy";
    default:
      shape satisfies never; // with a case missing: "Type '…' does not satisfy the expected type 'never'."
      return "unknown";
  }
}

interface Circle {
  kind: "circle";
  radius: number;
}
interface Square {
  kind: "square";
  sideLength: number;
}
interface Triangle {
  kind: "triangle";
  base: number;
  height: number;
}
type Shape = Circle | Square | Triangle;

function getPerimeter(shape: Shape): number { // ❌ Function lacks ending return statement and return type does not include 'undefined'.
  switch (shape.kind) {
    case "circle":
      return 2 * Math.PI * shape.radius;
    case "square":
      return 4 * shape.sideLength;
  }
}

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; sideLength: number }
  | { kind: "rectangle"; width: number; height: number };

function logShape(shape: Shape): void {
  switch (shape.kind) {
    case "circle":
      console.log("circle");
      break;
    case "square":
      console.log("square");
      break;
  }
}