System Design (HLD)Other Essential Design Principles

Law of Demeter

LevelIntermediate

Duration60 mins

TopicOther Essential Design Principles

3 / 4

Method Chains and Demeter

The Great Chain Debate

"But wait," you might say, "if the Law of Demeter limits method chaining, how do I explain this perfectly reasonable code?"

const result = users
    .filter(user => user.isActive())
    .map(user => user.getEmail())
    .sort()
    .join(", ");

This has four dots. According to the "one dot rule," this should be a catastrophic LoD violation. Yet it's idiomatic, well-designed code found in production systems everywhere.

The confusion arises from an oversimplified understanding of LoD. The principle isn't about counting dots—it's about whether you're reaching through objects to access their internals. Understanding this distinction is crucial for applying LoD correctly without abandoning useful patterns.

What You Will Learn

This page clarifies the relationship between method chaining and the Law of Demeter. You'll learn to distinguish between chains that violate LoD (object graph navigation) and chains that don't (fluent interfaces, transformations, builders). By the end, you'll have precise criteria for evaluating any chain you encounter.

The Core Distinction: Navigation vs Transformation

The key to understanding method chains and LoD lies in distinguishing between two fundamentally different types of chains:

Navigation Chains traverse an object graph, moving from one object to another, accessing internal structure. Each step reveals implementation details about how objects are composed. These chains violate LoD.

Transformation Chains apply operations to data, where each step returns a result that flows to the next operation. They don't navigate internal structure; they process values. These chains don't violate LoD.

The visual similarity between these chains is superficial. Their semantics are completely different.

Navigation Chains (LoD Violation)

•Each step accesses a different object
•Reveals internal structure
•Creates coupling to multiple types
•Changes in any type break the chain
•Asking "give me your X" repeatedly

Transformation Chains (LoD Compliant)

•Each step transforms the value
•Hides implementation, exposes operations
•Coupling is to the operation contract
•Steps are independent and composable
•Saying "do this to X, then that"

chain-distinction.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
// NAVIGATION CHAIN — LoD Violation
// Each method returns a DIFFERENT OBJECT that we then interrogate
const city = order
    .getCustomer()    // Returns Customer (different type)
    .getAddress()     // Returns Address (different type)
    .getCity();       // Returns City (different type)
 
// We've exposed: Order has Customer, Customer has Address, Address has City
// We're coupled to: Order, Customer, Address, City
 
 
// TRANSFORMATION CHAIN — LoD Compliant
// Each method returns the RESULT of an operation on the same value
const result = text
    .trim()           // Returns trimmed string
    .toLowerCase()    // Returns lowercased string  
    .split(" ")       // Returns array of words
    .filter(w => w)   // Returns filtered array
    .join("-");       // Returns joined string
 
// We've exposed: nothing about internal structure
// We're coupled to: string and array operations
 
 
// THE CRITICAL DIFFERENCE
// Navigation: we're getting to objects INSIDE other objects
// Transformation: we're applying operations to VALUES

The Litmus Test

Ask yourself: "Am I getting from A to B to C (navigation), or am I applying operation1, then operation2, then operation3 to a value (transformation)?" Navigation violates LoD; transformation doesn't.

Fluent Interfaces — The "Returns This" Pattern

Fluent interfaces are a design pattern where methods return this (the current object), enabling method chaining for configuration or command sequences. They create long chains but don't violate LoD because every method call is still on the same object.

When you see:

builder.setName("Alice").setAge(30).setEmail("alice@example.com").build();

You might count four dots and suspect an LoD violation. But look closer:

builder.setName("Alice") → returns builder
builder.setAge(30) → returns builder
builder.setEmail(...) → returns builder
builder.build() → returns the built object

Every intermediate call is to the same object — your original builder. You're not navigating into other objects; you're configuring the one object you have.

fluent-interface-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
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// ✅ FLUENT INTERFACE — Not an LoD violation
// Every method returns 'this', so we're always talking to the same object
 
class QueryBuilder {
    private selectClauses: string[] = [];
    private fromTable: string = "";
    private whereClauses: string[] = [];
    private orderByClause: string = "";
    private limitValue: number | null = null;
 
    select(...columns: string[]): this {
        this.selectClauses.push(...columns);
        return this;  // Returns the same QueryBuilder
    }
 
    from(table: string): this {
        this.fromTable = table;
        return this;  // Returns the same QueryBuilder
    }
 
    where(condition: string): this {
        this.whereClauses.push(condition);
        return this;  // Returns the same QueryBuilder
    }
 
    orderBy(column: string, direction: "ASC" | "DESC" = "ASC"): this {
        this.orderByClause = `${column} ${direction}`;
        return this;  // Returns the same QueryBuilder
    }
 
    limit(count: number): this {
        this.limitValue = count;
        return this;  // Returns the same QueryBuilder
    }
 
    build(): string {
        // Finally builds and returns the SQL string
        let sql = `SELECT ${this.selectClauses.join(", ")} FROM ${this.fromTable}`;
        if (this.whereClauses.length > 0) {
            sql += ` WHERE ${this.whereClauses.join(" AND ")}`;
        }
        if (this.orderByClause) {
            sql += ` ORDER BY ${this.orderByClause}`;
        }
        if (this.limitValue !== null) {
            sql += ` LIMIT ${this.limitValue}`;
        }
        return sql;
    }
}
 
