System Design LLDWhat Is Encapsulation

What Is Encapsulation?

LevelBeginner

Duration50 mins

TopicWhat Is Encapsulation

2 / 4

Bundling Data and Behavior

Why Data and Behavior Belong Together

Consider a medical practice. Patient records are kept in filing cabinets—folders containing medical history, prescriptions, lab results. Now imagine if the doctors, nurses, and pharmacists who interpret and act on those records worked in completely separate buildings with no connection to where the records are stored.

Every time a doctor needed to make a decision, they'd have to send a messenger to the filing building, wait for records, interpret them, make a decision, then send another messenger to update the records. The potential for lost data, miscommunication, and errors would be enormous.

This is precisely what happens in software when we separate data from behavior.

The fundamental principle: Data and the operations that manipulate that data have a natural affinity. They belong together. This page explores why this bundling is essential, how to achieve it correctly, and what happens when we violate this principle.

What You Will Learn

By the end of this page, you will understand the principle of cohesive bundling, recognize the symptoms of data-behavior separation, design classes that keep related data and methods together, and understand the relationship between bundling and the Single Responsibility Principle.

The Nature of Data-Behavior Affinity

In any system, certain operations are intrinsically tied to certain data. This isn't arbitrary—it reflects the nature of the domain we're modeling:

Bank accounts have balances, and deposit/withdraw operations that modify those balances.
Email messages have content, recipients, and send/forward operations that act on that data.
Shopping carts have items and totals, with add/remove operations that change them.
User profiles have credentials, with authenticate/updatePassword operations.

In each case, the operations are meaningless without the data, and the data is rarely useful without operations to manipulate it.

Signs of Natural Data-Behavior Affinity

•The operation always needs this data — A calculateTotal() method always needs access to the items and prices. They're inseparable.
•The data is meaningless without context — A raw balance number means nothing without operations that explain its semantics (what currency? can it go negative?).
•Changes are coupled — When the data structure changes, the operations must change. If items becomes lineItems, all operations accessing it must update.
•Validation is operation-specific — What constitutes valid data often depends on operations. A password might have different validity rules for creation vs. update.

The object-oriented solution:

Object-oriented design formalizes this affinity. A class is a construct that packages:

Attributes (Fields) — The data the entity owns
Methods — The operations that act on that data
Invariants — The rules about valid states (enforced by methods)

This package becomes a single, cohesive unit—an object—that is self-sufficient for its domain responsibilities.

The Anti-Pattern: Anemic Domain Models

The most common violation of data-behavior bundling is the Anemic Domain Model—a term coined by Martin Fowler to describe a diseased design pattern that plagues enterprise software.

In an anemic domain model:

Classes contain data (fields + getters/setters)
Behavior lives in separate "service" classes
Domain objects are mere data containers with no business logic

anemic_example.ts
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
// ❌ ANTI-PATTERN: Anemic Domain Model
 
// The "entity" is just a data bag with no behavior
class Order {
    id: string;
    customerId: string;
    items: OrderItem[];
    status: string;
    totalAmount: number;
    createdAt: Date;
    
    // Nothing but getters and setters
}
 
// All behavior lives in a separate "service"
class OrderService {
    calculateTotal(order: Order): number {
        let total = 0;
        for (const item of order.items) {
            total += item.price * item.quantity;
        }
        return total;
    }
    
    canBeCancelled(order: Order): boolean {
        return order.status === 'pending' || order.status === 'processing';
    }
    
    cancel(order: Order): void {
        if (!this.canBeCancelled(order)) {
            throw new Error("Order cannot be cancelled");
        }
        order.status = 'cancelled';
        // Direct field manipulation from outside the class!
    }
    
    addItem(order: Order, item: OrderItem): void {
        order.items.push(item);
        order.totalAmount = this.calculateTotal(order);
        // The service knows intimate details of Order's internals
    }
}

The problems with this design are severe:

Problems with Anemic Domain Models

•Lost Discoverability — To understand what you can do with an Order, you must search for OrderService, OrderProcessor, OrderValidator, etc. The behavior is scattered.
•Impossible Invariant Enforcement — Order cannot guarantee its status is valid or its total is correct. Any code can set order.status = 'invalid_garbage'.
•Duplicated Logic — Different services may implement the same logic differently. Two places might calculate totals with different rounding rules.
•Testing Complexity — Testing Order logic requires testing OrderService, which requires mocking all its dependencies.
•Feature Envy — The service is constantly reaching into Order to access its data—a code smell indicating misplaced responsibility.
•Procedural Design in OO Clothing — This is procedural programming wearing a class costume. We haven't gained OO benefits.

The "Service" Trap

Many enterprise frameworks encourage anemic models by generating "entity" classes for data and expecting "service" classes for logic. This architecture pattern has legitimate uses (for coordination and orchestration), but becomes an anti-pattern when ALL domain logic migrates to services, leaving entities hollow.

The Corrected Design: Rich Domain Models

