Low-Level DesignEntities

Entities in Domain-Driven Design

LevelIntermediate

Duration60 mins

TopicEntities

1 / 4

What is an Entity

The Object That Remembers Who It Is

In the vast landscape of object-oriented programming, we create countless objects—data containers, service wrappers, utility classes. Most objects are defined entirely by their attributes: two Point objects with coordinates (3, 4) are interchangeable. Swap them, and nothing changes.

But some objects are fundamentally different. A Customer named "Alice" with email "alice@example.com" is not interchangeable with another Customer who happens to share the same name and email. If Alice changes her email, she's still Alice. If she moves to a new address, she's still Alice. Something about Alice persists through all these changes—her identity.

This distinction lies at the heart of Domain-Driven Design's tactical patterns. Objects whose identity matters across time and state changes are called Entities. Understanding entities deeply is essential for building systems that accurately model real-world domains where continuity of identity matters.

What You Will Learn

By the end of this page, you will understand what entities are, why they exist as a distinct concept, how they differ from other object types, and when an object in your domain should be modeled as an entity. You'll gain the foundational vocabulary and mental model needed to make correct modeling decisions in complex domains.

The Entity Defined

Let's begin with Eric Evans' definition from the foundational Domain-Driven Design text:

"Many objects are not fundamentally defined by their attributes, but rather by a thread of continuity and identity."

— Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software

An Entity is an object that:

Has a distinct identity that persists through time and state changes
Is distinguishable from other objects even if all attributes are identical
Has continuity — we can track it across the lifetime of the system
Can be referenced — other parts of the system can point to it specifically

The key insight is that entities are not defined by what they are but by which they are. Two entities with identical attributes are still two distinct entities if they have different identities.

The Core Mental Model

Think of entities as objects with "souls." Even if every visible attribute changes, the entity remains the same entity. A person can change their name, address, appearance, and occupation—but they're still the same person. That persistent "sameness" is identity, and objects with identity are entities.

Formal characteristics of an Entity:

Entity Characteristics
Characteristic	Description	Example
Identity	A unique identifier that distinguishes this object from all others of the same type	Customer ID, Order Number, ISBN
Mutability	Attributes can change while identity remains constant	Customer changes address, balance, preferences
Lifecycle	Has a meaningful existence through creation, modification, and potential deletion	Order is created, fulfilled, and archived
Referenceability	Other objects can hold references to this entity via its identity	Invoice references Customer by ID
Equality by Identity	Two entities are equal if and only if they have the same identity	`customer1.equals(customer2)` iff `customer1.id == customer2.id`

Why Entities Exist as a Distinct Concept

You might wonder: "Can't we just use regular classes? Why do we need a special category called 'Entity'?"

The answer lies in the complexity of real-world domains and the need to model them accurately. Without the entity concept, we face several problems:

Problems Without Entity Concept

•Accidental Duplication: Without explicit identity, systems might create duplicate records for the same real-world thing because "all attributes matched" isn't sufficient for identity
•Lost Continuity: When attributes change, we lose track of which object we're dealing with—was this the same customer, or a different one?
•Broken References: If objects are identified by attributes, changing attributes breaks all references
•Inconsistent Equality: Different parts of the system might use different criteria for "sameness," causing subtle bugs
•Domain Confusion: The code doesn't reflect domain experts' mental model, making communication and maintenance harder

The banking domain example:

Consider a BankAccount. Without entity thinking, you might model it as:

class BankAccount {
    String ownerName;
    BigDecimal balance;
    String accountType;
}

Now, if two accounts have the same owner name, balance, and type, are they the same account? Obviously not! In the real world, bank accounts have account numbers—unique identifiers that persist through all changes.

Without this identity:

Transferring $100 between accounts becomes ambiguous
Closing an account might close the wrong one
Regulatory audits can't track account history
Legal proceedings can't identify specific accounts

The entity concept forces us to model identity explicitly, preventing these problems.

Domain-Driven Thinking

Entity is not just a programming pattern—it's a domain modeling concept. When domain experts talk about 'this customer' or 'that order,' they're implicitly using entity thinking. DDD makes this explicit in code, aligning technical implementation with domain understanding.

