Command Palette

Search for a command to run...

Hectal
Phase 4Beginner5 of 18 in TypeScript

Unions, Literals and Narrowing

Values that can be one of several types, exact-value types, and how TypeScript follows your if-statements to know which one you hold. Tagged unions, exhaustive checks and custom guards.

Real programs are full of values that can be one of several things: an id that is a number or a text, a request that is loading, done or failed, a shape that is a circle or a square. This phase teaches the tool for that: the union type, written A | B.

A union is only useful if you can find out which one you are holding. TypeScript does this by reading your if statements, switch statements and checks like typeof and instanceof, and narrowing the type inside each branch. You will learn every kind of narrowing, then the most useful pattern in all of TypeScript: the discriminated union, a union with a shared tag, which the compiler can check for completeness.

Every example is checked by the real TypeScript compiler. Predict the type before you look at the Types panel, then change the code and see how narrowing follows you.

0/7 · 0%
7 topics ~3 h 22 code blocks & diagrams
Start with the first topic
1
4.1

Union Types

A union type, written A | B, says a value is one of several types. TypeScript only lets you do what is safe for every member, until you check which one you really have.

26 min 3 code practice

2
4.2

Literal Types

A literal type is a type with exactly one value, like "up" or 42. Joined in a union, literals describe a small fixed set of allowed values, and as const keeps values from widening back to string or number.

26 min 3 code practice

3
4.3

Narrowing with typeof, Truthiness and Equality

Narrowing means TypeScript reads your if statements and shrinks a union to the member that must be true inside each branch. typeof, truthiness and === are the three everyday checks.

27 min 3 code practice

4
4.4

Narrowing with in and instanceof

When a union holds objects, typeof isn't enough. The in operator asks "does this object have this property?" and instanceof asks "was this object made by this class?". TypeScript narrows on both.

26 min 3 code practice

5
4.5

Discriminated Unions

A discriminated union is a union of object types that all share one property with a different literal value in each (the tag). Checking the tag tells TypeScript exactly which object you have, so every branch gets precisely the fields that exist.

26 min 3 code practice

6
4.6

Exhaustiveness Checking with never

never is the type with no values. If you handle every member of a union and then try to assign the leftover to never, it works; if you forgot a member, the compiler reports exactly which one. Adding a new variant then points you to every place that needs updating.

26 min 3 code practice

7
4.7

Custom Type Guards and Assertion Functions

When the built-in checks aren't enough, you write your own: a function returning x is T tells TypeScript what a true result means, and asserts x is T does the same for functions that throw. The compiler trusts you, so they must tell the truth.

28 min 4 code practice

Practise this phase

Hands-on exercises: write the code, see your page live, and press Check to have it tested automatically.

1

Only These Directions

The function move accepts any text, so a typo like "lef" gets through. Change the type Direction so only "up", "down", "left" and "right" are allowed.

Beginner
2

Narrow with typeof

describe takes a string | number | null. For text it returns the text in capital letters, for a number it returns the number with two decimals (toFixed(2)), and for null it returns "nothing".

Beginner
3

Tag the Shapes

A shape is either a circle with a radius, or a rectangle with width and height. Define type Shape as a discriminated union with a kind tag ("circle" and "rect"), then write area(shape: Shape): number with a switch.

Beginner
4

Never Forget a Case

A new shape, the triangle, was added to Shape, but area doesn't handle it, and assertNever complains. Read the error: it names the missing type.

Intermediate
5

Write a Type Guard

isUser checks that unknown data is a User (an object with a text name and a number age), but its return type is plain boolean, so TypeScript doesn't narrow. Change the return type to a type predicate.

Intermediate
6

Model a Request

Build the state of a data request. Define type Request as a discriminated union with status tags: "loading", "success" (with data: string[]) and "error" (with message: string).

Intermediate