Unions & narrowing.
Model "one of these" safely.

// ─── Basic unions ────────────────────────────
type ID = string | number;

const a: ID = 'u_123'; // ✅ string is allowed
const b: ID = 456; // ✅ number is allowed
// const c: ID = true; // ❌ boolean is not in the union

// ─── Literal unions — a fixed set of values ──
type Status = 'idle' | 'loading' | 'success' | 'error';

let s: Status = 'loading'; // ✅
// s = 'done'; // ❌ 'done' not in the union
// s = 'Loading'; // ❌ case matters — 'Loading' ≠ 'loading'

// ─── Union with null/undefined ───────────────
type MaybeUser = User | null | undefined;
interface User { name: string }

function getName(u: MaybeUser): string {
// return u.name; // ❌ u might be null/undefined
if (!u) return '(no user)'; // ✅ narrowed
return u.name;
}

// ─── Union of object shapes ──────────────────
type Shape =
| { kind: 'circle'; radius: number }
| { kind: 'square'; side: number };

function area(s: Shape): number {
switch (s.kind) {
case 'circle': return Math.PI * s.radius ** 2;
case 'square': return s.side ** 2;
}
}

console.log(getName({ name: 'Alice' }));
console.log(getName(null));
console.log(area({ kind: 'circle', radius: 2 }));

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

// ─── typeof for null (gotcha) ─────────────────
function describe(x: string | null): string {
if (x === null) return 'nothing'; // ✅ must check null explicitly
if (typeof x === 'string') return "${x}"`;
return '';
}

// ─── instanceof narrows 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
}

// ─── Array.isArray ───────────────────────────
function join(x: string | string[]): string {
if (Array.isArray(x)) {
return x.join(', '); // ✅ narrowed to string[]
}
return x; // ✅ narrowed to string
}

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

// ─── The in operator narrows by shape ──────
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';
}

// ─── Truthiness narrows null/undefined ────────
function greet(name?: string): string {
if (!name) {
return 'Hello, anonymous';
}
// name is string here — null and undefined filtered out
return Hello, ${name}`;
}

// ─── Careful: truthiness also filters "" and 0 ─
function badGreet(name?: string): string {
if (!name) return 'anonymous';
// ⚠️ Empty string '' also returns 'anonymous' — probably not intended
return Hello,${name}`;
}

// ─── Equality with literals narrows too ───────
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';

function isSafe(m: HttpMethod): boolean {
if (m === 'GET') return true; // narrowed to 'GET'
if (m === 'POST' || m === 'PUT') return false;
// m is 'DELETE' here — the only remaining case
return false;
}

// ─── Early-return pattern (very common) ───────
function process(user: User | null): string {
if (!user) return '(guest)'; // early return narrows for the rest
return user.name.toUpperCase();
}

console.log(move({ fly() {}, layEggs() {} }));
console.log(greet('Alice'), greet());
console.log(isSafe('GET'), isSafe('DELETE'));

// ─── The discriminated union ──────────────────
interface User { id: string; name: string }

type Result =
| { status: 'loading' }
| { status: 'success'; data: User }
| { status: 'error'; message: string };

function render(r: Result): string {
switch (r.status) {
case 'loading':
return 'Loading...';
case 'success':
return Hello, ${r.data.name}Error: ${r.message}; // ✅ r.message available
}
}

// ─── The compiler enforces it ─────────────────
function check(r: Result): string {
if (r.status === 'success') {
return r.data.name; // ✅ narrowed to success
// return r.message; // ❌ 'message' doesn't exist on success
}
if (r.status === 'error') {
return r.message; // ✅ narrowed to error
}
return 'loading'; // ✅ narrowed to loading
}

// ─── The pattern models state machines ───────
type FormState =
| { status: 'idle' }
| { status: 'submitting'; startedAt: Date }
| { status: 'success'; id: string }
| { status: 'error'; error: Error };

function describeForm(f: FormState): string {
switch (f.status) {
case 'idle': return 'Ready';
case 'submitting': return Submitting since ${f.startedAt.toISOString()}Saved as ${f.id};
case 'error': return Failed: ${f.error.message}`;
}
}

console.log(render({ status: 'success', data: { id: '1', name: 'Alice' } }));
console.log(render({ status: 'error', message: 'Not found' }));
console.log(render({ status: 'loading' }));

// ─── A type guard: value is User ─────────────
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'
);
}

// ─── Used in an if, it narrows ───────────────
function greet(x: unknown): string {
if (isUser(x)) {
return Hello, ${x.name}`; // ✅ x is User here
}
return 'Hello, stranger';
}

// ─── Generic guard for arrays ────────────────
function isArrayOf(
arr: unknown,
guard: (item: unknown) => item is T
): arr is T[] {
return Array.isArray(arr) && arr.every(guard);
}

const data: unknown = [
{ id: '1', name: 'Alice' },
{ id: '2', name: 'Bob' }
];

if (isArrayOf(data, isUser)) {
// data is User[] here
data.forEach(u => console.log(u.name));
}

// ─── Validating API responses ────────────────
async function fetchUser(id: string): Promise {
const res = await fetch(/api/users/${id}`);
const json: unknown = await res.json(); // unknown, not any
if (!isUser(json)) {
throw new Error('Invalid user response');
}
return json; // ✅ validated and narrowed
}

console.log(greet({ id: '1', name: 'Alice' }));
console.log(greet('not a user'));
console.log(greet(null));

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

function area(s: Shape): number {
switch (s.kind) {
case 'circle':
return Math.PI * s.radius ** 2;
case 'square':
return s.side ** 2;
case 'triangle':
return (s.base * s.height) / 2;
default:
// s is never here — every case was handled
const _exhaustive: never = s;
return _exhaustive;
}
}

// ─── If you add a new case... ─────────────────
type Shape2 =
| { kind: 'circle'; radius: number }
| { kind: 'square'; side: number }
| { kind: 'triangle'; base: number; height: number }
| { kind: 'rectangle'; w: number; h: number }; // new!

function area2(s: Shape2): number {
switch (s.kind) {
case 'circle': return Math.PI * s.radius ** 2;
case 'square': return s.side ** 2;
case 'triangle': return (s.base * s.height) / 2;
// case 'rectangle': return s.w * s.h; // ← forgot this one!
default:
// ❌ Type 'Shape2' is not assignable to type 'never'.
// Type '{ kind: "rectangle"; ... }' is not assignable
const _exhaustive: never = s;
return _exhaustive;
}
}

// ─── A reusable helper ────────────────────────
function assertNever(x: never): never {
throw new Error(Unexpected value: ${x}`);
}

console.log(area({ kind: 'circle', radius: 1 }));
console.log(area({ kind: 'square', side: 3 }));