// Usage — long chain, but only one object is involved
const query = new QueryBuilder()
    .select("id", "name", "email")
    .from("users")
    .where("active = true")
    .where("created_at > '2024-01-01'")
    .orderBy("created_at", "DESC")
    .limit(10)
    .build();

Why Fluent Interfaces Don't Violate LoD

The Law of Demeter says you can call methods on objects you directly have. In a fluent interface, you have the builder object. Every chained call is still on that same builder object (because each method returns this). You're not navigating to new objects; you're repeatedly calling methods on your direct friend.

Common Fluent Interface Patterns

•Builders — Configuring complex object construction step by step
•Query builders — Building database queries, API requests, GraphQL queries
•Test data builders — Creating test fixtures with readable configuration
•Configuration DSLs — Setting up frameworks, routers, dependency injection
•Assertion libraries — Chai, FluentAssertions, AssertJ chains
•Request/Response pipelines — Express middleware, HTTP client configuration

Collection Processing Chains

Collection processing with methods like filter(), map(), reduce(), sort(), and flatMap() creates chains that look like LoD violations but aren't. Each method returns a new collection (or a final value), not an internal component object.

The key insight: You're not navigating structure; you're transforming data. Each step operates on the output of the previous step, not on an internal property of the previous step.

collection-processing.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// ✅ COLLECTION PROCESSING — Not an LoD violation
// Each method transforms the collection and returns a new collection
 
// Processing a list of orders
const highValueCustomerEmails = orders
    .filter(order => order.getTotal() > 1000)    // Returns filtered Order[]
    .map(order => order.getCustomer())           // Returns Customer[] 🤔 Wait...
    .filter(customer => customer.isActive())     // Returns filtered Customer[]
    .map(customer => customer.getEmail())        // Returns string[]
    .filter((email, index, self) =>              // Unique emails
        self.indexOf(email) === index)
    .sort();                                      // Returns sorted string[]
 
// IMPORTANT NUANCE: 
// - `order.getCustomer()` could be an LoD concern if you then dig into Customer
// - But we're EXTRACTING data for processing, not navigating for manipulation
// - The result is a flat list of emails, not an object graph
 
// This is the difference between:
// ❌ order.getCustomer().getAddress().getCity() — navigating through structure
// ✅ orders.map(o => o.getCustomerEmail()) — extracting data for processing

The Nuanced Case:

Collection chains can contain LoD violations. Consider:

// This chain contains an LoD violation inside the map
orders.map(order => order.getCustomer().getAddress().getCity());

The collection chain itself (.map()) isn't the problem. The content of the lambda (order.getCustomer().getAddress().getCity()) is the problem. This is an LoD violation wrapped in collection processing.

The fix:

// Better: ask Order for what you need
orders.map(order => order.getShippingCity());

Now the collection processing is clean, and Order handles its internal structure.

Watch the Lambda Contents

Collection chains are LoD-compliant for the chain itself, but violations can hide inside the lambdas. Always evaluate what happens inside filter(), map(), and similar methods — that's where navigation violations lurk.

Optional and Null-Safe Chains

