Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Classes, Enums and Decorators

Structural typing of TypeScript classes

Reference for structural typing of TypeScript classes: why two unrelated classes with the same shape are interchangeable, and how private members and brands change it.

TypeScript decides whether one type fits another by comparing shapes, not names. This applies to classes too. If class A has every public member that class B requires, with compatible types, then an A can be used where a B is expected. No extends or implements is needed.

This is different from languages such as Java or C#, where class identity matters (nominal typing). It makes TypeScript flexible with plain objects and test doubles, but it also means two unrelated classes can accidentally be treated as the same type.

TypeScript
class Dog { name = ""; }
class Cat { name = ""; }
const pet: Dog = new Cat();   // allowed

Try it

TypeScript Same shape, different class

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.

TypeScript Private members and brands make classes nominal

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.

Syntax

There is no syntax to turn structural typing on or off. These rules decide compatibility:

Rule Description
Public members The source type must have every public member of the target, with assignable types. Extra members are fine.
Private / protected members The target's private or protected members must originate from the same declaration in the source. This is what makes such classes nominal.
Optional and readonly Optional members may be missing. readonly does not affect assignability.
Static side Static members and the constructor are separate: typeof A and typeof B are compared on their own.
Fresh object literals Excess property checks apply only to object literals assigned directly, not to class instances.

Edge cases:

  • Two classes with no members are compatible with each other and with {}.
  • Method parameters are compared bivariantly, so a method accepting a subtype is still allowed.
  • instanceof is nominal at runtime: it checks the prototype chain, so it can disagree with the type checker.

Usage notes

  • Rely on structural typing for lightweight mocks: any object with the right methods can stand in for a service.
  • When two types must not be mixed (units, ids), add a private field or a branded property, as in the second example.
  • A type guard based on instanceof narrows by class, but the compiler may keep other structurally identical types in the union.
  • Structural compatibility is checked when you pass a value, so a mismatch is reported at the call site, not at the class declaration.
  • Adding a member to a class can break callers of other classes that used to be compatible.