Entities in Real-World Domains

Entities appear naturally in virtually every complex domain. Recognizing them is a critical skill for domain modeling. Let's examine entities across various industries:

Entities Across Domains
Domain	Entity	Identity	Mutable Attributes
E-Commerce	Customer	CustomerId (UUID)	Name, email, address, preferences, loyalty tier
E-Commerce	Order	OrderNumber	Status, shipping address, line items, payment status
E-Commerce	Product	SKU or ProductId	Name, description, price, stock quantity, images
Healthcare	Patient	MedicalRecordNumber	Name, address, medical history, current medications
Healthcare	Appointment	AppointmentId	DateTime, status, notes, assigned doctor
Finance	Account	AccountNumber	Balance, status, owner, transaction history
Finance	Transaction	TransactionId	Status (though often immutable after creation)
HR System	Employee	EmployeeId	Name, department, salary, role, manager
HR System	Position	PositionId	Title, department, salary range, requirements
Logistics	Shipment	TrackingNumber	Status, location, estimated delivery, contents
Education	Student	StudentId	Name, enrolled courses, grades, contact info
Real Estate	Property	PropertyId or Address	Owner, price, status, description, features

Pattern recognition:

Notice that in every case, the entity has:

A unique identifier that domain experts actually use ("Order #12345," "Patient MRN 78901")
Attributes that can and do change during the entity's lifetime
A meaningful notion of "the same thing" persisting through changes

This isn't accidental—it reflects how businesses actually work. Domain experts don't say "the customer with name 'Alice' and email 'alice@example.com'." They say "Customer ID 12345" or just "Alice's account." Identity is built into the domain language.

Ubiquitous Language Connection

When domain experts naturally refer to things by identifiers ("Order #12345," "Account ending in 7890," "Case number 2024-001"), you're almost certainly looking at an entity. The domain's natural language reveals entity boundaries.

Entities vs Other Object Types

DDD distinguishes entities from other object types, particularly Value Objects. Understanding this distinction is crucial for correct modeling:

Entity Characteristics

•Identity matters — Distinguishable by ID, not attributes
•Mutable — State changes are expected and normal
•Continuous — Has a lifecycle through time
•Referenced — Other objects point to it by ID
•Equality by identity — Same ID = same entity
•Domain-centric — Represents key domain concepts

Value Object Characteristics

•No identity — Defined entirely by attributes
•Immutable — Never changes after creation
•Replaceable — Substituted with equivalent instance
•Embedded — Associated with entities, not referenced independently
•Equality by value — Same attributes = same value
•Descriptive — Describes or measures entities

The classic illustration:

Consider money. A $20 bill in your wallet has a serial number—it's technically an entity (the government tracks it). But when you pay for something, you don't care which $20 bill you use. You care about the amount. In most domains, money is modeled as a Value Object:

// Value Object - defined by its attributes, immutable
class Money {
    constructor(
        public readonly amount: number,
        public readonly currency: string
    ) {}
    
    equals(other: Money): boolean {
        return this.amount === other.amount && 
               this.currency === other.currency;
    }
}

But the bank account holding that money is an Entity:

// Entity - defined by identity, mutable
class BankAccount {
    constructor(
        public readonly accountId: AccountId,  // Identity
        private balance: Money                  // Mutable attribute
    ) {}
    
    equals(other: BankAccount): boolean {
        return this.accountId.equals(other.accountId);
    }
    
    credit(amount: Money): void {
        this.balance = this.balance.add(amount);  // State changes
    }
}

The entity (BankAccount) has an identity that persists. The value object (Money) is defined by what it is, not which specific instance it is.

Context Matters

Whether something is an entity or value object depends on the bounded context. In a currency tracking system, each physical bill might be an entity (tracked by serial number). In a retail POS system, money is a value object (we only care about amounts). Always model based on your specific domain's needs.

The Anatomy of an Entity

Every well-designed entity has a consistent structure. Understanding this structure helps you design entities correctly:

Entity Anatomy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
// A well-structured Entity in TypeScript
 
