Structural Type Compatibility

What it is and why to use it

TypeScript usually compares object types by their members rather than by a declared type name. A value can satisfy a smaller interface when it contains the required compatible fields. This structural approach fits JavaScript’s flexible object composition and makes small reusable contracts practical.

Common mistakes and limitations

Fresh object literals receive additional excess-property checking. Private and protected class members also impose compatibility rules beyond a simple public-field comparison. Structural assignment does not strip extra properties or validate untrusted data.

Run this example

Use TypeScript 5.8 or later with strict checking and an ES2022 target. Save each complete example independently as example.ts, compile it, then run the generated JavaScript with a compatible Node.js installation. Compiler-only options below affect checking; they do not add runtime validation.

Terminal — compile and run

npx tsc example.ts --strict --target ES2022 --module commonjs
node example.js

• interfaces
• excess property checks

Syntax

type Named = { name: string };

Examples

type Named = { name: string };
function welcome(person: Named): string { return "Hello, " + person.name; }
const learner = { name: "John", score: 87 };
console.log(welcome(learner));

Best practices

• Fresh object literals receive additional excess-property checking. Private and protected class members also impose compatibility rules beyond a simple public-field comparison. Structural assignment does not strip extra properties or validate untrusted data.
• Keep external-input validation separate from compile-time type descriptions.

Runtime & versions

Compiled to JavaScript. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

Related TypeScript documentation

Specifications & further reading

• Official TypeScript documentation