Optional types (like Java's Optional, Kotlin's nullable types, TypeScript's optional chaining) create chains for handling null safely. These require careful analysis — they can be either LoD-compliant or violating, depending on what's being chained.

Optional chaining for transformation: When you use Optional to apply transformations to a value that might be absent, you're not violating LoD. You're wrapping operations in null-safety.

Optional chaining for navigation: When you use Optional to safely navigate through an object graph, you're still navigating — the Optional just makes the null-checking prettier. This is still an LoD violation.

optional-chains.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
// ✅ OPTIONAL FOR TRANSFORMATION — Not an LoD violation
// We're applying transformations to a value, handling absence gracefully
 
function formatUserName(user: User | null): string {
    return Optional.ofNullable(user)
        .map(u => u.getName())
        .map(name => name.toUpperCase())
        .map(name => `User: ${name}`)
        .orElse("Unknown User");
}
 
// Each .map() transforms the value if present
// We're not navigating structure, we're processing a value
 
 
// ❌ OPTIONAL FOR NAVIGATION — Still an LoD violation!
// We're using Optional to navigate safely through structure
 
function getShippingCity(order: Order | null): string {
    return Optional.ofNullable(order)
        .map(o => o.getCustomer())      // Navigation to Customer
        .map(c => c.getAddress())        // Navigation to Address
        .map(a => a.getCity())           // Navigation to City
        .map(city => city.getName())     // Navigation to City's name
        .orElse("Unknown");
}
 
// This is cleaner than nested null checks, but STILL couples us to:
// Order -> Customer -> Address -> City -> name
// Optional doesn't change the LoD violation — it just makes it null-safe
 
 
// ✅ THE FIX — Push navigation to the object that owns structure
function getShippingCity(order: Order | null): string {
    return Optional.ofNullable(order)
        .map(o => o.getShippingCityName())  // Order handles its internals
        .orElse("Unknown");
}

typescript-optional-chaining.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// TypeScript's optional chaining (?.) has the same consideration
 
// ❌ Optional chaining used for navigation — still LoD violation
const cityName = order?.customer?.address?.city?.name ?? "Unknown";
 
// Prettier than:
// const cityName = order && order.customer && order.customer.address 
//     && order.customer.address.city && order.customer.address.city.name 
//     || "Unknown";
 
// But STILL couples to the entire structure
 
 
// ✅ Optional chaining on a single level — LoD compliant
const cityName = order?.getShippingCityName() ?? "Unknown";
 
// Order handles the internal navigation; we just handle order's absence

Syntax Doesn't Change Semantics

Optional wrappers and null-safe operators make null-checking elegant, but they don't change the coupling. If you're navigating through a?.b?.c?.d, you're coupled to all four levels regardless of syntax. The question is always: "Am I reaching into internal structure?"

Promise and Async Chains

Promise chains (.then().then().catch()) and their async/await equivalents create another form of chaining that people sometimes confuse with LoD violations. Promise chains are transformation chains — each step receives the previous step's result and produces a new result.

The Promise itself is a container for an eventual value. Chaining .then() calls applies transformations to that eventual value. You're not navigating object structure; you're defining a pipeline of operations.

promise-chains.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
// ✅ PROMISE CHAIN — Not an LoD violation
// Each .then() transforms the result, creating a pipeline
 
async function processUserOrder(userId: string): Promise<Receipt> {
    return fetchUser(userId)                          // Promise<User>
        .then(user => validateUserStatus(user))       // Promise<ValidatedUser>
        .then(user => createOrder(user))              // Promise<Order>
        .then(order => processPayment(order))         // Promise<PaymentResult>
        .then(payment => generateReceipt(payment))    // Promise<Receipt>
        .catch(error => handleError(error));          // Promise<Receipt>
}
 
// We're defining a pipeline: fetch → validate → create → pay → receipt
// Each step's output feeds the next step's input
// This is transformation, not navigation
 
 
// ❌ BUT: LoD violations can hide INSIDE the .then() callbacks
 
async function getCustomerCity(orderId: string): Promise<string> {
    return fetchOrder(orderId)
        .then(order => order.getCustomer())           // Navigation
        .then(customer => customer.getAddress())       // Navigation
        .then(address => address.getCity())            // Navigation
        .then(city => city.getName());                 // Navigation
}
 
// The Promise chain itself is fine
// The CONTENT of each .then() creates LoD violations
 
 
// ✅ FIX: Keep promise chain, eliminate internal navigation
 
async function getCustomerCity(orderId: string): Promise<string> {
    return fetchOrder(orderId)
        .then(order => order.getShippingCityName());  // Order handles internals
}

Async/Await Doesn't Change the Analysis

Using async/await instead of .then() changes syntax but not semantics. If your async function navigates through objects (const city = (await getOrder()).customer.address.city), it's still an LoD violation. The await syntax just makes the control flow linear.

Precise Criteria for Evaluating Any Chain

Let's consolidate our understanding into a precise checklist for evaluating any method chain. These criteria distinguish LoD-violating chains from acceptable ones.

Chain Evaluation Checklist

•What types are involved? If each method returns a different type that you then access methods on, you're likely navigating. If methods return the same type (fluent) or transformed values (processing), you're likely not violating LoD.
•Are you accessing internal structure? If you're getting to objects that are components of other objects (Order's Customer, Customer's Address), you're exposing structure. If you're transforming values, you're not exposing structure.
•Would refactoring break you? If another object reorganizes its internal fields, would your chain break? If yes, you're coupled to structure — LoD violation. If no, you're coupled to interface — LoD compliant.
•Are you interrogating or commanding? If you're asking for pieces so you can decide what to do, you're likely violating. If you're telling objects to do things and they return results, you're likely compliant.
•Could you test this with a simple mock? If you need to mock an entire object graph (mock A returns mock B returns mock C...), you're violating LoD. If you can mock one thing and test the chain, you're compliant.

Quick Reference: Common Chain Patterns
Pattern	LoD Compliant?	Reason
a.getB().getC().getD()	❌ No	Navigation through object graph
builder.setX().setY().setZ().build()	✅ Yes	Fluent interface, returns `this`
list.filter().map().reduce()	✅ Yes	Collection transformation pipeline
text.trim().toLowerCase().split()	✅ Yes	Value transformation chain
optional.map().filter().orElse()	✅ Yes	Optional transformation
promise.then().then().catch()	✅ Yes	Async transformation pipeline
a?.b?.c?.d	❌ No	Navigation with null-safety (still navigation)
result.data.user.profile.name	❌ No	Property navigation through structure
Observable.pipe(map(), filter(), tap())	✅ Yes	Reactive stream transformation

evaluation-examples.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
// Apply the checklist to real examples
 
// Example 1: a.getB().getC().doSomething()
// 1. Types: A → B → C → result (different types) ❌
// 2. Structure: B is inside A, C is inside B ❌
// 3. Refactoring: if B stops containing C, this breaks ❌
// 4. Interrogating: we're getting B, getting C ❌
// 5. Testing: need to mock A, B, C ❌
// VERDICT: LoD violation ❌
 
 
// Example 2: queryBuilder.select().from().where().build()
// 1. Types: QB → QB → QB → QB → Result (same until build) ✅
// 2. Structure: we're configuring, not accessing internals ✅
// 3. Refactoring: QB internal changes don't affect chain ✅
// 4. Commanding: we're telling QB to configure itself ✅
// 5. Testing: mock just queryBuilder ✅
// VERDICT: LoD compliant ✅
 
 
// Example 3: users.filter(u => u.isActive()).map(u => u.getEmail())
// 1. Types: User[] → User[] → string[] (collections) ✅
// 2. Structure: not accessing internal structure ✅
// 3. Refactoring: User can change how it stores email ✅
// 4. Commanding: telling collection to transform ✅
// 5. Testing: mock User array easily ✅
// VERDICT: LoD compliant ✅
 
 
// Example 4: apiResponse.data.results[0].metadata.tags
// 1. Types: Response → Data → Results → Item → Metadata → Tags ❌
// 2. Structure: exposing deep response structure ❌
// 3. Refactoring: API response change breaks this ❌
// 4. Interrogating: navigating into response structure ❌
// 5. Testing: need to construct entire response shape ❌
// VERDICT: LoD violation ❌

The External API Challenge

A common question arises with external APIs that return deeply nested data structures: "How do I follow LoD when the API gives me response.data.results[0].user.profile.address.city?"

External APIs present a unique challenge. You can't refactor a third-party API to be LoD-compliant. But you can contain the navigation to a single point in your codebase.

external-api-handling.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
// ❌ PROBLEM: LoD violations spread throughout codebase
// Every component that uses the API navigates its structure
 
// In UserService.ts
const userName = apiResponse.data.user.profile.name;
 
// In AddressValidator.ts  
const city = apiResponse.data.user.profile.address.city;
 
// In NotificationService.ts
const email = apiResponse.data.user.contactInfo.email;
 
// Every file knows the API response structure
// API changes require updates everywhere
 
 
// ✅ SOLUTION: Adapter/Anti-Corruption Layer
// Create an adapter that isolates API structure knowledge
 
// Define the domain model your code wants to work with
interface UserData {
    readonly name: string;
    readonly email: string;
    readonly city: string;
}
 
// Adapter class contains ALL navigation in ONE place
class ExternalApiAdapter {
    parseUserResponse(response: ExternalApiResponse): UserData {
        // All structure navigation is here and ONLY here
        const rawUser = response.data.user;
        
        return {
            name: rawUser.profile.name,
            email: rawUser.contactInfo.email,
            city: rawUser.profile.address.city,
        };
    }
}
 
// Rest of your codebase works with clean UserData
// In UserService.ts
const userName = userData.name;  // Clean!
 
// In AddressValidator.ts
const city = userData.city;  // Clean!
 
// In NotificationService.ts
const email = userData.email;  // Clean!
 
// API response structure change? Only ExternalApiAdapter needs updating

Anti-Corruption Layer Benefits

•Single point of change — API response changes affect one file
•Domain-appropriate models — Your code works with models that fit your needs, not the API's structure
•Testability — Mock UserData, not complex API response shapes
•Type safety — Adapter can validate/transform data as needed
•Decoupling — Swap APIs by swapping adapters; business logic unchanged

The Anti-Corruption Layer Pattern

This approach is formalized as the Anti-Corruption Layer pattern in Domain-Driven Design. It creates a boundary between your domain and external systems, translating external models into your internal models. The "corruption" being prevented is external structure polluting your domain code.

Refactoring Problematic Chains

When you identify an LoD-violating chain, how do you fix it? Here are systematic refactoring strategies for common scenarios.

Strategy 1: Tell, Don't Ask

•Instead of navigating to an object to perform an action, tell your direct object what you need
•Push behavior to the object that owns the data
•Transform a.getB().getC().doSomething() into a.doSomethingWithC()

tell-dont-ask-refactor.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Before: navigating to send notification
order.getCustomer().getContactInfo().getEmail()...
 
// After: telling order to handle notification
order.sendConfirmationNotification();
 
// Order internally:
class Order {
    sendConfirmationNotification(): void {
        this.customer.notifyOfOrder(this);
    }
}
 
// Customer internally:
class Customer {
    notifyOfOrder(order: Order): void {
        this.notificationService.send(
            this.contactInfo.getEmail(),
            this.createOrderMessage(order)
        );
    }
}

Strategy 2: Add Delegation Methods

•For read operations, create a method that returns what callers need
•Hide the navigation inside the object that owns the structure
•Transform a.getB().getC().getValue() into a.getCValue()

delegation-refactor.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
// Before: caller navigates to get shipping zone
const zone = order.getCustomer().getAddress().getCity().getShippingZone();
 
// After: Order exposes a delegation method
const zone = order.getShippingZone();
 
// Implementation distributed appropriately:
class Order {
    getShippingZone(): string {
        return this.customer.getShippingZone();
    }
}
 
class Customer {
    getShippingZone(): string {
        return this.address.getShippingZone();
    }
}
 
class Address {
    getShippingZone(): string {
        return this.city.getShippingZone();
    }
}

Strategy 3: Introduce Parameter Object

•When navigation extracts multiple values, create a dedicated data object
•Let the owning object build this object from its internals
•Transform scattered gets into a single cohesive response

parameter-object-refactor.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
// Before: caller extracts multiple values through navigation
const email = order.getCustomer().getContactInfo().getEmail();
const name = order.getCustomer().getProfile().getName();
const address = order.getCustomer().getAddress().getFormatted();
sendConfirmation(email, name, address);
 
// After: Order provides a consolidated confirmation data object
interface ConfirmationRecipient {
    email: string;
    name: string;
    address: string;
}
 
class Order {
    getConfirmationRecipient(): ConfirmationRecipient {
        return this.customer.getConfirmationDetails();
    }
}
 
class Customer {
    getConfirmationDetails(): ConfirmationRecipient {
        return {
            email: this.contactInfo.getEmail(),
            name: this.profile.getName(),
            address: this.address.getFormatted(),
        };
    }
}
 
// Caller is clean
const recipient = order.getConfirmationRecipient();
sendConfirmation(recipient);

Summary: Method Chains and LoD

Method chains aren't inherently bad. The question is whether you're navigating through object internals (LoD violation) or transforming values through a pipeline (LoD compliant). Fluent interfaces, collection processing, and promise chains typically don't violate LoD. Object graph navigation does — regardless of how elegantly it's written.

Summary — Chains Done Right

Key Takeaways

•Navigation vs Transformation — Chains that navigate through object internals violate LoD. Chains that transform values don't. This is the fundamental distinction.
•Fluent interfaces are compliant — When methods return this, you're always talking to the same object. Multi-dot fluent chains are not LoD violations.
•Collection processing is compliant — filter(), map(), reduce() transform collections. The chain itself is fine; watch what happens inside the lambdas.
•Optional/null-safe chains can go either way — Optional is a container that can hold navigation violations just as easily as transformations. Evaluate what's being chained, not that Optional is used.
•Promise chains are transformation chains — Each .then() receives and transforms the previous result. LoD violations can hide inside .then() callbacks.
•External APIs need anti-corruption layers — You can't refactor third-party APIs, but you can isolate navigation to adapter classes.
•Refactoring strategies exist — "Tell, Don't Ask," delegation methods, and parameter objects transform LoD-violating chains into compliant code.

Looking Ahead

We've clarified when method chains violate LoD and when they don't. The final page of this module addresses applying Demeter appropriately — understanding when LoD applies, when it might be relaxed, and how to balance LoD with other design concerns.

3 / 4

Loading learning content...

System Design (HLD)Other Essential Design Principles

Law of Demeter

LevelIntermediate

Duration60 mins

TopicOther Essential Design Principles

3 / 4

Method Chains and Demeter

The Great Chain Debate

"But wait," you might say, "if the Law of Demeter limits method chaining, how do I explain this perfectly reasonable code?"

const result = users
    .filter(user => user.isActive())
    .map(user => user.getEmail())
    .sort()
    .join(", ");

This has four dots. According to the "one dot rule," this should be a catastrophic LoD violation. Yet it's idiomatic, well-designed code found in production systems everywhere.

What You Will Learn

The Core Distinction: Navigation vs Transformation

The key to understanding method chains and LoD lies in distinguishing between two fundamentally different types of chains:

The visual similarity between these chains is superficial. Their semantics are completely different.

Navigation Chains (LoD Violation)

•Each step accesses a different object
•Reveals internal structure
•Creates coupling to multiple types
•Changes in any type break the chain
•Asking "give me your X" repeatedly

Transformation Chains (LoD Compliant)

•Each step transforms the value
•Hides implementation, exposes operations
•Coupling is to the operation contract
•Steps are independent and composable
•Saying "do this to X, then that"

chain-distinction.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
// NAVIGATION CHAIN — LoD Violation
// Each method returns a DIFFERENT OBJECT that we then interrogate
const city = order
    .getCustomer()    // Returns Customer (different type)
    .getAddress()     // Returns Address (different type)
    .getCity();       // Returns City (different type)
 
// We've exposed: Order has Customer, Customer has Address, Address has City
// We're coupled to: Order, Customer, Address, City
 
 
// TRANSFORMATION CHAIN — LoD Compliant
// Each method returns the RESULT of an operation on the same value
const result = text
    .trim()           // Returns trimmed string
    .toLowerCase()    // Returns lowercased string  
    .split(" ")       // Returns array of words
    .filter(w => w)   // Returns filtered array
    .join("-");       // Returns joined string
 
// We've exposed: nothing about internal structure
// We're coupled to: string and array operations
 
 
// THE CRITICAL DIFFERENCE
// Navigation: we're getting to objects INSIDE other objects
// Transformation: we're applying operations to VALUES

The Litmus Test

Ask yourself: "Am I getting from A to B to C (navigation), or am I applying operation1, then operation2, then operation3 to a value (transformation)?" Navigation violates LoD; transformation doesn't.

Fluent Interfaces — The "Returns This" Pattern

When you see:

builder.setName("Alice").setAge(30).setEmail("alice@example.com").build();

You might count four dots and suspect an LoD violation. But look closer:

builder.setName("Alice") → returns builder
builder.setAge(30) → returns builder
builder.setEmail(...) → returns builder
builder.build() → returns the built object

Every intermediate call is to the same object — your original builder. You're not navigating into other objects; you're configuring the one object you have.

fluent-interface-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
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// ✅ FLUENT INTERFACE — Not an LoD violation
// Every method returns 'this', so we're always talking to the same object
 
class QueryBuilder {
    private selectClauses: string[] = [];
    private fromTable: string = "";
    private whereClauses: string[] = [];
    private orderByClause: string = "";
    private limitValue: number | null = null;
 
    select(...columns: string[]): this {
        this.selectClauses.push(...columns);
        return this;  // Returns the same QueryBuilder
    }
 
    from(table: string): this {
        this.fromTable = table;
        return this;  // Returns the same QueryBuilder
    }
 
    where(condition: string): this {
        this.whereClauses.push(condition);
        return this;  // Returns the same QueryBuilder
    }
 
    orderBy(column: string, direction: "ASC" | "DESC" = "ASC"): this {
        this.orderByClause = `${column} ${direction}`;
        return this;  // Returns the same QueryBuilder
    }
 
    limit(count: number): this {
        this.limitValue = count;
        return this;  // Returns the same QueryBuilder
    }
 
    build(): string {
        // Finally builds and returns the SQL string
        let sql = `SELECT ${this.selectClauses.join(", ")} FROM ${this.fromTable}`;
        if (this.whereClauses.length > 0) {
            sql += ` WHERE ${this.whereClauses.join(" AND ")}`;
        }
        if (this.orderByClause) {
            sql += ` ORDER BY ${this.orderByClause}`;
        }
        if (this.limitValue !== null) {
            sql += ` LIMIT ${this.limitValue}`;
        }
        return sql;
    }
}
 
// Usage — long chain, but only one object is involved
const query = new QueryBuilder()
    .select("id", "name", "email")
    .from("users")
    .where("active = true")
    .where("created_at > '2024-01-01'")
    .orderBy("created_at", "DESC")
    .limit(10)
    .build();

Why Fluent Interfaces Don't Violate LoD

Common Fluent Interface Patterns

•Builders — Configuring complex object construction step by step
•Query builders — Building database queries, API requests, GraphQL queries
•Test data builders — Creating test fixtures with readable configuration
•Configuration DSLs — Setting up frameworks, routers, dependency injection
•Assertion libraries — Chai, FluentAssertions, AssertJ chains
•Request/Response pipelines — Express middleware, HTTP client configuration

Collection Processing Chains

The key insight: You're not navigating structure; you're transforming data. Each step operates on the output of the previous step, not on an internal property of the previous step.

collection-processing.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// ✅ COLLECTION PROCESSING — Not an LoD violation
// Each method transforms the collection and returns a new collection
 
// Processing a list of orders
const highValueCustomerEmails = orders
    .filter(order => order.getTotal() > 1000)    // Returns filtered Order[]
    .map(order => order.getCustomer())           // Returns Customer[] 🤔 Wait...
    .filter(customer => customer.isActive())     // Returns filtered Customer[]
    .map(customer => customer.getEmail())        // Returns string[]
    .filter((email, index, self) =>              // Unique emails
        self.indexOf(email) === index)
    .sort();                                      // Returns sorted string[]
 
// IMPORTANT NUANCE: 
// - `order.getCustomer()` could be an LoD concern if you then dig into Customer
// - But we're EXTRACTING data for processing, not navigating for manipulation
// - The result is a flat list of emails, not an object graph
 
// This is the difference between:
// ❌ order.getCustomer().getAddress().getCity() — navigating through structure
// ✅ orders.map(o => o.getCustomerEmail()) — extracting data for processing

The Nuanced Case:

Collection chains can contain LoD violations. Consider:

// This chain contains an LoD violation inside the map
orders.map(order => order.getCustomer().getAddress().getCity());

The fix:

// Better: ask Order for what you need
orders.map(order => order.getShippingCity());

Now the collection processing is clean, and Order handles its internal structure.

Watch the Lambda Contents

Optional and Null-Safe Chains

Optional chaining for transformation: When you use Optional to apply transformations to a value that might be absent, you're not violating LoD. You're wrapping operations in null-safety.

optional-chains.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
// ✅ OPTIONAL FOR TRANSFORMATION — Not an LoD violation
// We're applying transformations to a value, handling absence gracefully
 
function formatUserName(user: User | null): string {
    return Optional.ofNullable(user)
        .map(u => u.getName())
        .map(name => name.toUpperCase())
        .map(name => `User: ${name}`)
        .orElse("Unknown User");
}
 
// Each .map() transforms the value if present
// We're not navigating structure, we're processing a value
 
 
// ❌ OPTIONAL FOR NAVIGATION — Still an LoD violation!
// We're using Optional to navigate safely through structure
 
function getShippingCity(order: Order | null): string {
    return Optional.ofNullable(order)
        .map(o => o.getCustomer())      // Navigation to Customer
        .map(c => c.getAddress())        // Navigation to Address
        .map(a => a.getCity())           // Navigation to City
        .map(city => city.getName())     // Navigation to City's name
        .orElse("Unknown");
}
 
// This is cleaner than nested null checks, but STILL couples us to:
// Order -> Customer -> Address -> City -> name
// Optional doesn't change the LoD violation — it just makes it null-safe
 
 
// ✅ THE FIX — Push navigation to the object that owns structure
function getShippingCity(order: Order | null): string {
    return Optional.ofNullable(order)
        .map(o => o.getShippingCityName())  // Order handles its internals
        .orElse("Unknown");
}

typescript-optional-chaining.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// TypeScript's optional chaining (?.) has the same consideration
 
// ❌ Optional chaining used for navigation — still LoD violation
const cityName = order?.customer?.address?.city?.name ?? "Unknown";
 
// Prettier than:
// const cityName = order && order.customer && order.customer.address 
//     && order.customer.address.city && order.customer.address.city.name 
//     || "Unknown";
 
// But STILL couples to the entire structure
 
 
// ✅ Optional chaining on a single level — LoD compliant
const cityName = order?.getShippingCityName() ?? "Unknown";
 
// Order handles the internal navigation; we just handle order's absence

Syntax Doesn't Change Semantics

Promise and Async Chains

promise-chains.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
// ✅ PROMISE CHAIN — Not an LoD violation
// Each .then() transforms the result, creating a pipeline
 
async function processUserOrder(userId: string): Promise<Receipt> {
    return fetchUser(userId)                          // Promise<User>
        .then(user => validateUserStatus(user))       // Promise<ValidatedUser>
        .then(user => createOrder(user))              // Promise<Order>
        .then(order => processPayment(order))         // Promise<PaymentResult>
        .then(payment => generateReceipt(payment))    // Promise<Receipt>
        .catch(error => handleError(error));          // Promise<Receipt>
}
 
// We're defining a pipeline: fetch → validate → create → pay → receipt
// Each step's output feeds the next step's input
// This is transformation, not navigation
 
 
// ❌ BUT: LoD violations can hide INSIDE the .then() callbacks
 
async function getCustomerCity(orderId: string): Promise<string> {
    return fetchOrder(orderId)
        .then(order => order.getCustomer())           // Navigation
        .then(customer => customer.getAddress())       // Navigation
        .then(address => address.getCity())            // Navigation
        .then(city => city.getName());                 // Navigation
}
 
// The Promise chain itself is fine
// The CONTENT of each .then() creates LoD violations
 
 
// ✅ FIX: Keep promise chain, eliminate internal navigation
 
async function getCustomerCity(orderId: string): Promise<string> {
    return fetchOrder(orderId)
        .then(order => order.getShippingCityName());  // Order handles internals
}

Async/Await Doesn't Change the Analysis

Precise Criteria for Evaluating Any Chain

Let's consolidate our understanding into a precise checklist for evaluating any method chain. These criteria distinguish LoD-violating chains from acceptable ones.

Chain Evaluation Checklist

•What types are involved? If each method returns a different type that you then access methods on, you're likely navigating. If methods return the same type (fluent) or transformed values (processing), you're likely not violating LoD.
•Are you accessing internal structure? If you're getting to objects that are components of other objects (Order's Customer, Customer's Address), you're exposing structure. If you're transforming values, you're not exposing structure.
•Would refactoring break you? If another object reorganizes its internal fields, would your chain break? If yes, you're coupled to structure — LoD violation. If no, you're coupled to interface — LoD compliant.
•Are you interrogating or commanding? If you're asking for pieces so you can decide what to do, you're likely violating. If you're telling objects to do things and they return results, you're likely compliant.
•Could you test this with a simple mock? If you need to mock an entire object graph (mock A returns mock B returns mock C...), you're violating LoD. If you can mock one thing and test the chain, you're compliant.

Quick Reference: Common Chain Patterns
Pattern	LoD Compliant?	Reason
a.getB().getC().getD()	❌ No	Navigation through object graph
builder.setX().setY().setZ().build()	✅ Yes	Fluent interface, returns `this`
list.filter().map().reduce()	✅ Yes	Collection transformation pipeline
text.trim().toLowerCase().split()	✅ Yes	Value transformation chain
optional.map().filter().orElse()	✅ Yes	Optional transformation
promise.then().then().catch()	✅ Yes	Async transformation pipeline
a?.b?.c?.d	❌ No	Navigation with null-safety (still navigation)
result.data.user.profile.name	❌ No	Property navigation through structure
Observable.pipe(map(), filter(), tap())	✅ Yes	Reactive stream transformation

evaluation-examples.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
// Apply the checklist to real examples
 
// Example 1: a.getB().getC().doSomething()
// 1. Types: A → B → C → result (different types) ❌
// 2. Structure: B is inside A, C is inside B ❌
// 3. Refactoring: if B stops containing C, this breaks ❌
// 4. Interrogating: we're getting B, getting C ❌
// 5. Testing: need to mock A, B, C ❌
// VERDICT: LoD violation ❌
 
 
// Example 2: queryBuilder.select().from().where().build()
// 1. Types: QB → QB → QB → QB → Result (same until build) ✅
// 2. Structure: we're configuring, not accessing internals ✅
// 3. Refactoring: QB internal changes don't affect chain ✅
// 4. Commanding: we're telling QB to configure itself ✅
// 5. Testing: mock just queryBuilder ✅
// VERDICT: LoD compliant ✅
 
 
// Example 3: users.filter(u => u.isActive()).map(u => u.getEmail())
// 1. Types: User[] → User[] → string[] (collections) ✅
// 2. Structure: not accessing internal structure ✅
// 3. Refactoring: User can change how it stores email ✅
// 4. Commanding: telling collection to transform ✅
// 5. Testing: mock User array easily ✅
// VERDICT: LoD compliant ✅
 
 
// Example 4: apiResponse.data.results[0].metadata.tags
// 1. Types: Response → Data → Results → Item → Metadata → Tags ❌
// 2. Structure: exposing deep response structure ❌
// 3. Refactoring: API response change breaks this ❌
// 4. Interrogating: navigating into response structure ❌
// 5. Testing: need to construct entire response shape ❌
// VERDICT: LoD violation ❌

The External API Challenge

A common question arises with external APIs that return deeply nested data structures: "How do I follow LoD when the API gives me response.data.results[0].user.profile.address.city?"

External APIs present a unique challenge. You can't refactor a third-party API to be LoD-compliant. But you can contain the navigation to a single point in your codebase.

external-api-handling.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
// ❌ PROBLEM: LoD violations spread throughout codebase
// Every component that uses the API navigates its structure
 
// In UserService.ts
const userName = apiResponse.data.user.profile.name;
 
// In AddressValidator.ts  
const city = apiResponse.data.user.profile.address.city;
 
// In NotificationService.ts
const email = apiResponse.data.user.contactInfo.email;
 
// Every file knows the API response structure
// API changes require updates everywhere
 
 
// ✅ SOLUTION: Adapter/Anti-Corruption Layer
// Create an adapter that isolates API structure knowledge
 
// Define the domain model your code wants to work with
interface UserData {
    readonly name: string;
    readonly email: string;
    readonly city: string;
}
 
// Adapter class contains ALL navigation in ONE place
class ExternalApiAdapter {
    parseUserResponse(response: ExternalApiResponse): UserData {
        // All structure navigation is here and ONLY here
        const rawUser = response.data.user;
        
        return {
            name: rawUser.profile.name,
            email: rawUser.contactInfo.email,
            city: rawUser.profile.address.city,
        };
    }
}
 
// Rest of your codebase works with clean UserData
// In UserService.ts
const userName = userData.name;  // Clean!
 
// In AddressValidator.ts
const city = userData.city;  // Clean!
 
// In NotificationService.ts
const email = userData.email;  // Clean!
 
// API response structure change? Only ExternalApiAdapter needs updating

Anti-Corruption Layer Benefits

•Single point of change — API response changes affect one file
•Domain-appropriate models — Your code works with models that fit your needs, not the API's structure
•Testability — Mock UserData, not complex API response shapes
•Type safety — Adapter can validate/transform data as needed
•Decoupling — Swap APIs by swapping adapters; business logic unchanged

The Anti-Corruption Layer Pattern

Refactoring Problematic Chains

When you identify an LoD-violating chain, how do you fix it? Here are systematic refactoring strategies for common scenarios.

Strategy 1: Tell, Don't Ask

•Instead of navigating to an object to perform an action, tell your direct object what you need
•Push behavior to the object that owns the data
•Transform a.getB().getC().doSomething() into a.doSomethingWithC()

tell-dont-ask-refactor.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Before: navigating to send notification
order.getCustomer().getContactInfo().getEmail()...
 
// After: telling order to handle notification
order.sendConfirmationNotification();
 
// Order internally:
class Order {
    sendConfirmationNotification(): void {
        this.customer.notifyOfOrder(this);
    }
}
 
// Customer internally:
class Customer {
    notifyOfOrder(order: Order): void {
        this.notificationService.send(
            this.contactInfo.getEmail(),
            this.createOrderMessage(order)
        );
    }
}

Strategy 2: Add Delegation Methods

•For read operations, create a method that returns what callers need
•Hide the navigation inside the object that owns the structure
•Transform a.getB().getC().getValue() into a.getCValue()

delegation-refactor.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
// Before: caller navigates to get shipping zone
const zone = order.getCustomer().getAddress().getCity().getShippingZone();
 
// After: Order exposes a delegation method
const zone = order.getShippingZone();
 
// Implementation distributed appropriately:
class Order {
    getShippingZone(): string {
        return this.customer.getShippingZone();
    }
}
 
class Customer {
    getShippingZone(): string {
        return this.address.getShippingZone();
    }
}
 
class Address {
    getShippingZone(): string {
        return this.city.getShippingZone();
    }
}

Strategy 3: Introduce Parameter Object

•When navigation extracts multiple values, create a dedicated data object
•Let the owning object build this object from its internals
•Transform scattered gets into a single cohesive response

parameter-object-refactor.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
// Before: caller extracts multiple values through navigation
const email = order.getCustomer().getContactInfo().getEmail();
const name = order.getCustomer().getProfile().getName();
const address = order.getCustomer().getAddress().getFormatted();
sendConfirmation(email, name, address);
 
// After: Order provides a consolidated confirmation data object
interface ConfirmationRecipient {
    email: string;
    name: string;
    address: string;
}
 
class Order {
    getConfirmationRecipient(): ConfirmationRecipient {
        return this.customer.getConfirmationDetails();
    }
}
 
class Customer {
    getConfirmationDetails(): ConfirmationRecipient {
        return {
            email: this.contactInfo.getEmail(),
            name: this.profile.getName(),
            address: this.address.getFormatted(),
        };
    }
}
 
// Caller is clean
const recipient = order.getConfirmationRecipient();
sendConfirmation(recipient);

Summary: Method Chains and LoD

Summary — Chains Done Right

Key Takeaways

•Navigation vs Transformation — Chains that navigate through object internals violate LoD. Chains that transform values don't. This is the fundamental distinction.
•Fluent interfaces are compliant — When methods return this, you're always talking to the same object. Multi-dot fluent chains are not LoD violations.
•Collection processing is compliant — filter(), map(), reduce() transform collections. The chain itself is fine; watch what happens inside the lambdas.
•Optional/null-safe chains can go either way — Optional is a container that can hold navigation violations just as easily as transformations. Evaluate what's being chained, not that Optional is used.
•Promise chains are transformation chains — Each .then() receives and transforms the previous result. LoD violations can hide inside .then() callbacks.
•External APIs need anti-corruption layers — You can't refactor third-party APIs, but you can isolate navigation to adapter classes.
•Refactoring strategies exist — "Tell, Don't Ask," delegation methods, and parameter objects transform LoD-violating chains into compliant code.

Looking Ahead

3 / 4