Structural typing: shape is the only thing the checker compares

Names don’t matter, members do

Why does this matter? Because the moment you understand that TypeScript checks shape, not name, you stop writing unnecessary casts and start designing types that actually compose across module boundaries.

Most older typed languages are nominal: a value of type Point is only a Point if it was declared as one. TypeScript is structural (often called “duck typing”: if it walks like a duck…). The checker compares the set of members the target requires against what the source provides.

interface Point { x: number; y: number }
interface Vector2D { x: number; y: number }

function length(p: Point): number {
  return Math.hypot(p.x, p.y);
}

const v: Vector2D = { x: 3, y: 4 };
length(v); // ✅ compiles — Vector2D has x and y, so it IS a Point's shape
//     ^? (parameter) p: Point  — but a Vector2D satisfies it

Point and Vector2D were declared independently, share no extends, live in different files — and are still interchangeable. There is no Point brand stamped on the value at runtime; TypeScript erases types entirely. The only question the checker asks is: does the source object have at least the members the target demands, at compatible types?

Extra members are fine in this direction — a source can have more than the target needs:

const labelled = { x: 1, y: 2, label: "origin" };
length(labelled); // ✅ extra `label` is ignored — it still has x and y

This is the whole model. A type is a constraint on shape, not a club you have to be admitted to.

The one place it feels nominal: excess-property checks

If structural typing always ignored extra properties, this would compile — and it doesn’t:

interface Options { width: number; height: number }

function configure(o: Options) { /* ... */ }

configure({ width: 100, height: 50, widht: 10 });
// Error: Object literal may only specify known properties,
//        and 'widht' does not exist in type 'Options'. Did you mean 'width'?

That widht typo would otherwise be silently swallowed as a harmless extra property. To catch exactly this class of bug, TypeScript runs an excess-property check on fresh object literals assigned directly to a typed target. A literal is “fresh” the moment it’s written; assigning it somewhere typed triggers the stricter check.

The check evaporates the instant the literal passes through a variable, because the variable’s inferred type no longer carries “freshness”:

const opts = { width: 100, height: 50, widht: 10 };
configure(opts); // ✅ no error — `opts` is a widened variable, not a fresh literal
//        ^? widht: number is just an extra, structurally-ignored member

You can opt into extra properties explicitly with an index signature ([key: string]: unknown) or by casting, but the typo-catching default is usually what you want.

Functions are structural too

Assignability extends to functions — and here it gets subtle (full variance rules are unit 03). A function is assignable to another if it can be called wherever the target is expected. The key surprise: a function that ignores parameters fits where one taking parameters is wanted.

type Handler = (event: { type: string; x: number }) => void;

const log: Handler = () => console.log("clicked"); // ✅ ignoring the arg is fine
const partial: Handler = (e: { type: string }) => {}; // ✅ asks for less than it's given

A handler that needs fewer properties than the caller supplies is safe — the caller passes a richer object, the handler reads a subset. Foreshadow: this “needs less, gets more” direction is the heart of variance, which we unpack with generics in unit 03.

Recovering nominal safety on purpose: branded types

Structural typing has a real cost: UserId and OrderId, both string, are freely interchangeable — so you can pass an order id where a user id was expected and the checker stays silent.

type UserId = string;
type OrderId = string;

function loadUser(id: UserId) { /* ... */ }
const order: OrderId = "ord_42";
loadUser(order); // ✅ compiles — but this is a real bug

Teams recover nominal safety with a branded type: intersect the primitive with a phantom marker that exists only in the type system.

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

function asUserId(s: string): UserId {
  return s as UserId; // the brand is applied once, at a trusted boundary
}

function loadUser(id: UserId) { /* ... */ }

const order = "ord_42" as OrderId;
loadUser(order);
// Error: Argument of type 'OrderId' is not assignable to parameter of type 'UserId'.
//   Type 'OrderId' is not assignable to type '{ readonly __brand: "UserId"; }'.

The __brand field never exists at runtime (you only ever cast into it), but structurally UserId and OrderId now have different __brand literal types, so the checker rejects mixing them. Teams reach for this on id types, money/units, validated-vs-raw strings — anywhere a plain primitive carries dangerous semantics that structural typing would happily ignore.