Discriminated union narrowing in Typescript - Step-by-Step Execution

Concept Flow - Discriminated union narrowing

Start with union type variable

↓

Check discriminant property

↓

Match case A

↓

Use properties

↓

End

We check a special property (discriminant) to know which type we have, then safely use its specific properties.

Execution Sample

Typescript

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

function area(shape: Shape) {
  if (shape.kind === "circle") {
    return Math.PI * shape.radius ** 2;
  } else {
    return shape.size ** 2;
  }
}

Calculates area by checking the 'kind' property to know if shape is circle or square.

Execution Table

Step	Condition	Condition Result	Narrowed Type	Action	Output
1	shape.kind === "circle"	true	{ kind: "circle"; radius: number }	Calculate circle area	28.274333882308138
2	shape.kind === "circle"	false	{ kind: "square"; size: number }	Calculate square area	16
3	No more cases	-	-	Return result	-

💡 All union cases handled by checking discriminant 'kind'; function returns area.

Variable Tracker

Variable	Start	After Step 1	After Step 2	Final
shape	{ kind: "circle", radius: 3 }	{ kind: "circle", radius: 3 }	-	-
shape	{ kind: "square", size: 4 }	-	{ kind: "square", size: 4 }	-
output	-	28.274333882308138	16	-

Key Moments - 2 Insights

Why can we access 'radius' only after checking shape.kind === "circle"?

Because the discriminated union narrows the type to the circle variant, so TypeScript knows 'radius' exists only then (see execution_table step 1).

What happens if we forget to check the discriminant property?

TypeScript won't know which type it is, so accessing specific properties like 'radius' or 'size' will cause errors or require unsafe casts.

Visual Quiz - 3 Questions

Look at the execution table, what is the narrowed type when shape.kind === "circle" is true?

A { kind: "square"; size: number }

B { kind: "circle"; radius: number }

C union of both types

D any

💡 Hint

Check the 'Narrowed Type' column in execution_table row 1.

At which step does the condition shape.kind === "circle" become false?

A Step 1

B Step 3

C Step 2

D Never

💡 Hint

Look at the 'Condition Result' column in execution_table row 2.

If we add a new shape kind 'triangle', what must we do to keep narrowing working?

A Add a new condition checking shape.kind === "triangle"

B Remove existing conditions

C Use type assertions everywhere

D Ignore it, TypeScript handles automatically

💡 Hint

Discriminated union narrowing requires checking each discriminant value explicitly (see concept_flow).

Concept Snapshot

Discriminated union narrowing:
- Use a common 'discriminant' property (like 'kind')
- Check this property in conditions
- TypeScript narrows type inside each branch
- Access only properties valid for that narrowed type
- Ensures safe, clear code for union types

Full Transcript

Discriminated union narrowing means using a special property common to all types in a union to tell which exact type we have. In the example, the 'kind' property tells if the shape is a circle or square. We check 'shape.kind === "circle"' to narrow the type to circle, so we can safely use 'radius'. If false, we know it's a square and use 'size'. This way, TypeScript helps us avoid mistakes by knowing exactly which properties exist at each step.