// Strong typing for identity prevents mixing IDs
class CustomerId {
    constructor(public readonly value: string) {
        if (!value || value.trim().length === 0) {
            throw new Error("CustomerId cannot be empty");
        }
    }
    
    equals(other: CustomerId): boolean {
        return this.value === other.value;
    }
    
    toString(): string {
        return this.value;
    }
}
 
// The Entity itself
class Customer {
    // ========================================
    // 1. IDENTITY - The soul of the entity
    // ========================================
    private readonly id: CustomerId;
    
    // ========================================
    // 2. MUTABLE STATE - Attributes that change
    // ========================================
    private name: string;
    private email: Email;           // Value Object
    private address: Address;       // Value Object
    private loyaltyPoints: number;
    private tier: CustomerTier;     // Enum or Value Object
    
    // ========================================
    // 3. INVARIANTS - Rules that must always hold
    // ========================================
    // - Email must be valid
    // - Name cannot be empty
    // - Loyalty points cannot be negative
    // - Tier must match point thresholds
    
    // ========================================
    // 4. CONSTRUCTOR - Enforce valid creation
    // ========================================
    constructor(
        id: CustomerId,
        name: string,
        email: Email,
        address: Address
    ) {
        this.id = id;
        this.setName(name);  // Use setter for validation
        this.email = email;
        this.address = address;
        this.loyaltyPoints = 0;
        this.tier = CustomerTier.BRONZE;
    }
    
    // ========================================
    // 5. IDENTITY ACCESSOR - Read-only access to ID
    // ========================================
    getId(): CustomerId {
        return this.id;
    }
    
    // ========================================
    // 6. BEHAVIOR METHODS - Operations that modify state
    // ========================================
    changeEmail(newEmail: Email): void {
        // Could raise domain event: EmailChanged
        this.email = newEmail;
    }
    
    relocate(newAddress: Address): void {
        // Could raise domain event: CustomerRelocated
        this.address = newAddress;
    }
    
    earnPoints(points: number): void {
        if (points < 0) {
            throw new Error("Cannot earn negative points");
        }
        this.loyaltyPoints += points;
        this.recalculateTier();
    }
    
    // ========================================
    // 7. PRIVATE HELPERS - Internal state management
    // ========================================
    private setName(name: string): void {
        if (!name || name.trim().length === 0) {
            throw new Error("Customer name cannot be empty");
        }
        this.name = name.trim();
    }
    
    private recalculateTier(): void {
        if (this.loyaltyPoints >= 10000) {
            this.tier = CustomerTier.PLATINUM;
        } else if (this.loyaltyPoints >= 5000) {
            this.tier = CustomerTier.GOLD;
        } else if (this.loyaltyPoints >= 1000) {
            this.tier = CustomerTier.SILVER;
        } else {
            this.tier = CustomerTier.BRONZE;
        }
    }
    
    // ========================================
    // 8. EQUALITY - Based on identity only
    // ========================================
    equals(other: Customer): boolean {
        if (other === null || other === undefined) {
            return false;
        }
        return this.id.equals(other.id);
    }
    
    // ========================================
    // 9. HASH CODE - Consistent with equals
    // ========================================
    hashCode(): number {
        return hashString(this.id.value);
    }
}

Key Structural Elements

•Identity Field: Always private and final/readonly. Once assigned, identity never changes.
•Identity Type: Use a typed ID class instead of raw primitives. Prevents CustomerId from being confused with OrderId.
•Mutable Attributes: Private with controlled access. Changes happen through behavior methods.
•Invariants: Business rules that must always be true. Validated in constructor and methods.
•Behavior Methods: Named using domain language. customer.relocate(address) not customer.setAddress(address).
•Equality: Always based on identity. Two customers with same ID are equal, regardless of other attributes.

When to Model Something as an Entity

Deciding whether to model a concept as an entity is a critical design decision. Here's a systematic approach:

Model as Entity When...

