How to narrow a union type.
Every technique, one page.

// ─── Narrowing string | number | boolean ─────
function format(value: string | number | boolean): string {
if (typeof value === 'string') {
return value.toUpperCase(); // ✅ narrowed to string
}
if (typeof value === 'number') {
return value.toFixed(2); // ✅ narrowed to number
}
// value is boolean here — the only remaining case
return value ? 'yes' : 'no'; // ✅ narrowed to boolean
}

// ─── typeof null gotcha ──────────────────────
function describe(x: string | null): string {
// typeof null === 'object' — typeof can't distinguish null
if (x === null) return 'nothing'; // check null explicitly first
return x; // ✅ narrowed to string
}

// ─── typeof + Array.isArray for arrays ───────
function join(x: string | string[]): string {
// typeof [] === 'object' — typeof says nothing useful here
if (Array.isArray(x)) {
return x.join(', '); // ✅ narrowed to string[]
}
return x; // ✅ narrowed to string
}

// ─── typeof values cheat sheet ───────────────
// typeof 'x' → 'string'
// typeof 1 → 'number'
// typeof true → 'boolean'
// typeof undefined → 'undefined'
// typeof null → 'object' ← gotcha
// typeof {} → 'object'
// typeof [] → 'object'
// typeof () => {} → 'function'
// typeof Symbol() → 'symbol'
// typeof 1n → 'bigint'

console.log(format('hi'), format(3.14), format(true));
console.log(join(['a', 'b']));

// ─── The discriminated union ─────────────────
type Shape =
| { kind: 'circle'; radius: number }
| { kind: 'square'; side: number }
| { kind: 'triangle'; base: number; height: number };

// ─── Switch on the discriminant ──────────────
function area(s: Shape): number {
switch (s.kind) {
case 'circle':
return Math.PI * s.radius ** 2; // ✅ narrowed to circle
case 'square':
return s.side ** 2; // ✅ narrowed to square
case 'triangle':
return (s.base * s.height) / 2; // ✅ narrowed to triangle
default:
// s is never here — exhaustive check
const _exhaustive: never = s;
return _exhaustive;
}
}

// ─── If-else narrows too ─────────────────────
function describe(s: Shape): string {
if (s.kind === 'circle') return Circle r=${s.radius}Square s=${s.side};
return Triangle b=${s.base}`; // ✅ narrowed to triangle
}

// ─── API response example ────────────────────
type ApiResult =
| { status: 'loading' }
| { status: 'success'; data: T }
| { status: 'error'; message: string };

function render(r: ApiResult): string {
switch (r.status) {
case 'loading': return 'Loading…';
case 'success': return String(r.data); // ✅ r.data exists
case 'error': return r.message; // ✅ r.message exists
}
}

console.log(area({ kind: 'circle', radius: 2 }));
console.log(describe({ kind: 'square', side: 3 }));
console.log(render({ status: 'success', data: 42 }));

// ─── in — narrow by property presence ──────
interface Bird { fly(): void; layEggs(): void }
interface Fish { swim(): void; layEggs(): void }

function move(animal: Bird | Fish): string {
if ('fly' in animal) {
animal.fly(); // ✅ narrowed to Bird
return 'flew';
}
animal.swim(); // ✅ narrowed to Fish
return 'swam';
}

// ─── instanceof — narrow class instances ─────
class Cat { meow() { return 'meow'; } }
class Dog { bark() { return 'woof'; } }

function speak(pet: Cat | Dog): string {
if (pet instanceof Cat) {
return pet.meow(); // ✅ narrowed to Cat
}
return pet.bark(); // ✅ narrowed to Dog
}

// ─── instanceof works with built-ins too ─────
function describeError(err: Error | TypeError | RangeError): string {
if (err instanceof TypeError) return 'type error';
if (err instanceof RangeError) return 'range error';
return 'error';
}

// ─── Custom type guard — narrow anything ─────
interface User { id: string; name: string }

function isUser(x: unknown): x is User {
return (
typeof x === 'object' &&
x !== null &&
'id' in x &&
'name' in x &&
typeof (x as User).id === 'string' &&
typeof (x as User).name === 'string'
);
}

function greet(x: unknown): string {
if (isUser(x)) {
return Hello, ${x.name}`; // ✅ narrowed to User
}
return 'Hello, stranger';
}

// ─── Equality with literals (without a switch) ─
type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';

function isSafe(m: Method): boolean {
if (m === 'GET') return true; // narrowed to 'GET'
if (m === 'DELETE') return false;
return false; // narrowed to 'POST' | 'PUT'
}

console.log(move({ fly() {}, layEggs() {} }));
console.log(speak(new Cat()), speak(new Dog()));
console.log(greet({ id: '1', name: 'Alice' }));
console.log(isSafe('GET'));