Structural typing

Shape, not name

1interface Named {2  name: string3}4 5class Person {6  name: string7  age: number8  constructor(name: string, age: number) {9    this.name = name10    this.age = age11  }12}13 14const fromClass: Named = new Person("Ada", 36) // fine: it has a name15const fromLiteral: Person = { name: "Lin", age: 30 } // fine: same shape as Person

Person never mentions Named, and the object literal was never created with new Person, yet both assignments compile. There is no implements needed, because types are erased and the checker can only compare structure. One consequence: fromLiteral instanceof Person is false at runtime, even though the checker accepted it as a Person. Classes become nominal only when they have private or #private members, which a plain object cannot copy.

The excess property check

1type Point = { x: number; y: number }2 3const p3 = { x: 1, y: 2, z: 3 }4const ok: Point = p3 // fine: extra members are allowed5 6const typo: Point = { x: 1, y: 2, zz: 3 } // Error: Object literal may only specify known properties

Structurally both are the same assignment. The difference is freshness: an object literal written directly where a Point is expected cannot be used for anything else, so an unknown property in it is almost certainly a mistake. Once the object is in a variable, it may be used elsewhere with its extra members, so the check does not apply. This is a targeted lint, not a guarantee that values have no extra properties.

When the shape is not enough

Ids are the classic case. A user id and an order id are both strings, and a function that takes (userId: string, orderId: string) will happily accept them in the wrong order. A brand adds a property that exists only in the type:

1type UserId = string & { readonly __brand: "UserId" }2type OrderId = string & { readonly __brand: "OrderId" }3 4const asUserId = (raw: string) => raw as UserId5 6function loadOrder(user: UserId, order: OrderId) {7  return `${user}/${order}`8}9 10const u = asUserId("u_1")11const o = "o_9" as OrderId12loadOrder(o, u) // Error: OrderId is not assignable to UserId

At runtime they are still plain strings. The brand only exists for the checker, so create branded values in one place (the function that parses or validates them) and let the types carry the guarantee from there.

Functions are compared structurally too

A function that takes fewer parameters can be passed where one taking more is expected, which is why [1, 2].forEach((n) => ...) works even though forEach passes three arguments. Under strictFunctionTypes, parameter types are checked so that a callback cannot demand a narrower argument than it will be given.