You spend an entire afternoon adding types to your project. Every variable has an interface, every function has explicit return types, and your editor is completely free of red squiggly lines. You feel invincible.
Wait. How? You wrote TypeScript! Wasn't TypeScript supposed to make this exact error impossible?
If this has happened to you, welcome to the club. Almost every developer goes through a phase where TypeScript feels like an aggressive back-seat driver that yells at you constantly, yet somehow lets actual bugs slip right into production.
The problem is rarely your code. The problem is almost always your mental model.
Most beginners treat TypeScript like Java or C# bolted onto JavaScript. But TypeScript does not work like any traditional language you have used before. Today, we are going to look at how TypeScript actually thinks, why your types disappear before your app even boots, and how to stop fighting the compiler once and for all. The Phantom Type System: Type Erasure
When you run tsc (the TypeScript compiler), it does two completely separate jobs: It checks your code for type errors. It completely strips away every single type, interface, and type annotation, spitting out plain JavaScript.
Look closely at what happens after compilation. Those beautiful interfaces you designed? Gone. The custom generic constraints? Vanished.
At runtime in Node.js or in Chrome's V8 engine, your computer is running raw JavaScript. The runtime has zero memory of what types you wrote.
Because beginners think types exist at runtime, they often write code like this:
JavaScript's instanceof operator checks prototypes of actual objects in memory. But User was erased during compilation! It left no trace in JavaScript, so instanceof User makes zero sense to the runtime.
TypeScript trusted your annotation at compile time. But TypeScript cannot monitor the network pipe. If the backend returns null or { error: 500 }, your code will crash at runtime.
Rule of thumb: TypeScript validates what you write, not what the outside world sends you. For external boundaries (APIs, localStorage, user input), always use runtime validators like Zod or custom type guard functions. Shape Over Name: Structural Typing
In traditional languages, type systems are nominal. A type's identity is determined by its explicit name or declaration.
In TypeScript, the type system is structural (often called compile-time duck typing). A type's identity is determined exclusively by its internal shape.
In Java or C#, assigning a Point2D to a Vector2D without an explicit cast would throw a compile-time error. They have different names, so they are different types.
In TypeScript, the compiler checks the blueprint: Does point have an x of type number? Yes. Does point have a y of type number? Yes. Done. They are completely interchangeable.
Why does Case A fail while Case B succeeds when both pass the exact same properties?
Here is why: TypeScript enforces Excess Property Checks specifically on fresh object literals.