•Identity matters to the business: Domain experts refer to specific instances ("Order #12345", "Patient Smith")
•The object changes over time: State transitions are meaningful (order goes from placed → shipped → delivered)
•Other objects reference it: You need to point to "this specific customer" from multiple places
•Lifecycle is significant: Creation, modification, archival, deletion are business events
•History matters: You might need to track what it was at different points in time
•Duplicates are problematic: Creating two instances of the "same" thing would be a bug
•Operations depend on identity: "Transfer money from account A to account B" requires distinguishing A from B

Model as Value Object When...

•Identity doesn't matter: You care about the value, not which instance
•Objects are interchangeable: Any instance with same attributes works equally well
•Immutability is natural: Once created, there's no reason to change it
•It describes or measures: Money, dates, addresses, measurements, colors
•Equality means equivalent attributes: Two Money(100, USD) are the same
•No meaningful lifecycle: It doesn't "live" through changes—you create new instances

The Litmus Test

Ask yourself: "If I made an exact copy of this object with the same attributes, would that be a bug or perfectly fine?" If it's a bug (two customers with ID 12345 is wrong), it's an entity. If it's fine (two instances of Money(50, 'USD') are interchangeable), it's a value object.

Borderline cases:

Some concepts can be modeled either way depending on context:

Concept	Entity Context	Value Object Context
Address	Property management (each address is a registered location)	E-commerce (just describes where to ship)
Email	Email service (tracking delivery, read status)	User profile (just contact information)
Seat	Airline reservation (this specific seat on this specific flight)	General capacity planning (we need 100 seats)
Color	Paint inventory (tracking specific batches)	UI styling (hex codes are interchangeable)

The domain drives the decision. Model what matters to your specific business context.

Common Entity Modeling Mistakes

Even experienced developers make mistakes when modeling entities. Being aware of these anti-patterns helps you avoid them:

Anti-Patterns to Avoid

•The Anemic Entity: Entity with only getters/setters, no behavior. All logic lives in "service" classes. This scatters domain logic and violates encapsulation.
•The God Entity: Entity that does everything—hundreds of methods, thousands of lines. Usually indicates missing aggregate boundaries or service extraction.
•Primitive Obsession: Using string for CustomerId, int for age, string for email. Loses type safety and validation.
•Mutable Identity: Allowing the ID to change. If customer.setId(newId) exists, the model is broken.
•Attribute-Based Equality: Implementing equals() by comparing all attributes instead of identity. Breaks collections and caching.
•Leaky Encapsulation: Exposing internal state via getters that return mutable objects. Callers can modify entity state without going through proper methods.
•Missing Invariants: No validation in constructor or setters. Entity can exist in invalid states (negative balance, null required fields).
•Confusion with DTOs: Treating the entity like a data transfer object—just a bag of data for serialization. Entities have behavior.

anti-pattern.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// ❌ ANTI-PATTERN: Anemic Entity
 
class Customer {
    public id: string;      // Mutable ID!
    public name: string;
    public email: string;
    public balance: number;
    
    // Just a data container
    // No behavior, no validation
    // Logic scattered elsewhere
}
 
// All logic in a "service"
class CustomerService {
    updateEmail(c: Customer, email: string) {
        // Validation here instead of entity
        if (!isValidEmail(email)) {
            throw new Error("Invalid email");
        }
        c.email = email;
    }
    
    charge(c: Customer, amount: number) {
        // Business logic outside entity
        if (c.balance < amount) {
            throw new Error("Insufficient funds");
        }
        c.balance -= amount;
    }
}

correct-pattern.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
// ✅ CORRECT: Rich Entity
 
class Customer {
    private readonly id: CustomerId;
    private name: string;
    private email: Email;  // Value Object
    private balance: Money; // Value Object
    
    constructor(
        id: CustomerId,
        name: string,
        email: Email
    ) {
        this.id = id;
        this.setName(name);
        this.email = email;
        this.balance = Money.zero();
    }
    
    // Behavior lives in the entity
    changeEmail(newEmail: Email): void {
        this.email = newEmail;
    }
    
    charge(amount: Money): void {
        if (!this.balance.isGreaterThanOrEqual(amount)) {
            throw new InsufficientFundsError(
                this.id, amount
            );
        }
        this.balance = this.balance.subtract(amount);
    }
    
