TypeScript Reference ยท Concepts and Comparisons
Structural typing in TypeScript
Learn how TypeScript decides compatibility by shape, not by name: object types, classes, extra properties, and when structural typing surprises you.
TypeScript decides whether one type fits another by comparing their members, not their names. If a value has every property and method the target type asks for, with compatible types, it is accepted. It does not matter which interface, class or alias the value was "declared" as.
This is called structural typing, and it is the reason TypeScript describes JavaScript code well. JavaScript has no declared types at run time; objects are bags of properties, and functions care only about what they can read from those bags.
interface Point { x: number; y: number } const p = { x: 1, y: 2, label: "origin" }; const q: Point = p; // fine: p has x and y
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
How the comparison works
- Required members must exist. Every non-optional property of the target must be present in the source with an assignable type.
- Extra members are fine when the source is not a fresh object literal. A fresh literal assigned directly gets the extra property check, a separate rule that catches typos.
- Methods and functions are compared by their parameter and return types, not by their names.
- Classes are compared like objects. Instances of two unrelated classes with the same public members are interchangeable.
- Private and protected members break the tie. If a class has a
privateor#privatemember, only instances from that same declaration are compatible. - Generics are compared by their arguments' structure. Two differently named generic types with the same expanded shape are the same for assignment.
Usage notes
- Structural typing is not unsound by itself; it just means that intent is not recorded. Two IDs that are both
stringare interchangeable, so mix-ups compile. - Use branded types when different kinds of the same primitive must not mix. See Branded types.
- A private field turns a class nominal-like, which is a cheap way to forbid structural lookalikes.
- Object literals are checked more strictly than variables holding the same object. See excess property checks.
- Weak types (all properties optional) require at least one matching property. See weak type detection.
- Error messages about assignability point to the first missing or incompatible member, which is the quickest way to learn what the compiler compared.