The antidote to anemic models is the Rich Domain Model—objects that own both their data AND the behavior that operates on that data. Let's refactor the previous example:

rich_domain_model.ts
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
// ✅ CORRECT: Rich Domain Model with bundled behavior
 
class Order {
    private readonly id: string;
    private readonly customerId: string;
    private items: OrderItem[];
    private status: OrderStatus;
    private cachedTotal: number | null = null;
    private readonly createdAt: Date;
    
    constructor(id: string, customerId: string) {
        this.id = id;
        this.customerId = customerId;
        this.items = [];
        this.status = OrderStatus.PENDING;
        this.createdAt = new Date();
    }
    
    // Behavior is bundled WITH the data it operates on
    
    addItem(item: OrderItem): void {
        if (!this.canBeModified()) {
            throw new OrderModificationError(
                "Cannot add items to a non-modifiable order"
            );
        }
        this.validateItem(item);
        this.items.push(item);
        this.invalidateCachedTotal();
    }
    
    removeItem(itemId: string): void {
        if (!this.canBeModified()) {
            throw new OrderModificationError(
                "Cannot remove items from a non-modifiable order"
            );
        }
        this.items = this.items.filter(item => item.id !== itemId);
        this.invalidateCachedTotal();
    }
    
    getTotal(): number {
        if (this.cachedTotal === null) {
            this.cachedTotal = this.items.reduce(
                (sum, item) => sum + item.price * item.quantity,
                0
            );
        }
        return this.cachedTotal;
    }
    
    cancel(): void {
        if (!this.canBeCancelled()) {
            throw new OrderStateError(
                `Order in status ${this.status} cannot be cancelled`
            );
        }
        this.status = OrderStatus.CANCELLED;
    }
    
    // Domain logic is INSIDE the class
    
    private canBeModified(): boolean {
        return this.status === OrderStatus.PENDING;
    }
    
    canBeCancelled(): boolean {
        return [OrderStatus.PENDING, OrderStatus.PROCESSING]
            .includes(this.status);
    }
    
    private validateItem(item: OrderItem): void {
        if (item.quantity <= 0) {
            throw new ValidationError("Item quantity must be positive");
        }
        if (item.price < 0) {
            throw new ValidationError("Item price cannot be negative");
        }
    }
    
    private invalidateCachedTotal(): void {
        this.cachedTotal = null;
    }
    
    // Controlled access to state
    
    getId(): string { return this.id; }
    getStatus(): OrderStatus { return this.status; }
    getItemCount(): number { return this.items.length; }
    
    // Return a defensive copy or immutable view
    getItems(): ReadonlyArray<OrderItem> { 
        return [...this.items]; 
    }
}

The transformation is dramatic:

Anemic Model

•Status can be set to anything
•Total must be manually kept in sync
•Items can be added in any state
•Validation scattered in services
•Testing requires service + entity
•Domain rules live outside domain

Rich Domain Model

•Status transitions are controlled
•Total is always consistent (cached)
•State-based modification control
•Validation inside the entity
•Entity is self-testing, complete
•Domain rules ARE the domain

The Principle of Cohesion

Data-behavior bundling is deeply connected to the concept of cohesion—a measure of how strongly related and focused the responsibilities of a single module are.

High cohesion means that the elements of a class work together toward a single, well-defined purpose. Low cohesion means a class is a grab-bag of unrelated responsibilities.

Bundling data and behavior correctly is the mechanism by which we achieve high cohesion.

Types of Cohesion (From Worst to Best)
Type	Description	Example	Quality
Coincidental	Elements are randomly grouped	UtilityClass with unrelated functions	❌ Worst
Logical	Elements do similar things but on different data	AllValidatorsInOneClass	❌ Poor
Temporal	Elements are grouped by when they execute	StartupInitializer doing unrelated setup	⚠️ Weak
Procedural	Elements are steps in a procedure	ProcessingPipeline with coupled steps	⚠️ Moderate
Communicational	Elements operate on the same data	Report class generating multiple reports from same data	✅ Good
Sequential	Output of one element is input to next	DataTransformer pipeline	✅ Good
Functional	All elements contribute to a single, well-defined task	Parser class parsing only one format	✅ Best

Cohesion and bundling:

When data and behavior are properly bundled, classes naturally achieve communicational or functional cohesion:

All methods operate on the same data (communicational)
All elements contribute to a single domain responsibility (functional)

An Order class achieves functional cohesion when all its methods relate to order management. The data (items, status, total) and behavior (addItem, cancel, getTotal) work together toward managing orders.

Anemic models create coincidental or logical cohesion: the entity class groups data coincidentally, while service classes group behaviors logically but not by the data they operate on.

Cohesion Heuristic

To test cohesion, try to describe your class's responsibility in one sentence without using "and" or "or." If you can't, the class might be doing too much. An Order class "manages order state and operations"—single responsibility. An OrderAndEmailService "manages orders AND sends emails"—two responsibilities, low cohesion.

