What structural typing means in Typescript - Deep Dive

Overview - What structural typing means

What is it?

Structural typing is a way to check if two types are compatible based on their shape or structure, not their names. It means that if two objects have the same properties with the same types, they are considered the same type. This is different from naming types explicitly and requiring exact matches. Structural typing helps TypeScript understand if values can be used interchangeably by looking at what they contain.

Why it matters

Without structural typing, programmers would have to create exact matching types or classes to use values together, making code less flexible and more verbose. Structural typing allows easier reuse and integration of code by focusing on what data looks like rather than what it is called. This makes programs more adaptable and reduces errors when combining different parts that share the same shape.

Where it fits

Before learning structural typing, you should understand basic TypeScript types and interfaces. After this, you can explore advanced type features like type inference, type guards, and generics. Structural typing is a foundation for understanding how TypeScript checks compatibility between different types and objects.

Mental Model

Core Idea

Types are compatible if their shapes match, regardless of their names.

Think of it like...

It's like matching puzzle pieces by their edges and patterns, not by the picture on the box. If the edges fit perfectly, the pieces connect, no matter what the picture says.

Type A: { name: string, age: number }
Type B: { name: string, age: number }

Type A and Type B are compatible because:
┌─────────────┐   ┌─────────────┐
│ name:string │ = │ name:string │
│ age:number  │ = │ age:number  │
└─────────────┘   └─────────────┘

Names don't matter, only matching properties.

Build-Up - 6 Steps

1

Foundation

Understanding basic types and interfaces

Concept: Learn what types and interfaces are in TypeScript and how they describe data shapes.

In TypeScript, types and interfaces describe what properties an object has and what types those properties are. For example, an interface Person { name: string; age: number } means any object with a string name and a number age fits this shape.

Result

You can create objects that match these shapes and TypeScript will check if they fit the description.

Knowing how types describe data shapes is the first step to understanding how TypeScript compares types.

2

Foundation

Difference between nominal and structural typing

Concept: Introduce the idea that some languages check types by name (nominal) and others by shape (structural).

In nominal typing, types must have the same name to be compatible. In structural typing, types are compatible if their properties match, even if names differ. TypeScript uses structural typing, unlike some languages like Java or C# which use nominal typing.

Result

You understand that TypeScript cares about what properties exist, not what the type is called.

This distinction explains why TypeScript allows flexible type compatibility and why some code that looks different still works.

3

Intermediate

How TypeScript checks type compatibility

🤔Before reading on: do you think TypeScript requires exact type names to match, or just matching properties? Commit to your answer.

Concept: TypeScript compares types by checking if one type has at least the properties of another with compatible types.

When assigning one object to a variable of another type, TypeScript checks if the source has all required properties of the target type with matching types. Extra properties are allowed. For example, an object with {name, age, city} can be assigned to a variable expecting {name, age} because it has all needed properties.

Result

You can assign objects with extra properties to variables expecting fewer properties, as long as required ones match.

Understanding this compatibility rule helps prevent confusion about why some assignments work and others don't.

4

Intermediate

Structural typing with functions and methods

🤔Before reading on: do you think functions are compared by their names or by their input and output types? Commit to your answer.

Concept: Functions are structurally typed by their parameter and return types, not by their names or where they come from.

If two functions have compatible parameter types and return types, TypeScript considers them compatible. For example, a function that takes a number and returns a string can be assigned to a variable expecting a function with the same signature, even if their names differ.

Result

You can interchange functions with matching input/output types regardless of their declared names.

This shows structural typing applies beyond objects to functions, enabling flexible code reuse.

5

Advanced

Structural typing with classes and inheritance

🤔Before reading on: do you think classes must inherit to be compatible, or is matching structure enough? Commit to your answer.

Concept: In TypeScript, classes are also structurally typed, so inheritance is not required for compatibility if the shapes match.

Even if two classes have no inheritance relationship, if their instances have the same properties and methods with compatible types, TypeScript treats them as compatible. This means you can assign an instance of one class to a variable typed as another class if their structures align.

Result

You can use class instances interchangeably based on their shape, not their class hierarchy.

Knowing this prevents confusion about why TypeScript allows assignments between unrelated classes.

6

Expert

Structural typing pitfalls and excess property checks

🤔Before reading on: do you think TypeScript always allows extra properties when assigning objects? Commit to your answer.

Concept: TypeScript performs extra checks when assigning object literals to catch mistakes with unexpected properties, even though structural typing allows extra properties in general.

When you assign an object literal directly to a variable or parameter expecting a certain type, TypeScript warns if the object has properties not in the target type. This is called excess property checking and helps catch typos or errors. However, if the object is stored in a variable first, this check is relaxed.

Result

You learn when TypeScript enforces stricter checks despite structural typing's flexibility.

Understanding excess property checks helps avoid confusing errors and write safer code.

Under the Hood

TypeScript's compiler compares types by examining their properties and methods recursively. It checks if the source type has all required members of the target type with compatible types. This process is called structural compatibility. The compiler ignores type names and focuses on the shape, allowing flexible assignments. Excess property checks are an additional step to catch likely mistakes with object literals.

Why designed this way?