    private setName(name: string): void {
        if (!name?.trim()) {
            throw new InvalidNameError();
        }
        this.name = name.trim();
    }
}

The Litmus Test for Anemic Entities

If your entity has only getters/setters and you have separate 'service' classes with methods like processOrder(order), validateCustomer(customer), or calculateBalance(account), you likely have anemic entities. The logic should live where the data lives.

Summary: The Entity Foundation

We've established the foundational understanding of entities in Domain-Driven Design. Let's consolidate the key insights:

Key Takeaways

•Entities are defined by identity, not attributes — A thread of continuity persists through all state changes.
•Entities have lifecycles — They're created, modified, and potentially removed. This lifecycle is meaningful to the business.
•Identity must be explicit and immutable — Use strongly-typed ID classes, never allow ID changes.
•Equality is based solely on identity — Two entities with the same ID are equal, regardless of other attributes.
•Entities should have behavior — They're not just data containers. Domain logic belongs in the entity.
•Context determines entity vs value object — The same real-world concept might be modeled differently in different bounded contexts.
•Entities are where invariants are enforced — The entity is responsible for maintaining its own consistency.

What's next:

Now that we understand what an entity is, we need to explore the subtle but crucial distinction between identity and equality in depth. The next page dives into how entities determine sameness, why this differs from value equality, and the technical implications for implementing equals() and hashCode() correctly.

Page Complete

You now understand what entities are, why they exist as a distinct concept, and when to use them. You've seen entity structure, recognized common anti-patterns, and understand how entities differ from value objects. Next, we'll explore identity versus equality in depth.

1 / 4

Loading learning content...

Low-Level DesignEntities

Entities in Domain-Driven Design

LevelIntermediate

Duration60 mins

TopicEntities

1 / 4

What is an Entity

The Object That Remembers Who It Is

What You Will Learn

The Entity Defined

Let's begin with Eric Evans' definition from the foundational Domain-Driven Design text:

"Many objects are not fundamentally defined by their attributes, but rather by a thread of continuity and identity."

— Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software

An Entity is an object that:

Has a distinct identity that persists through time and state changes
Is distinguishable from other objects even if all attributes are identical
Has continuity — we can track it across the lifetime of the system
Can be referenced — other parts of the system can point to it specifically

The key insight is that entities are not defined by what they are but by which they are. Two entities with identical attributes are still two distinct entities if they have different identities.

The Core Mental Model

Formal characteristics of an Entity:

Entity Characteristics
Characteristic	Description	Example
Identity	A unique identifier that distinguishes this object from all others of the same type	Customer ID, Order Number, ISBN
Mutability	Attributes can change while identity remains constant	Customer changes address, balance, preferences
Lifecycle	Has a meaningful existence through creation, modification, and potential deletion	Order is created, fulfilled, and archived
Referenceability	Other objects can hold references to this entity via its identity	Invoice references Customer by ID
Equality by Identity	Two entities are equal if and only if they have the same identity	`customer1.equals(customer2)` iff `customer1.id == customer2.id`

Why Entities Exist as a Distinct Concept

You might wonder: "Can't we just use regular classes? Why do we need a special category called 'Entity'?"

The answer lies in the complexity of real-world domains and the need to model them accurately. Without the entity concept, we face several problems:

Problems Without Entity Concept

•Accidental Duplication: Without explicit identity, systems might create duplicate records for the same real-world thing because "all attributes matched" isn't sufficient for identity
•Lost Continuity: When attributes change, we lose track of which object we're dealing with—was this the same customer, or a different one?
•Broken References: If objects are identified by attributes, changing attributes breaks all references
•Inconsistent Equality: Different parts of the system might use different criteria for "sameness," causing subtle bugs
•Domain Confusion: The code doesn't reflect domain experts' mental model, making communication and maintenance harder

The banking domain example:

Consider a BankAccount. Without entity thinking, you might model it as:

class BankAccount {
    String ownerName;
    BigDecimal balance;
    String accountType;
}

Without this identity:

Transferring $100 between accounts becomes ambiguous
Closing an account might close the wrong one
Regulatory audits can't track account history
Legal proceedings can't identify specific accounts