What Belongs Together? Design Heuristics

Deciding what data and behavior to bundle together requires judgment. Here are practical heuristics for making these decisions:

Heuristics for Data-Behavior Bundling

•The Information Expert Principle — Assign responsibility to the class that has the information needed to fulfill it. If Order has items and prices, Order should calculate the total. Not a calculator service.
•The Actor Principle — Group data and behavior by the real-world entity it models. An Order, a Customer, a Product—these are your actors. Their real-world operations hint at class methods.
•The Change Together Principle — If data and behavior change together (for the same reasons, at the same times), they belong together. Item prices and total calculation rules change together—bundle them.
•The Coupled Access Pattern — If certain data is always accessed by certain operations, bundle them. If startTime and endTime are always accessed by isActive() and getDuration(), they belong in the same class.
•The Invariant Principle — If an invariant ("total equals sum of item prices") must be maintained, the data involved and the operations that enforce it must be together.

information_expert.ts
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
// Applying the Information Expert Principle
 
// ❌ WRONG: External calculation
class Product {
    name: string;
    price: number;
    taxCategory: string;
}
 
class TaxCalculator {
    calculateTax(product: Product): number {
        // TaxCalculator needs to know about Product's internals
        switch (product.taxCategory) {
            case 'food': return product.price * 0.0;
            case 'luxury': return product.price * 0.20;
            default: return product.price * 0.10;
        }
    }
}
 
// ✅ CORRECT: Product is the information expert
class Product {
    private name: string;
    private price: number;
    private taxRate: number; // Internalized from taxCategory
    
    constructor(name: string, price: number, taxCategory: TaxCategory) {
        this.name = name;
        this.price = price;
        this.taxRate = TaxCategory.toRate(taxCategory);
    }
    
    // Product knows its own tax—it has all needed information
    calculateTax(): number {
        return this.price * this.taxRate;
    }
    
    getPriceWithTax(): number {
        return this.price + this.calculateTax();
    }
}

Boundaries are not always obvious:

Some decisions require deeper analysis:

Cross-cutting concerns like logging and security don't belong in domain objects—use aspect-oriented techniques or decorators.
Coordination logic that orchestrates multiple objects belongs in application services, not domain entities.
Infrastructure concerns (database, network) should be injected as dependencies, not bundled with domain data.

The goal is not to cram everything into domain classes, but to ensure that domain behavior lives with domain data. Technical infrastructure remains separate.

Tell, Don't Ask: The Complementary Principle

Data-behavior bundling naturally leads to the Tell, Don't Ask principle—a design heuristic that reinforces good encapsulation:

Tell objects what to do; don't ask them for data and make decisions externally.

This principle directly addresses a common pattern where external code queries an object's state, makes a decision, then tells the object what to do. This pattern violates encapsulation because the decision logic should live inside the object.

ask_pattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// ❌ ASK: Query then decide externally
 
function processPayment(order: Order) {
    // ASK for status
    if (order.getStatus() === 'pending') {
        // ASK for total
        const total = order.getTotal();
        // External decision-making
        if (total > 0) {
            paymentGateway.charge(total);
            // TELL order what we decided
            order.setStatus('paid');
        }
    }
}

tell_pattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// ✅ TELL: Let the object decide
 
function processPayment(order: Order) {
    // TELL order to accept payment
    // Order decides if this is valid
    order.acceptPayment(paymentGateway);
    // Order encapsulates its own rules
}
 
// Inside Order class:
acceptPayment(gateway: PaymentGateway) {
    if (this.status !== 'pending') {
        throw new InvalidStateError();
    }
    gateway.charge(this.getTotal());
    this.status = 'paid';
}

Why Tell, Don't Ask matters:

Encapsulates decisions — The decision "can I be paid?" lives inside Order, not scattered across callers.
Prevents duplication — Every caller would have to duplicate the status-checking logic in the Ask pattern.
Enables evolution — If the rules for accepting payment change (e.g., add fraud checks), only Order needs updating.
Reduces temporal coupling — In the Ask pattern, callers must call methods in the right order. In Tell, the object controls the sequence.

Note: This doesn't mean getters are forbidden. Sometimes you legitimately need to display data. But if you're getting data to make a decision, ask if that decision should live inside the object.

The Litmus Test

If you find yourself writing if (object.getSomething()) followed by object.doSomething(), consider whether the entire logic should be a single method on the object. The chain of "get-check-do" is a smell indicating potential encapsulation violation.

Bundling in Practice: A Case Study

Let's work through a realistic example of designing bundled classes. Consider a Subscription system where users subscribe to plans with billing cycles.

Initial requirements:

Users have subscriptions to plans
Plans have prices and billing intervals (monthly/yearly)
Subscriptions can be active, paused, cancelled, or expired
Users can upgrade/downgrade plans
Billing calculates the next charge date and prorated amounts

subscription_domain.ts
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
128
129
130
131
132
133
134
135
136
137
138
// A well-bundled Subscription class
 
