Common pitfalls: traps that compile clean and bite later

The roundup table

Each row is a trap that passes the compiler. Read it as: symptom, why it slips through, and the reflex fix.

Branding: defeating structural typing on purpose

Unit 01 taught that TypeScript is structural — two types with the same shape are interchangeable. Usually a feature; here a hazard. type UserId = string and type OrderId = string are the same type, so passing one where the other is wanted compiles. Branding adds a phantom property that exists only in the type:

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function getUser(id: UserId) { /* ... */ }
const order = "ord_1" as OrderId;

// getUser(order); // Error: 'OrderId' is not assignable to 'UserId'
//   the __brand discriminates them even though both are string at runtime
const user = "usr_1" as UserId;
getUser(user); // ok

The __brand never exists at runtime (it’s string underneath), but the type now distinguishes the two, so a mixed-up ID is a compile error. This is the standard fix for “structural typing let the wrong primitive through.”

Array covariance: the canonical unsoundness

TypeScript deliberately treats arrays as covariant — Dog[] is assignable to Animal[] — for ergonomics. But arrays are mutable, which makes this unsound:

const dogs: Dog[] = [new Dog()];
const animals: Animal[] = dogs; // allowed — covariance
animals.push(new Cat());        // compiles! Animal[] accepts a Cat
dogs[1].bark();                 // runtime crash — it's a Cat, no bark()

The compiler accepted every line, yet dogs now contains a Cat. The fix in API design: accept readonly Animal[] when you only read, so a caller can’t smuggle a Cat into someone’s Dog[].

Mutation invalidates narrowing

Narrowing (unit 02) is only valid until the value can change. A mutable binding or property narrowed in an if can be reset by any intervening call the compiler can’t see through:

function f(box: { v: string | null }) {
  if (box.v !== null) {
    sideEffect();        // could set box.v = null — compiler assumes it didn't
    box.v.toUpperCase(); // ^? string  — but might throw at runtime
  }
}

The compiler narrows box.v to string inside the if and keeps that assumption across sideEffect(), because it can’t prove the call left box.v alone. The fix: copy to a const local immediately after the check (const v = box.v;) so the narrowed value can’t be mutated out from under you.