The entity concept forces us to model identity explicitly, preventing these problems.

Domain-Driven Thinking

Entities in Real-World Domains

Entities appear naturally in virtually every complex domain. Recognizing them is a critical skill for domain modeling. Let's examine entities across various industries:

Entities Across Domains
Domain	Entity	Identity	Mutable Attributes
E-Commerce	Customer	CustomerId (UUID)	Name, email, address, preferences, loyalty tier
E-Commerce	Order	OrderNumber	Status, shipping address, line items, payment status
E-Commerce	Product	SKU or ProductId	Name, description, price, stock quantity, images
Healthcare	Patient	MedicalRecordNumber	Name, address, medical history, current medications
Healthcare	Appointment	AppointmentId	DateTime, status, notes, assigned doctor
Finance	Account	AccountNumber	Balance, status, owner, transaction history
Finance	Transaction	TransactionId	Status (though often immutable after creation)
HR System	Employee	EmployeeId	Name, department, salary, role, manager
HR System	Position	PositionId	Title, department, salary range, requirements
Logistics	Shipment	TrackingNumber	Status, location, estimated delivery, contents
Education	Student	StudentId	Name, enrolled courses, grades, contact info
Real Estate	Property	PropertyId or Address	Owner, price, status, description, features

Pattern recognition:

Notice that in every case, the entity has:

A unique identifier that domain experts actually use ("Order #12345," "Patient MRN 78901")
Attributes that can and do change during the entity's lifetime
A meaningful notion of "the same thing" persisting through changes

Ubiquitous Language Connection

Entities vs Other Object Types

DDD distinguishes entities from other object types, particularly Value Objects. Understanding this distinction is crucial for correct modeling:

Entity Characteristics

•Identity matters — Distinguishable by ID, not attributes
•Mutable — State changes are expected and normal
•Continuous — Has a lifecycle through time
•Referenced — Other objects point to it by ID
•Equality by identity — Same ID = same entity
•Domain-centric — Represents key domain concepts

Value Object Characteristics

•No identity — Defined entirely by attributes
•Immutable — Never changes after creation
•Replaceable — Substituted with equivalent instance
•Embedded — Associated with entities, not referenced independently
•Equality by value — Same attributes = same value
•Descriptive — Describes or measures entities

The classic illustration:

// Value Object - defined by its attributes, immutable
class Money {
    constructor(
        public readonly amount: number,
        public readonly currency: string
    ) {}
    
    equals(other: Money): boolean {
        return this.amount === other.amount && 
               this.currency === other.currency;
    }
}

But the bank account holding that money is an Entity:

// Entity - defined by identity, mutable
class BankAccount {
    constructor(
        public readonly accountId: AccountId,  // Identity
        private balance: Money                  // Mutable attribute
    ) {}
    
    equals(other: BankAccount): boolean {
        return this.accountId.equals(other.accountId);
    }
    
    credit(amount: Money): void {
        this.balance = this.balance.add(amount);  // State changes
    }
}

The entity (BankAccount) has an identity that persists. The value object (Money) is defined by what it is, not which specific instance it is.

Context Matters

The Anatomy of an Entity

Every well-designed entity has a consistent structure. Understanding this structure helps you design entities correctly:

Entity Anatomy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
// A well-structured Entity in TypeScript
 
// Strong typing for identity prevents mixing IDs
class CustomerId {
    constructor(public readonly value: string) {
        if (!value || value.trim().length === 0) {
            throw new Error("CustomerId cannot be empty");
        }
    }
    
    equals(other: CustomerId): boolean {
        return this.value === other.value;
    }
    
    toString(): string {
        return this.value;
    }
}
 
// The Entity itself
class Customer {
    // ========================================
    // 1. IDENTITY - The soul of the entity
    // ========================================
    private readonly id: CustomerId;
    
    // ========================================
    // 2. MUTABLE STATE - Attributes that change
    // ========================================
    private name: string;
    private email: Email;           // Value Object
    private address: Address;       // Value Object
    private loyaltyPoints: number;
    private tier: CustomerTier;     // Enum or Value Object
    