class Subscription {
    private readonly id: string;
    private readonly userId: string;
    private plan: Plan;
    private status: SubscriptionStatus;
    private startDate: Date;
    private currentPeriodEnd: Date;
    private pausedAt: Date | null = null;
    
    constructor(id: string, userId: string, plan: Plan) {
        this.id = id;
        this.userId = userId;
        this.plan = plan;
        this.status = SubscriptionStatus.ACTIVE;
        this.startDate = new Date();
        this.currentPeriodEnd = this.plan.calculateNextBillingDate(this.startDate);
    }
    
    // ===== Domain Behaviors (bundled with data) =====
    
    changePlan(newPlan: Plan, billingMode: BillingMode): PlanChangeResult {
        this.ensureCanModify();
        
        const prorationData = this.calculateProration(newPlan, billingMode);
        const previousPlan = this.plan;
        
        this.plan = newPlan;
        this.currentPeriodEnd = newPlan.calculateNextBillingDate(new Date());
        
        return new PlanChangeResult(
            previousPlan,
            newPlan,
            prorationData.creditAmount,
            prorationData.chargeAmount
        );
    }
    
    pause(reason: PauseReason): void {
        this.ensureActive();
        this.status = SubscriptionStatus.PAUSED;
        this.pausedAt = new Date();
    }
    
    resume(): void {
        if (this.status !== SubscriptionStatus.PAUSED) {
            throw new InvalidStateError("Can only resume paused subscriptions");
        }
        
        // Extend the period by the pause duration
        const pauseDuration = Date.now() - this.pausedAt!.getTime();
        this.currentPeriodEnd = new Date(
            this.currentPeriodEnd.getTime() + pauseDuration
        );
        
        this.status = SubscriptionStatus.ACTIVE;
        this.pausedAt = null;
    }
    
    cancel(immediate: boolean = false): CancellationResult {
        this.ensureCanModify();
        
        if (immediate) {
            this.status = SubscriptionStatus.CANCELLED;
            return new CancellationResult(new Date(), this.calculateRefund());
        }
        
        // Schedule cancellation at period end
        this.status = SubscriptionStatus.PENDING_CANCELLATION;
        return new CancellationResult(this.currentPeriodEnd, 0);
    }
    
    renew(): void {
        if (!this.isRenewable()) {
            throw new InvalidStateError("Subscription is not renewable");
        }
        this.currentPeriodEnd = this.plan.calculateNextBillingDate(
            this.currentPeriodEnd
        );
        this.status = SubscriptionStatus.ACTIVE;
    }
    
    // ===== Private Helpers (internal logic) =====
    
    private ensureActive(): void {
        if (this.status !== SubscriptionStatus.ACTIVE) {
            throw new InvalidStateError(
                `Operation requires active subscription, current: ${this.status}`
            );
        }
    }
    
    private ensureCanModify(): void {
        const modifiableStatuses = [
            SubscriptionStatus.ACTIVE,
            SubscriptionStatus.PAUSED
        ];
        if (!modifiableStatuses.includes(this.status)) {
            throw new InvalidStateError("Subscription cannot be modified");
        }
    }
    
    private calculateProration(newPlan: Plan, mode: BillingMode): ProrationData {
        const daysRemaining = this.getDaysRemainingInPeriod();
        const totalDays = this.getPeriodLengthDays();
        const fraction = daysRemaining / totalDays;
        
        const currentCredit = this.plan.price * fraction;
        const newCharge = mode === BillingMode.IMMEDIATE 
            ? newPlan.price 
            : newPlan.price * fraction;
            
        return { creditAmount: currentCredit, chargeAmount: newCharge };
    }
    
    private calculateRefund(): number {
        const fraction = this.getDaysRemainingInPeriod() / this.getPeriodLengthDays();
        return this.plan.price * fraction;
    }
    
    // ===== Query Methods (controlled access) =====
    
    isActive(): boolean {
        return this.status === SubscriptionStatus.ACTIVE;
    }
    
    isRenewable(): boolean {
        return [
            SubscriptionStatus.ACTIVE,
            SubscriptionStatus.PAUSED
        ].includes(this.status);
    }
    
    getDaysRemainingInPeriod(): number { /* ... */ }
    getPeriodLengthDays(): number { /* ... */ }
    getCurrentPlan(): Plan { return this.plan; }
}

Notice how the design embodies bundling:

All subscription data (status, plan, dates) is private
All subscription operations (changePlan, pause, resume, cancel, renew) are methods
Invariants ("can't pause a cancelled subscription") are enforced internally
Complex calculations (proration, refunds) live inside the class
External code tells the subscription what to do (subscription.changePlan(newPlan)), not how

An anemic version would expose all fields and put SubscriptionService.changePlan(subscription, newPlan) elsewhere—losing all these benefits.

Summary: Bundling Data and Behavior

We've explored the first pillar of encapsulation in depth. Here are the essential takeaways:

Key Takeaways

