Unions and narrowing
A union type such as string | number says a value can be one of several types. Follow a seven-line function as tsc refuses a method that only strings have, then watch a typeof check split the union in two: string inside the if, number after it. Finally run the program, see "ab" and 7 take the same two paths and print AB 7.0, and learn why the check survives when the types are erased.
5 quick questions
Pick an answer to see why. Your score saves with your progress.
01Which values can you pass to a parameter typed id: string | number?
A union means "one of these types". show("ab") and show(7) are both allowed; show(true) is not.
02Why is id.toUpperCase() an error when id is string | number and nothing has been checked?
tsc reports: Property 'toUpperCase' does not exist on type 'string | number'. Property 'toUpperCase' does not exist on type 'number'. It works for string, but not for number, so it is not safe on the union.
03Inside if (typeof id === "string") { ... }, what type does tsc give id?
The typeof check is a type guard. In the branch where it is true, tsc narrows the union to string, so string methods such as toUpperCase are allowed.
04The if branch returns. What type does id have on the line after the if?
Every string has already returned inside the if, so the code after it only runs for numbers. tsc's control flow analysis removes string and leaves number.
05Why does narrowing use checks like typeof instead of reading the type annotation while the program runs?
tsc removes : string | number from the JavaScript it writes. The typeof check is ordinary JavaScript, so it still runs and still picks the right branch.
Glossary
- Union type
- A type made of several types joined with |, such as string | number. A value of it can be any one of them.
- Member
- One of the types inside a union. string and number are the members of string | number.
- typeof
- A JavaScript operator that gives a value's kind as text while the program runs, such as "string" or "number".
- Type guard
- A check, such as typeof id === "string", that tsc uses to work out a more exact type inside a branch.
- Narrowing
- When tsc works out a more exact type than the declared one, for example string instead of string | number, from the checks around the code.
- Control flow analysis
- How tsc follows ifs, returns and other branches to know which types can reach each line.
- Type erasure
- Removing the types when tsc writes JavaScript. The running program never sees them.
Notes and sources
- tsc shows this union as string | number. Order does not matter in a union: number | string is the same type.
- The program is real and runnable: tsc 5.9 compiles it with no errors and node show.js prints AB 7.0.
- typeof can give "string", "number", "bigint", "boolean", "symbol", "undefined", "object" or "function". Note typeof null is "object".
- Working out the type from ifs, returns and other checks is called control flow analysis. It also narrows after ===, in, instanceof and Array.isArray checks.
- TypeScript Handbook: Everyday Types, Union Types
- TypeScript Handbook: Narrowing
- TypeScript Handbook: Narrowing, typeof type guards
- TypeScript Handbook: Narrowing, control flow analysis
- TypeScript Handbook: The Basics, Erased Types
- MDN: typeof
- MDN: String.prototype.toUpperCase()
- MDN: Number.prototype.toFixed()
Quiz Unlocks after the last step.