    // ========================================
    // 3. INVARIANTS - Rules that must always hold
    // ========================================
    // - Email must be valid
    // - Name cannot be empty
    // - Loyalty points cannot be negative
    // - Tier must match point thresholds
    
    // ========================================
    // 4. CONSTRUCTOR - Enforce valid creation
    // ========================================
    constructor(
        id: CustomerId,
        name: string,
        email: Email,
        address: Address
    ) {
        this.id = id;
        this.setName(name);  // Use setter for validation
        this.email = email;
        this.address = address;
        this.loyaltyPoints = 0;
        this.tier = CustomerTier.BRONZE;
    }
    
    // ========================================
    // 5. IDENTITY ACCESSOR - Read-only access to ID
    // ========================================
    getId(): CustomerId {
        return this.id;
    }
    
    // ========================================
    // 6. BEHAVIOR METHODS - Operations that modify state
    // ========================================
    changeEmail(newEmail: Email): void {
        // Could raise domain event: EmailChanged
        this.email = newEmail;
    }
    
    relocate(newAddress: Address): void {
        // Could raise domain event: CustomerRelocated
        this.address = newAddress;
    }
    
    earnPoints(points: number): void {
        if (points < 0) {
            throw new Error("Cannot earn negative points");
        }
        this.loyaltyPoints += points;
        this.recalculateTier();
    }
    
    // ========================================
    // 7. PRIVATE HELPERS - Internal state management
    // ========================================
    private setName(name: string): void {
        if (!name || name.trim().length === 0) {
            throw new Error("Customer name cannot be empty");
        }
        this.name = name.trim();
    }
    
    private recalculateTier(): void {
        if (this.loyaltyPoints >= 10000) {
            this.tier = CustomerTier.PLATINUM;
        } else if (this.loyaltyPoints >= 5000) {
            this.tier = CustomerTier.GOLD;
        } else if (this.loyaltyPoints >= 1000) {
            this.tier = CustomerTier.SILVER;
        } else {
            this.tier = CustomerTier.BRONZE;
        }
    }
    
    // ========================================
    // 8. EQUALITY - Based on identity only
    // ========================================
    equals(other: Customer): boolean {
        if (other === null || other === undefined) {
            return false;
        }
        return this.id.equals(other.id);
    }
    
    // ========================================
    // 9. HASH CODE - Consistent with equals
    // ========================================
    hashCode(): number {
        return hashString(this.id.value);
    }
}

Key Structural Elements

•Identity Field: Always private and final/readonly. Once assigned, identity never changes.
•Identity Type: Use a typed ID class instead of raw primitives. Prevents CustomerId from being confused with OrderId.
•Mutable Attributes: Private with controlled access. Changes happen through behavior methods.
•Invariants: Business rules that must always be true. Validated in constructor and methods.
•Behavior Methods: Named using domain language. customer.relocate(address) not customer.setAddress(address).
•Equality: Always based on identity. Two customers with same ID are equal, regardless of other attributes.

When to Model Something as an Entity

Deciding whether to model a concept as an entity is a critical design decision. Here's a systematic approach:

Model as Entity When...

•Identity matters to the business: Domain experts refer to specific instances ("Order #12345", "Patient Smith")
•The object changes over time: State transitions are meaningful (order goes from placed → shipped → delivered)
•Other objects reference it: You need to point to "this specific customer" from multiple places
•Lifecycle is significant: Creation, modification, archival, deletion are business events
•History matters: You might need to track what it was at different points in time
•Duplicates are problematic: Creating two instances of the "same" thing would be a bug
•Operations depend on identity: "Transfer money from account A to account B" requires distinguishing A from B

Model as Value Object When...

•Identity doesn't matter: You care about the value, not which instance
•Objects are interchangeable: Any instance with same attributes works equally well
•Immutability is natural: Once created, there's no reason to change it
•It describes or measures: Money, dates, addresses, measurements, colors
•Equality means equivalent attributes: Two Money(100, USD) are the same
•No meaningful lifecycle: It doesn't "live" through changes—you create new instances