•Data and behavior have natural affinity — Operations that always need certain data, or data that only makes sense with certain operations, belong together in a class.
•Anemic domain models are an anti-pattern — Separating data into entities and behavior into services creates procedural code disguised as OO, losing all encapsulation benefits.
•Rich domain models bundle properly — Domain logic lives inside domain entities. Entities are self-sufficient, enforcing their own invariants.
•Cohesion is the goal — Proper bundling achieves functional or communicational cohesion. All elements work together toward a single responsibility.
•Use the Information Expert principle — Assign behavior to the class that has the information needed for it.
•Tell, Don't Ask reinforces bundling — Instead of querying state externally and deciding, tell objects what to do and let them decide.

What's next:

Bundling is only half of encapsulation. The next page explores the second pillar: hiding implementation details. We'll learn how to decide what to expose, what to hide, and why keeping secrets is essential for maintainable software.

Page Complete

You now understand why data and behavior belong together, can recognize the anemic domain model anti-pattern, and know how to design rich domain models that properly bundle state and operations. This is the foundation of writing objects that are self-sufficient and self-protecting.

2 / 4

Loading learning content...

System Design LLDWhat Is Encapsulation

What Is Encapsulation?

LevelBeginner

Duration50 mins

TopicWhat Is Encapsulation

2 / 4

Bundling Data and Behavior

Why Data and Behavior Belong Together

This is precisely what happens in software when we separate data from behavior.

What You Will Learn

The Nature of Data-Behavior Affinity

In any system, certain operations are intrinsically tied to certain data. This isn't arbitrary—it reflects the nature of the domain we're modeling:

Bank accounts have balances, and deposit/withdraw operations that modify those balances.
Email messages have content, recipients, and send/forward operations that act on that data.
Shopping carts have items and totals, with add/remove operations that change them.
User profiles have credentials, with authenticate/updatePassword operations.

In each case, the operations are meaningless without the data, and the data is rarely useful without operations to manipulate it.

Signs of Natural Data-Behavior Affinity

•The operation always needs this data — A calculateTotal() method always needs access to the items and prices. They're inseparable.
•The data is meaningless without context — A raw balance number means nothing without operations that explain its semantics (what currency? can it go negative?).
•Changes are coupled — When the data structure changes, the operations must change. If items becomes lineItems, all operations accessing it must update.
•Validation is operation-specific — What constitutes valid data often depends on operations. A password might have different validity rules for creation vs. update.

The object-oriented solution:

Object-oriented design formalizes this affinity. A class is a construct that packages:

Attributes (Fields) — The data the entity owns
Methods — The operations that act on that data
Invariants — The rules about valid states (enforced by methods)

This package becomes a single, cohesive unit—an object—that is self-sufficient for its domain responsibilities.

The Anti-Pattern: Anemic Domain Models

The most common violation of data-behavior bundling is the Anemic Domain Model—a term coined by Martin Fowler to describe a diseased design pattern that plagues enterprise software.

In an anemic domain model:

Classes contain data (fields + getters/setters)
Behavior lives in separate "service" classes
Domain objects are mere data containers with no business logic

anemic_example.ts
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
// ❌ ANTI-PATTERN: Anemic Domain Model
 
// The "entity" is just a data bag with no behavior
class Order {
    id: string;
    customerId: string;
    items: OrderItem[];
    status: string;
    totalAmount: number;
    createdAt: Date;
    
    // Nothing but getters and setters
}
 
// All behavior lives in a separate "service"
class OrderService {
    calculateTotal(order: Order): number {
        let total = 0;
        for (const item of order.items) {
            total += item.price * item.quantity;
        }
        return total;
    }
    
    canBeCancelled(order: Order): boolean {
        return order.status === 'pending' || order.status === 'processing';
    }
    
    cancel(order: Order): void {
        if (!this.canBeCancelled(order)) {
            throw new Error("Order cannot be cancelled");
        }
        order.status = 'cancelled';
        // Direct field manipulation from outside the class!
    }
    
    addItem(order: Order, item: OrderItem): void {
        order.items.push(item);
        order.totalAmount = this.calculateTotal(order);
        // The service knows intimate details of Order's internals
    }
}

The problems with this design are severe:

Problems with Anemic Domain Models

•Lost Discoverability — To understand what you can do with an Order, you must search for OrderService, OrderProcessor, OrderValidator, etc. The behavior is scattered.
•Impossible Invariant Enforcement — Order cannot guarantee its status is valid or its total is correct. Any code can set order.status = 'invalid_garbage'.
•Duplicated Logic — Different services may implement the same logic differently. Two places might calculate totals with different rounding rules.
•Testing Complexity — Testing Order logic requires testing OrderService, which requires mocking all its dependencies.
•Feature Envy — The service is constantly reaching into Order to access its data—a code smell indicating misplaced responsibility.
•Procedural Design in OO Clothing — This is procedural programming wearing a class costume. We haven't gained OO benefits.

The "Service" Trap