Structural typing was chosen to make TypeScript more flexible and easier to use with JavaScript's dynamic nature. JavaScript objects are often created on the fly without strict class hierarchies, so checking compatibility by shape fits better. This design reduces boilerplate and allows gradual typing. Alternatives like nominal typing would make TypeScript less compatible with existing JavaScript patterns.

┌─────────────────────────────┐
│       TypeScript Compiler    │
├─────────────────────────────┤
│  Compare source and target   │
│  types by properties:        │
│  - Check each property name  │
│  - Check property types      │
│  - Recursively check nested  │
│    structures                │
│                             │
│  Ignore type names           │
│                             │
│  Excess property check for   │
│  object literals             │
└─────────────┬───────────────┘
              │
              ▼
    Compatible or incompatible

Myth Busters - 4 Common Misconceptions

Quick: Does TypeScript require types to have the same name to be compatible? Commit to yes or no.

Common Belief: Types must have the same name or come from the same class to be compatible.

Reality: TypeScript only cares about the shape of the types, not their names or declarations.

Why it matters: Believing this causes confusion when assignments between different named types work, leading to misunderstandings about type safety.

Quick: Can you assign an object with extra properties to a variable expecting fewer properties without error? Commit to yes or no.

Common Belief: Extra properties always cause errors when assigning objects to typed variables.

Reality: TypeScript allows extra properties in assignments except when assigning object literals directly, where it performs excess property checks.

Why it matters: Misunderstanding this leads to frustration with unexpected errors or missed bugs when extra properties are silently accepted.

Quick: Are classes in TypeScript checked by inheritance for compatibility? Commit to yes or no.

Common Belief: Class instances must inherit from the same class to be compatible.

Reality: Classes are structurally typed, so instances with matching properties are compatible regardless of inheritance.

Why it matters: This misconception can cause unnecessary class hierarchies or confusion about why unrelated classes can be assigned to each other.

Quick: Does structural typing mean TypeScript ignores function parameter types? Commit to yes or no.

Common Belief: Functions are compatible as long as their names match, ignoring parameter types.

Reality: Functions are structurally typed by their parameter and return types, not by names.

Why it matters: Ignoring this can cause runtime errors if incompatible functions are assigned, thinking names alone ensure safety.

Expert Zone

1

TypeScript uses a form of 'duck typing' but with strict checks on optional and readonly properties, which can affect compatibility subtly.

2

Excess property checks only apply to object literals assigned directly, not to variables, which can lead to subtle bugs if misunderstood.

3

Structural typing interacts with generics in complex ways, sometimes requiring explicit constraints to ensure correct compatibility.

When NOT to use

Structural typing is less suitable when strict nominal typing is required for security or domain modeling, such as in some backend systems. In those cases, using branded types or nominal typing patterns with unique symbols or classes is better to prevent accidental mixing of types.

Production Patterns

In real-world TypeScript projects, structural typing enables flexible API design, allowing different modules to interoperate without tight coupling. It supports gradual typing of JavaScript codebases and helps with mocking in tests by allowing objects with matching shapes to stand in for complex types.

Connections

Duck Typing (Programming)

Structural typing is a formalized, static version of duck typing.

Understanding structural typing clarifies how TypeScript enforces duck typing rules at compile time, preventing many runtime errors.

Interface Segregation Principle (Software Design)

Structural typing encourages designing small, focused interfaces that can be composed flexibly.

Knowing structural typing helps appreciate why breaking interfaces into minimal shapes improves code reuse and compatibility.

Taxonomy in Biology

Structural typing groups types by shared features rather than lineage, similar to classifying organisms by traits instead of ancestry.

This cross-domain view shows how focusing on observable characteristics rather than names or origins can simplify classification and understanding.

Common Pitfalls

#1 Assigning object literals with typos in property names causes silent acceptance.

Wrong approach:

const person: { name: string; age: number } = { name: 'Alice', agge: 30 };

Correct approach:

const person: { name: string; age: number } = { name: 'Alice', age: 30 };

Root cause:

Misunderstanding that excess property checks only catch extra properties, not misspelled required ones, leading to silent bugs.

#2 Expecting class inheritance to enforce type compatibility.

Wrong approach:

class A { name: string = ''; } class B { name: string = ''; } let a: A = new B(); // Error expected

Correct approach:

class A { name: string = ''; } class B { name: string = ''; } let a: A = new B(); // Allowed due to structural typing

Root cause:

Confusing nominal typing rules from other languages with TypeScript's structural typing.

#3 Ignoring excess property checks when passing object literals to functions.

Wrong approach:

function greet(person: { name: string }) {} greet({ name: 'Bob', age: 25 }); // Error

Correct approach:

const bob = { name: 'Bob', age: 25 }; greet(bob); // Allowed

Root cause:

Not realizing that direct object literals are checked strictly for extra properties, but variables are not.

Key Takeaways

Structural typing means TypeScript checks if types have matching properties, ignoring their names.

This approach allows flexible and safe reuse of code by focusing on what data looks like, not what it is called.

TypeScript applies structural typing to objects, functions, and classes, enabling broad compatibility.

Excess property checks add safety by warning about unexpected properties in object literals.

Understanding structural typing helps avoid common misconceptions and write more adaptable TypeScript code.