The Litmus Test

Borderline cases:

Some concepts can be modeled either way depending on context:

Concept	Entity Context	Value Object Context
Address	Property management (each address is a registered location)	E-commerce (just describes where to ship)
Email	Email service (tracking delivery, read status)	User profile (just contact information)
Seat	Airline reservation (this specific seat on this specific flight)	General capacity planning (we need 100 seats)
Color	Paint inventory (tracking specific batches)	UI styling (hex codes are interchangeable)

The domain drives the decision. Model what matters to your specific business context.

Common Entity Modeling Mistakes

Even experienced developers make mistakes when modeling entities. Being aware of these anti-patterns helps you avoid them:

Anti-Patterns to Avoid

•The Anemic Entity: Entity with only getters/setters, no behavior. All logic lives in "service" classes. This scatters domain logic and violates encapsulation.
•The God Entity: Entity that does everything—hundreds of methods, thousands of lines. Usually indicates missing aggregate boundaries or service extraction.
•Primitive Obsession: Using string for CustomerId, int for age, string for email. Loses type safety and validation.
•Mutable Identity: Allowing the ID to change. If customer.setId(newId) exists, the model is broken.
•Attribute-Based Equality: Implementing equals() by comparing all attributes instead of identity. Breaks collections and caching.
•Leaky Encapsulation: Exposing internal state via getters that return mutable objects. Callers can modify entity state without going through proper methods.
•Missing Invariants: No validation in constructor or setters. Entity can exist in invalid states (negative balance, null required fields).
•Confusion with DTOs: Treating the entity like a data transfer object—just a bag of data for serialization. Entities have behavior.

anti-pattern.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// ❌ ANTI-PATTERN: Anemic Entity
 
class Customer {
    public id: string;      // Mutable ID!
    public name: string;
    public email: string;
    public balance: number;
    
    // Just a data container
    // No behavior, no validation
    // Logic scattered elsewhere
}
 
// All logic in a "service"
class CustomerService {
    updateEmail(c: Customer, email: string) {
        // Validation here instead of entity
        if (!isValidEmail(email)) {
            throw new Error("Invalid email");
        }
        c.email = email;
    }
    
    charge(c: Customer, amount: number) {
        // Business logic outside entity
        if (c.balance < amount) {
            throw new Error("Insufficient funds");
        }
        c.balance -= amount;
    }
}

correct-pattern.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
// ✅ CORRECT: Rich Entity
 
class Customer {
    private readonly id: CustomerId;
    private name: string;
    private email: Email;  // Value Object
    private balance: Money; // Value Object
    
    constructor(
        id: CustomerId,
        name: string,
        email: Email
    ) {
        this.id = id;
        this.setName(name);
        this.email = email;
        this.balance = Money.zero();
    }
    
    // Behavior lives in the entity
    changeEmail(newEmail: Email): void {
        this.email = newEmail;
    }
    
    charge(amount: Money): void {
        if (!this.balance.isGreaterThanOrEqual(amount)) {
            throw new InsufficientFundsError(
                this.id, amount
            );
        }
        this.balance = this.balance.subtract(amount);
    }
    
    private setName(name: string): void {
        if (!name?.trim()) {
            throw new InvalidNameError();
        }
        this.name = name.trim();
    }
}

The Litmus Test for Anemic Entities

Summary: The Entity Foundation

We've established the foundational understanding of entities in Domain-Driven Design. Let's consolidate the key insights:

Key Takeaways

•Entities are defined by identity, not attributes — A thread of continuity persists through all state changes.
•Entities have lifecycles — They're created, modified, and potentially removed. This lifecycle is meaningful to the business.
•Identity must be explicit and immutable — Use strongly-typed ID classes, never allow ID changes.
•Equality is based solely on identity — Two entities with the same ID are equal, regardless of other attributes.
•Entities should have behavior — They're not just data containers. Domain logic belongs in the entity.
•Context determines entity vs value object — The same real-world concept might be modeled differently in different bounded contexts.
•Entities are where invariants are enforced — The entity is responsible for maintaining its own consistency.

What's next:

Page Complete

1 / 4