The Corrected Design: Rich Domain Models

The antidote to anemic models is the Rich Domain Model—objects that own both their data AND the behavior that operates on that data. Let's refactor the previous example:

rich_domain_model.ts
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
// ✅ CORRECT: Rich Domain Model with bundled behavior
 
class Order {
    private readonly id: string;
    private readonly customerId: string;
    private items: OrderItem[];
    private status: OrderStatus;
    private cachedTotal: number | null = null;
    private readonly createdAt: Date;
    
    constructor(id: string, customerId: string) {
        this.id = id;
        this.customerId = customerId;
        this.items = [];
        this.status = OrderStatus.PENDING;
        this.createdAt = new Date();
    }
    
    // Behavior is bundled WITH the data it operates on
    
    addItem(item: OrderItem): void {
        if (!this.canBeModified()) {
            throw new OrderModificationError(
                "Cannot add items to a non-modifiable order"
            );
        }
        this.validateItem(item);
        this.items.push(item);
        this.invalidateCachedTotal();
    }
    
    removeItem(itemId: string): void {
        if (!this.canBeModified()) {
            throw new OrderModificationError(
                "Cannot remove items from a non-modifiable order"
            );
        }
        this.items = this.items.filter(item => item.id !== itemId);
        this.invalidateCachedTotal();
    }
    
    getTotal(): number {
        if (this.cachedTotal === null) {
            this.cachedTotal = this.items.reduce(
                (sum, item) => sum + item.price * item.quantity,
                0
            );
        }
        return this.cachedTotal;
    }
    
    cancel(): void {
        if (!this.canBeCancelled()) {
            throw new OrderStateError(
                `Order in status ${this.status} cannot be cancelled`
            );
        }
        this.status = OrderStatus.CANCELLED;
    }
    
    // Domain logic is INSIDE the class
    
    private canBeModified(): boolean {
        return this.status === OrderStatus.PENDING;
    }
    
    canBeCancelled(): boolean {
        return [OrderStatus.PENDING, OrderStatus.PROCESSING]
            .includes(this.status);
    }
    
    private validateItem(item: OrderItem): void {
        if (item.quantity <= 0) {
            throw new ValidationError("Item quantity must be positive");
        }
        if (item.price < 0) {
            throw new ValidationError("Item price cannot be negative");
        }
    }
    
    private invalidateCachedTotal(): void {
        this.cachedTotal = null;
    }
    
    // Controlled access to state
    
    getId(): string { return this.id; }
    getStatus(): OrderStatus { return this.status; }
    getItemCount(): number { return this.items.length; }
    
    // Return a defensive copy or immutable view
    getItems(): ReadonlyArray<OrderItem> { 
        return [...this.items]; 
    }
}

The transformation is dramatic:

Anemic Model

•Status can be set to anything
•Total must be manually kept in sync
•Items can be added in any state
•Validation scattered in services
•Testing requires service + entity
•Domain rules live outside domain

Rich Domain Model

•Status transitions are controlled
•Total is always consistent (cached)
•State-based modification control
•Validation inside the entity
•Entity is self-testing, complete
•Domain rules ARE the domain

The Principle of Cohesion

Data-behavior bundling is deeply connected to the concept of cohesion—a measure of how strongly related and focused the responsibilities of a single module are.

High cohesion means that the elements of a class work together toward a single, well-defined purpose. Low cohesion means a class is a grab-bag of unrelated responsibilities.

Bundling data and behavior correctly is the mechanism by which we achieve high cohesion.

Types of Cohesion (From Worst to Best)
Type	Description	Example	Quality
Coincidental	Elements are randomly grouped	UtilityClass with unrelated functions	❌ Worst
Logical	Elements do similar things but on different data	AllValidatorsInOneClass	❌ Poor
Temporal	Elements are grouped by when they execute	StartupInitializer doing unrelated setup	⚠️ Weak
Procedural	Elements are steps in a procedure	ProcessingPipeline with coupled steps	⚠️ Moderate
Communicational	Elements operate on the same data	Report class generating multiple reports from same data	✅ Good
Sequential	Output of one element is input to next	DataTransformer pipeline	✅ Good
Functional	All elements contribute to a single, well-defined task	Parser class parsing only one format	✅ Best

Cohesion and bundling:

When data and behavior are properly bundled, classes naturally achieve communicational or functional cohesion:

All methods operate on the same data (communicational)
All elements contribute to a single domain responsibility (functional)

Anemic models create coincidental or logical cohesion: the entity class groups data coincidentally, while service classes group behaviors logically but not by the data they operate on.

Cohesion Heuristic

What Belongs Together? Design Heuristics

Deciding what data and behavior to bundle together requires judgment. Here are practical heuristics for making these decisions:

Heuristics for Data-Behavior Bundling

