If it fits
the shape.

TypeScript is JavaScript with a static type layer checked at compile time and then erased — you get bug-catching and tooling (autocomplete, refactors) at your desk, and plain JavaScript with zero type overhead at runtime. But the thing that defines how it feels is that its type system is structural, not nominal. Compatibility is decided by an object's shape — the properties it has and their types — not by any name or declared inheritance.

This is duck typing made static: "if it walks like a duck and quacks like a duck, it's a duck." An object is compatible with a type if it has what that type asks for, full stop — it never needed to be declared as implementing anything. Define an interface today, and objects you wrote yesterday satisfy it automatically, as long as their shape matches. That single principle — match by shape, not by name — is the key that unlocks TypeScript's behavior. Nearly every question of the form "why is this assignable / why isn't it?" is answered by comparing two shapes, which is exactly what the next section formalizes.

Here's the whole rule in one sentence: a source value is assignable to a target type if, for every property the target requires, the source has that property with a matching type. That's it. Two consequences follow, and they explain most day-to-day TypeScript.

The first consequence trips people up: an object with more properties than the target is still assignable. A function that wants a { x, y } point happily accepts a { x, y, z } — it only ever reads x and y, so the extra z is harmless. A wider object can always stand in where a narrower one is expected. The second is the reverse: an object missing a required property is rejected, because the code might read the property that isn't there. This asymmetry — extra is fine, missing is not — falls directly out of "does the target get everything it asks for?" Once you internalize that one check, TypeScript's assignability stops being mysterious.

If extra properties are always fine, why does TypeScript sometimes complain that 'colour' does not exist in type '{ color: string }'? Because of a deliberate exception: the excess-property check. When you assign a fresh object literal directly to a typed target, TypeScript additionally flags any property the target never declared.

The reason is purely practical: it catches typos. If you write { color: "red", colour: "blue" } against a type that only has color, the structural rule alone would happily accept it (it has color; the extra colour is "just extra"). But almost certainly you meant color and misspelled it, so silently accepting it would hide a bug. The excess-property check is TypeScript deciding that for a fresh literal — where the extra property serves no purpose and probably signals a mistake — it's worth being strict. Crucially, it applies only to object literals assigned directly; the moment the value comes from a variable, the normal "wider is fine" rule takes over again. So the model is: shape-based assignability everywhere, plus one typo-guard tightening for literals. Knowing this explains the otherwise-baffling case where extracting an object to a variable makes a type error disappear.

Assignability is a simple predicate over the target's required properties — each must exist in the source with a matching type:

A wider source (extra props) still satisfies this; a source missing any required p, or with a wrong type at p, fails. Extra is fine, missing is not.

The object-literal check adds one clause — no property outside the target's declared set — to catch typos:

For variables, only the first clause applies (wider is fine); for fresh literals, both — so a misspelled property is rejected. The runnable version below implements assignability, missing/excess props, and the literal check.

Structural typing is a genuine design choice with trade-offs, best seen against its opposite:

TypeScript chose structural because it's layering types onto JavaScript, a language built around ad-hoc objects and duck typing — nominal typing would fight the grain of the language. The upside is low ceremony: you define an interface describing a shape, and every value that already has that shape conforms, no edits required. The occasional downside is that two conceptually different types that happen to share a shape (say, a Meters and a Feet both being just number) are freely interchangeable, which can hide a units bug — for those cases you reach for tricks like branded types to simulate nominal typing. But 95% of the time, "match by shape" is exactly what you want, and it's why TypeScript feels lightweight despite adding a whole type system.

The first is the confusing excess-property surprise. You assign an object literal with one extra field and get an error; you extract the exact same object to a variable first and the error vanishes. This looks like a bug in TypeScript but it's the excess-property check working as designed — strict on fresh literals (to catch typos), relaxed on variables (where "wider is fine" applies). Knowing the rule turns a baffling inconsistency into an expected one.

Two bigger ones. Trusting any: typing something as any switches off checking for that value entirely — it's assignable to and from everything, silently — so a stray any can let a whole class of bugs slip through the type system you added precisely to catch them. Prefer unknown (which forces you to narrow before use) and treat any as a last resort. And forgetting types are erased: TypeScript's types vanish at runtime, so they can't validate data that arrives from outside your program — an API response, user input, a JSON parse. Annotating a fetch result as User is a promise, not a check; if the server sends something else, TypeScript won't know. Validate external data at the boundary (with a runtime schema validator) and let types take over inside. The whole handbook rests on one idea worth carrying everywhere: TypeScript matches by shape, not name — a value fits a type when it has what the type asks for — and every surprising assignability result is that rule, plus the literal typo-guard, plus the fact that types are a compile-time story that ends before your program runs.