Structural Typing, Interfaces and Assignability

Key points

1. 1

   A value is assignable when it has at least the target's required members with compatible types; extra members are fine and class names do not matter.

2. 2

   Excess property checks apply only to fresh object literals checked directly against a type: assignments, annotated returns, array elements and nested literals. Variables, assertions and spreads bypass them.

3. 3

   Interfaces merge across declarations and give clearer errors; type aliases can name unions, tuples and computed types but cannot be reopened. Only object type aliases get an implicit index signature.

4. 4

   readonly T[] is not assignable to T[], but property-level readonly is ignored by assignability, so the same object can be mutated through another alias.

5. 5

   Under strictFunctionTypes, function-typed properties check parameters contravariantly, while method syntax stays bivariant; arrays are covariant, which is unsound for writes.

6. 6

   private, protected and #private members make class compatibility nominal for those members; branded types (string & { __brand: "X" }) fake nominal typing for primitives.

7. 7

   {} accepts everything except null and undefined; unknown accepts everything but is assignable only to unknown and any; any is assignable to everything except never.

Read the source

• Type Compatibility
• Object Types (excess property checks, readonly, index signatures)
• Declaration Merging