•The Information Expert Principle — Assign responsibility to the class that has the information needed to fulfill it. If Order has items and prices, Order should calculate the total. Not a calculator service.
•The Actor Principle — Group data and behavior by the real-world entity it models. An Order, a Customer, a Product—these are your actors. Their real-world operations hint at class methods.
•The Change Together Principle — If data and behavior change together (for the same reasons, at the same times), they belong together. Item prices and total calculation rules change together—bundle them.
•The Coupled Access Pattern — If certain data is always accessed by certain operations, bundle them. If startTime and endTime are always accessed by isActive() and getDuration(), they belong in the same class.
•The Invariant Principle — If an invariant ("total equals sum of item prices") must be maintained, the data involved and the operations that enforce it must be together.

information_expert.ts
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
// Applying the Information Expert Principle
 
// ❌ WRONG: External calculation
class Product {
    name: string;
    price: number;
    taxCategory: string;
}
 
class TaxCalculator {
    calculateTax(product: Product): number {
        // TaxCalculator needs to know about Product's internals
        switch (product.taxCategory) {
            case 'food': return product.price * 0.0;
            case 'luxury': return product.price * 0.20;
            default: return product.price * 0.10;
        }
    }
}
 
// ✅ CORRECT: Product is the information expert
class Product {
    private name: string;
    private price: number;
    private taxRate: number; // Internalized from taxCategory
    
    constructor(name: string, price: number, taxCategory: TaxCategory) {
        this.name = name;
        this.price = price;
        this.taxRate = TaxCategory.toRate(taxCategory);
    }
    
    // Product knows its own tax—it has all needed information
    calculateTax(): number {
        return this.price * this.taxRate;
    }
    
    getPriceWithTax(): number {
        return this.price + this.calculateTax();
    }
}

Boundaries are not always obvious:

Some decisions require deeper analysis:

Cross-cutting concerns like logging and security don't belong in domain objects—use aspect-oriented techniques or decorators.
Coordination logic that orchestrates multiple objects belongs in application services, not domain entities.
Infrastructure concerns (database, network) should be injected as dependencies, not bundled with domain data.

The goal is not to cram everything into domain classes, but to ensure that domain behavior lives with domain data. Technical infrastructure remains separate.

Tell, Don't Ask: The Complementary Principle

Data-behavior bundling naturally leads to the Tell, Don't Ask principle—a design heuristic that reinforces good encapsulation:

Tell objects what to do; don't ask them for data and make decisions externally.

ask_pattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// ❌ ASK: Query then decide externally
 
function processPayment(order: Order) {
    // ASK for status
    if (order.getStatus() === 'pending') {
        // ASK for total
        const total = order.getTotal();
        // External decision-making
        if (total > 0) {
            paymentGateway.charge(total);
            // TELL order what we decided
            order.setStatus('paid');
        }
    }
}

tell_pattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// ✅ TELL: Let the object decide
 
function processPayment(order: Order) {
    // TELL order to accept payment
    // Order decides if this is valid
    order.acceptPayment(paymentGateway);
    // Order encapsulates its own rules
}
 
// Inside Order class:
acceptPayment(gateway: PaymentGateway) {
    if (this.status !== 'pending') {
        throw new InvalidStateError();
    }
    gateway.charge(this.getTotal());
    this.status = 'paid';
}

Why Tell, Don't Ask matters:

Encapsulates decisions — The decision "can I be paid?" lives inside Order, not scattered across callers.
Prevents duplication — Every caller would have to duplicate the status-checking logic in the Ask pattern.
Enables evolution — If the rules for accepting payment change (e.g., add fraud checks), only Order needs updating.
Reduces temporal coupling — In the Ask pattern, callers must call methods in the right order. In Tell, the object controls the sequence.

Note: This doesn't mean getters are forbidden. Sometimes you legitimately need to display data. But if you're getting data to make a decision, ask if that decision should live inside the object.

The Litmus Test

Bundling in Practice: A Case Study

Let's work through a realistic example of designing bundled classes. Consider a Subscription system where users subscribe to plans with billing cycles.

Initial requirements:

Users have subscriptions to plans
Plans have prices and billing intervals (monthly/yearly)
Subscriptions can be active, paused, cancelled, or expired
Users can upgrade/downgrade plans
Billing calculates the next charge date and prorated amounts

subscription_domain.ts
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
128
129
130
131
132
133
134
135
136
137
138
// A well-bundled Subscription class
 
class Subscription {
    private readonly id: string;
    private readonly userId: string;
    private plan: Plan;
    private status: SubscriptionStatus;
    private startDate: Date;
    private currentPeriodEnd: Date;
    private pausedAt: Date | null = null;
    
    constructor(id: string, userId: string, plan: Plan) {
        this.id = id;
        this.userId = userId;
        this.plan = plan;
        this.status = SubscriptionStatus.ACTIVE;
        this.startDate = new Date();
        this.currentPeriodEnd = this.plan.calculateNextBillingDate(this.startDate);
    }
    
    // ===== Domain Behaviors (bundled with data) =====
    
