Duck typing mental model in TypeScript - Deep Dive

Overview - Duck typing mental model in TypeScript

What is it?

Duck typing in TypeScript means that an object's type is determined by what properties and methods it has, not by its explicit type name. If an object looks like a certain type and behaves like it, TypeScript treats it as that type. This lets you use objects flexibly without strict class inheritance or interfaces.

Why it matters

Duck typing exists to make code more flexible and easier to work with by focusing on what an object can do rather than what it is called. Without duck typing, you would need rigid class hierarchies or explicit declarations everywhere, making code harder to reuse and slower to write. It helps TypeScript catch errors while still allowing natural JavaScript-style coding.

Where it fits

Before learning duck typing, you should understand basic TypeScript types and interfaces. After this, you can explore advanced type features like type guards, structural typing, and generics to write safer and more flexible code.

Mental Model

Core Idea

If an object has the right shape—meaning the right properties and methods—TypeScript treats it as that type, regardless of its declared type name.

Think of it like...

It's like recognizing a tool by how it works, not by its label. If it quacks and walks like a duck, it's a duck, no matter what the tag says.

┌───────────────┐       ┌───────────────┐
│   Object A    │       │   Object B    │
│ ┌───────────┐ │       │ ┌───────────┐ │
│ │quack():void│ │       │ │quack():void│ │
│ │walk():void │ │       │ │walk():void │ │
│ └───────────┘ │       │ └───────────┘ │
└───────┬───────┘       └───────┬───────┘
        │                       │
        │ Has same shape        │
        └───────────────┬───────┘
                        ▼
                 Treated as same type

Build-Up - 7 Steps

1

Foundation

Understanding TypeScript Types

Concept: Learn what types are and how TypeScript uses them to check code.

TypeScript uses types to describe what kind of data a variable holds, like number, string, or object. When you write code, TypeScript checks if you use variables correctly according to their types. For example, if a variable is a number, you can't use it like a string.

Result

You know how TypeScript uses types to catch mistakes before running code.

Understanding basic types is essential because duck typing builds on how TypeScript checks if objects fit expected shapes.

2

Foundation

What is Structural Typing?

Concept: TypeScript checks types based on their structure, not their names.

In TypeScript, two objects are considered the same type if they have the same properties with the same types, even if they come from different places. For example, two objects with a 'name' string property are compatible, regardless of their declared types.

Result

You see that TypeScript cares about what properties an object has, not what it's called.

Knowing structural typing helps you understand why duck typing works in TypeScript.

3

Intermediate

How Duck Typing Works in TypeScript

🤔Before reading on: do you think TypeScript requires explicit inheritance to treat objects as the same type? Commit to your answer.

Concept: Duck typing means TypeScript accepts any object that matches the expected shape, without needing explicit inheritance or interface implementation.

If a function expects an object with certain properties or methods, you can pass any object that has those, even if it doesn't declare the type explicitly. For example, a function expecting {quack: () => void} accepts any object with a quack method.

Result

You can use objects flexibly, passing different shapes as long as they fit the expected structure.

Understanding this lets you write more reusable and flexible code without strict class hierarchies.

4

Intermediate

Interfaces and Duck Typing Together

🤔Before reading on: do you think an object must explicitly declare an interface to be used as that interface type? Commit to your answer.

Concept: Interfaces describe expected shapes, but objects don't need to declare them to be compatible.

In TypeScript, interfaces define what properties an object should have. However, any object with matching properties can be used where that interface is expected, even if it doesn't say it implements the interface. This is duck typing in action.

Result

You can use plain objects or different classes interchangeably if they match the interface shape.

Knowing this prevents confusion about needing explicit declarations and encourages flexible design.

5

Intermediate

Optional Properties and Duck Typing

Concept: Optional properties in interfaces affect compatibility in duck typing.

Interfaces can have optional properties marked with ?. When checking compatibility, objects don't need to have optional properties. For example, if an interface has an optional 'fly' method, objects without 'fly' still match the interface if they have the required parts.

Result

You understand how optional parts make duck typing more flexible.

Recognizing optional properties helps you design interfaces that accept a wider range of objects.

6

Advanced

Type Compatibility and Excess Property Checks

🤔Before reading on: do you think TypeScript allows objects with extra properties beyond the expected shape? Commit to your answer.

Concept: TypeScript usually allows extra properties but warns when object literals have unexpected properties directly assigned.

When you assign an object literal to a variable or pass it as an argument, TypeScript checks for extra properties not in the expected type and may give an error. But if the object comes from a variable, extra properties are allowed. This subtlety helps catch mistakes but allows flexibility.

Result

You know when TypeScript enforces strict shape matching and when it is lenient.

Understanding this prevents confusing errors and helps you write clearer code.

7

Expert

Duck Typing Limits and Structural Type System

🤔Before reading on: do you think duck typing can detect all type errors perfectly? Commit to your answer.

Concept: Duck typing relies on structure, which can miss some semantic errors or intentional distinctions between types with the same shape.

Because TypeScript uses structural typing, two different concepts with the same shape are considered compatible. For example, types representing different units or concepts but with the same properties are interchangeable, which can cause subtle bugs. Advanced techniques like branded types or nominal typing patterns help avoid this.

Result

You realize duck typing is powerful but has limits that require careful design.

Knowing these limits helps you avoid bugs and design safer type systems in large projects.

Under the Hood