    changePlan(newPlan: Plan, billingMode: BillingMode): PlanChangeResult {
        this.ensureCanModify();
        
        const prorationData = this.calculateProration(newPlan, billingMode);
        const previousPlan = this.plan;
        
        this.plan = newPlan;
        this.currentPeriodEnd = newPlan.calculateNextBillingDate(new Date());
        
        return new PlanChangeResult(
            previousPlan,
            newPlan,
            prorationData.creditAmount,
            prorationData.chargeAmount
        );
    }
    
    pause(reason: PauseReason): void {
        this.ensureActive();
        this.status = SubscriptionStatus.PAUSED;
        this.pausedAt = new Date();
    }
    
    resume(): void {
        if (this.status !== SubscriptionStatus.PAUSED) {
            throw new InvalidStateError("Can only resume paused subscriptions");
        }
        
        // Extend the period by the pause duration
        const pauseDuration = Date.now() - this.pausedAt!.getTime();
        this.currentPeriodEnd = new Date(
            this.currentPeriodEnd.getTime() + pauseDuration
        );
        
        this.status = SubscriptionStatus.ACTIVE;
        this.pausedAt = null;
    }
    
    cancel(immediate: boolean = false): CancellationResult {
        this.ensureCanModify();
        
        if (immediate) {
            this.status = SubscriptionStatus.CANCELLED;
            return new CancellationResult(new Date(), this.calculateRefund());
        }
        
        // Schedule cancellation at period end
        this.status = SubscriptionStatus.PENDING_CANCELLATION;
        return new CancellationResult(this.currentPeriodEnd, 0);
    }
    
    renew(): void {
        if (!this.isRenewable()) {
            throw new InvalidStateError("Subscription is not renewable");
        }
        this.currentPeriodEnd = this.plan.calculateNextBillingDate(
            this.currentPeriodEnd
        );
        this.status = SubscriptionStatus.ACTIVE;
    }
    
    // ===== Private Helpers (internal logic) =====
    
    private ensureActive(): void {
        if (this.status !== SubscriptionStatus.ACTIVE) {
            throw new InvalidStateError(
                `Operation requires active subscription, current: ${this.status}`
            );
        }
    }
    
    private ensureCanModify(): void {
        const modifiableStatuses = [
            SubscriptionStatus.ACTIVE,
            SubscriptionStatus.PAUSED
        ];
        if (!modifiableStatuses.includes(this.status)) {
            throw new InvalidStateError("Subscription cannot be modified");
        }
    }
    
    private calculateProration(newPlan: Plan, mode: BillingMode): ProrationData {
        const daysRemaining = this.getDaysRemainingInPeriod();
        const totalDays = this.getPeriodLengthDays();
        const fraction = daysRemaining / totalDays;
        
        const currentCredit = this.plan.price * fraction;
        const newCharge = mode === BillingMode.IMMEDIATE 
            ? newPlan.price 
            : newPlan.price * fraction;
            
        return { creditAmount: currentCredit, chargeAmount: newCharge };
    }
    
    private calculateRefund(): number {
        const fraction = this.getDaysRemainingInPeriod() / this.getPeriodLengthDays();
        return this.plan.price * fraction;
    }
    
    // ===== Query Methods (controlled access) =====
    
    isActive(): boolean {
        return this.status === SubscriptionStatus.ACTIVE;
    }
    
    isRenewable(): boolean {
        return [
            SubscriptionStatus.ACTIVE,
            SubscriptionStatus.PAUSED
        ].includes(this.status);
    }
    
    getDaysRemainingInPeriod(): number { /* ... */ }
    getPeriodLengthDays(): number { /* ... */ }
    getCurrentPlan(): Plan { return this.plan; }
}

Notice how the design embodies bundling:

All subscription data (status, plan, dates) is private
All subscription operations (changePlan, pause, resume, cancel, renew) are methods
Invariants ("can't pause a cancelled subscription") are enforced internally
Complex calculations (proration, refunds) live inside the class
External code tells the subscription what to do (subscription.changePlan(newPlan)), not how

An anemic version would expose all fields and put SubscriptionService.changePlan(subscription, newPlan) elsewhere—losing all these benefits.

Summary: Bundling Data and Behavior

We've explored the first pillar of encapsulation in depth. Here are the essential takeaways:

Key Takeaways

•Data and behavior have natural affinity — Operations that always need certain data, or data that only makes sense with certain operations, belong together in a class.
•Anemic domain models are an anti-pattern — Separating data into entities and behavior into services creates procedural code disguised as OO, losing all encapsulation benefits.
•Rich domain models bundle properly — Domain logic lives inside domain entities. Entities are self-sufficient, enforcing their own invariants.
•Cohesion is the goal — Proper bundling achieves functional or communicational cohesion. All elements work together toward a single responsibility.
•Use the Information Expert principle — Assign behavior to the class that has the information needed for it.
•Tell, Don't Ask reinforces bundling — Instead of querying state externally and deciding, tell objects what to do and let them decide.

What's next:

Page Complete

2 / 4