TypeScript's type system is structural, meaning it compares the shape of types by checking if required properties and methods exist with compatible types. At compile time, TypeScript verifies that objects have the expected members. It does not rely on runtime class inheritance or explicit declarations but on matching property names and types. This allows flexible assignment and function calls based on shape compatibility.

Why designed this way?

TypeScript was designed to work smoothly with JavaScript, which is dynamic and does not enforce classes or interfaces at runtime. Structural typing and duck typing allow gradual typing and easy integration with existing JavaScript code. This design avoids the rigidity of nominal typing, making TypeScript more practical and developer-friendly.

┌───────────────┐       ┌───────────────┐
│ Expected Type │       │ Actual Object │
│ ┌───────────┐ │       │ ┌───────────┐ │
│ │ propA     │ │◄──────│ │ propA     │ │
│ │ methodB() │ │◄──────│ │ methodB() │ │
│ └───────────┘ │       │ └───────────┘ │
└───────┬───────┘       └───────┬───────┘
        │                       │
        │ Structural match      │
        └───────────────┬───────┘
                        ▼
               Assignment allowed

Myth Busters - 3 Common Misconceptions

Quick: Does an object need to explicitly declare an interface to be used as that interface type? Commit to yes or no.

Common Belief: An object must explicitly declare it implements an interface to be treated as that interface.

Reality: TypeScript uses structural typing, so any object with the right shape matches the interface, even without explicit declaration.

Why it matters: Believing this limits flexibility and causes unnecessary code or confusion about compatibility.

Quick: Does TypeScript allow objects with extra properties beyond the expected type without any warnings? Commit to yes or no.

Common Belief: TypeScript always allows objects with extra properties beyond the expected shape without errors.

Reality: TypeScript warns about extra properties when assigning object literals directly but allows them when the object comes from a variable.

Why it matters: Misunderstanding this causes confusing errors or missed mistakes in object shapes.

Quick: Does duck typing guarantee that two types with the same shape are always semantically the same? Commit to yes or no.

Common Belief: If two types have the same shape, they are always interchangeable and mean the same thing.

Reality: Types with the same shape can represent different concepts, and duck typing treats them as compatible, which can cause subtle bugs.

Why it matters: Ignoring this can lead to mixing incompatible data and logic errors in large codebases.

Expert Zone

1

TypeScript's excess property checks only apply to object literals, not variables, which can confuse developers new to duck typing.

2

Branded or nominal typing patterns are used by experts to simulate nominal typing and avoid accidental type compatibility.

3

TypeScript's structural typing allows powerful generic programming but requires careful design to avoid unintended matches.

When NOT to use

Duck typing is not ideal when you need strict type distinctions or nominal typing, such as in financial or safety-critical systems. In those cases, use branded types, classes with private members, or runtime type checks to enforce stricter typing.

Production Patterns

In real-world TypeScript projects, duck typing enables flexible APIs, polymorphic functions, and easy integration with JavaScript libraries. Experts combine it with interfaces, type guards, and branded types to balance flexibility and safety.

Connections

Nominal Typing

Opposite typing system

Understanding duck typing's structural approach clarifies why nominal typing enforces stricter type identity, helping choose the right typing strategy.

Interface Segregation Principle (Software Design)

Builds on

Knowing duck typing helps apply interface segregation by designing small, focused interfaces that objects can easily match.

Biology - Species Identification

Similar pattern of classification

Just like biologists classify animals by observable traits rather than names, duck typing classifies objects by their shape, showing cross-domain parallels in categorization.

Common Pitfalls

#1 Assuming an object must declare an interface to be compatible.

Wrong approach:

interface Bird { fly(): void; }
const obj = { fly: () => console.log('Flying') };
const bird: Bird = obj; // Works
const anotherBird: Bird = { fly: () => console.log('Flying') }; // Error if missing explicit declaration

Correct approach:

interface Bird { fly(): void; }
const obj = { fly: () => console.log('Flying') };
const bird: Bird = obj; // Works
const anotherBird: Bird = { fly: () => console.log('Flying') }; // Also works without explicit declaration

Root cause:

Misunderstanding that TypeScript uses structural typing, not nominal typing.

#2 Getting unexpected errors due to excess property checks on object literals.

Wrong approach:

interface Duck { quack(): void; }
const duck: Duck = { quack: () => {}, swim: () => {} }; // Error: Object literal may only specify known properties

Correct approach:

interface Duck { quack(): void; }
const obj = { quack: () => {}, swim: () => {} };
const duck: Duck = obj; // Works because obj is a variable

Root cause:

Not knowing excess property checks only apply to object literals directly assigned.

#3 Mixing types with same shape but different meanings causing bugs.

Wrong approach:

type USD = { amount: number };
type EUR = { amount: number };
function payUSD(money: USD) { /* ... */ }
payUSD({ amount: 10 } as EUR); // Allowed but incorrect

Correct approach:

type USD = { amount: number; __brand: 'USD' };
type EUR = { amount: number; __brand: 'EUR' };
function payUSD(money: USD) { /* ... */ }
payUSD({ amount: 10, __brand: 'USD' }); // Correct and safe

Root cause:

Structural typing treats same-shaped types as compatible, ignoring semantic differences.

Key Takeaways

Duck typing in TypeScript means compatibility is based on an object's shape, not its declared type name.

TypeScript uses structural typing, allowing flexible and reusable code without strict inheritance.

Excess property checks help catch mistakes but only apply to object literals, not variables.

Duck typing can cause subtle bugs when different concepts share the same shape, requiring advanced patterns to avoid.

Understanding duck typing helps write safer, clearer, and more flexible TypeScript code.