System Design (LLD)Dependency Injection Anti-Patterns

DI Anti-Patterns and Best Practices

LevelAdvanced

Duration75 mins

TopicDependency Injection Anti-Patterns

2 / 4

Circular Dependencies

The Initialization Order Nightmare

Your application worked flawlessly in development. Then you deploy to production and encounter a cryptic error: Maximum call stack size exceeded or Cannot read property of undefined during startup. Hours of debugging reveal the cause: ServiceA needs ServiceB to be constructed, but ServiceB needs ServiceA to be constructed. Neither can exist without the other. The IoC container enters an infinite loop trying to resolve this paradox.

This is a circular dependency—a cycle in your dependency graph where A depends on B depends on C depends on A. Unlike constructor over-injection, which is immediately visible in the code, circular dependencies can hide across multiple classes and packages, emerging only at runtime as stack overflows or mysterious null references.

Why Circular Dependencies Are Dangerous

Circular dependencies violate the fundamental principle that dependencies should form a Directed Acyclic Graph (DAG). When cycles exist, there's no valid ordering for construction. IoC containers may fail loudly, silently corrupt state, or enter infinite loops—depending on implementation.

What You Will Learn

By the end of this page, you will understand how circular dependencies arise, detect them before they cause production failures, apply systematic strategies to break cycles, and recognize the design flaws that circular dependencies reveal.

Understanding Circular Dependencies

A circular dependency exists when class A depends on class B, and class B (directly or indirectly) depends on class A. The cycle can involve any number of classes:

Direct cycle: A → B → A
Indirect cycle: A → B → C → D → A

When using constructor injection exclusively, circular dependencies make instantiation impossible. To create A, you need B. To create B, you need A. Neither can be created first.

CircularDependency.ts (Anti-Pattern)
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
// 🚨 ANTI-PATTERN: Direct Circular Dependency
// Neither class can be instantiated - each requires the other
 
class AuthenticationService {
    constructor(
        private readonly userService: UserService
    ) {}
    
    authenticate(token: string): AuthenticatedUser {
        const userId = this.decodeToken(token);
        return this.userService.getUser(userId); // Needs UserService
    }
    
    private decodeToken(token: string): string { /* ... */ }
}
 
class UserService {
    constructor(
        private readonly authService: AuthenticationService
    ) {}
    
    getUser(userId: string): User {
        // ... lookup user
    }
    
    sendPasswordResetEmail(userId: string): void {
        const user = this.getUser(userId);
        const resetToken = this.authService./* ??? */; // Needs AuthenticationService
        // ... send email with token
    }
}
 
// ❌ Impossible to construct:
// const auth = new AuthenticationService(???);  // Need UserService first
// const user = new UserService(???);            // Need AuthenticationService first

The Indirect Cycle—Harder to Detect:

More insidiously, cycles can span many classes. Consider this chain that seems reasonable in isolation:

Dependency Chain

OrderService 
    → PaymentService 
        → FraudDetectionService 
            → UserRiskProfileService 
                → OrderHistoryService 
                    → OrderService  // CYCLE DETECTED!
 
Each individual dependency seems reasonable. But together, they form an
unresolvable cycle that may span multiple packages and teams.

The Hidden Monster

Indirect cycles are the most dangerous because no single developer sees the full picture. Team A adds OrderService → PaymentService. Team B adds FraudDetectionService → UserRiskProfileService. Team C closes the loop without realizing it. The system explodes in production.

How Circular Dependencies Manifest

Different IoC containers and runtime environments handle circular dependencies differently. Understanding these behaviors helps you diagnose issues faster:

Circular Dependency Behaviors by Environment
Environment/Container	Behavior	Symptoms
Node.js require()	Module returns partial exports	Undefined or incomplete objects at runtime; hard-to-trace bugs
Angular DI	Detection and error at bootstrap	Clear error message: 'Circular dependency detected'
Spring Framework	Attempts proxy-based resolution	May work but indicates design flaw; occasional cryptic failures
NestJS	Detection with clear error	Error message identifies the cycle path
Manual construction	Stack overflow or infinite loop	Recursive constructor calls until stack exhausted
Lazy resolution	Deferred construction allows startup	Null references when lazy property accessed before initialization

Manifestation Example in Node.js:

Node.js has notoriously subtle circular dependency behavior. When modules circularly require each other, you get partially initialized exports:

Node.js Circular Dependency Surprise
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// file: moduleA.ts
import { functionB } from './moduleB';
 
export function functionA() {
    console.log('A called');
    functionB();
}
 
// This runs at import time, BEFORE moduleB finishes loading
functionA();
 
// file: moduleB.ts  
import { functionA } from './moduleA';
 
export function functionB() {
    console.log('B called');
    functionA(); // 💥 UNDEFINED! moduleA hasn't finished exporting yet
}
 
// Runtime error: functionA is not a function
// The error appears unrelated to circular deps, causing hours of confusion

The Silent Corruption

The worst manifestation isn't an error—it's silent corruption. Some containers 'resolve' cycles by injecting partially constructed objects or null proxies. Your code runs but operates on invalid state. These bugs are nearly impossible to diagnose without understanding the underlying circular dependency.

Root Causes of Circular Dependencies

Circular dependencies are always symptoms of deeper design problems. Understanding these root causes is essential for prevention and resolution:

Root Causes of Circular Dependencies

•Misplaced Responsibilities — Methods or data are in the wrong class. The cycle exists because one class contains functionality that belongs elsewhere.
•Missing Abstraction — Two concrete classes depend on each other when both should depend on a shared abstraction that neither implements.
•Bidirectional Communication Without Events — Classes need to communicate in both directions but use direct dependencies instead of event-driven patterns.
•God Classes Fragmented Incorrectly — A monolithic class was split, but the split didn't follow natural domain boundaries. The fragments still need each other.
•Layering Violations — Lower layers depend on upper layers when the inverse should be true. Business logic depends on UI; data layer depends on application layer.
•Convenience Over Architecture — Developers add a handy method to an existing class rather than creating proper infrastructure, inadvertently creating cycles.
•Aggregate Boundary Confusion — In DDD, aggregates reference each other directly instead of through IDs, creating coupling that leads to cycles.

Case Study: The Misplaced Responsibility

Revisiting our earlier example, the cycle exists because AuthenticationService has a method that should be in a different class:

AuthenticationService.authenticate() → needs user lookup → needs UserService
UserService.sendPasswordResetEmail() → needs token generation → needs AuthenticationService

But wait—why does UserService send emails? That's not a user management concern. And why does it generate reset tokens? Token generation is an authentication concern. The method is misplaced.

Misplaced Responsibility Analysis
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// The problem: sendPasswordResetEmail() doesn't belong in UserService
// It combines authentication (token), notification (email), and user lookup
 
// UserService should ONLY manage user data
// AuthenticationService should ONLY handle security tokens
// NotificationService should ONLY handle email/SMS/push
// PasswordResetService should orchestrate the three
 
// Current (broken):
UserService ─────────────────→ AuthenticationService
    ↑                               │
    └───────────────────────────────┘
    
// Proper design eliminates the cycle:
PasswordResetService → AuthenticationService
                    → UserService  
                    → NotificationService
 
// Each arrow is uni-directional. No cycles.

Detection Strategies

Waiting for production failures to reveal circular dependencies is catastrophically expensive. Implement these detection strategies to catch cycles early:

Detection Methods

•Static Analysis Tools — Use tools like Madge (JavaScript), ArchUnit (Java), NDepend (.NET), or deptrac (PHP) to analyze import graphs and detect cycles at build time.
•IDE Plugins — Many IDEs have plugins that visualize dependency graphs and highlight cycles. IntelliJ's 'Analyze Dependencies' is particularly powerful.
•IoC Container Diagnostics — Most containers have diagnostic modes that report potential issues. Enable these in CI pipelines.
•Custom Graph Analysis — For complex projects, write a script that parses import statements and runs cycle detection (topological sort failure).
•Unit Test Isolation — If a unit test requires complex initialization order or fails with 'not initialized' errors, investigate for cycles.
•Dependency Graph Visualization — Regular visualization of the dependency graph reveals cycles visually. Tools like Graphviz transform import data into images.

Madge CLI Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Using Madge to detect circular dependencies in a TypeScript project
 
# Install
npm install -g madge
 
# Detect circular dependencies
madge --circular --extensions ts src/
 
# Output when cycle found:
# Circular dependency found:
#   src/services/OrderService.ts ->
#   src/services/PaymentService.ts ->
#   src/services/FraudDetectionService.ts ->
#   src/services/UserRiskProfileService.ts ->
#   src/services/OrderHistoryService.ts ->
#   src/services/OrderService.ts
 
# Generate visual graph
madge --circular --image cycle-graph.svg src/
 
# This command should be in CI pipeline to fail builds with cycles

CI Integration Is Non-Negotiable

Add circular dependency detection to your CI pipeline. The few seconds of analysis time prevents hours or days of production debugging. Most tools return non-zero exit codes when cycles are found, making CI integration trivial.

Resolution Strategies: Breaking the Cycle

When you've identified a circular dependency, several strategies can break the cycle. Choose based on the root cause:

Strategy 1: Extract Shared Abstraction (Dependency Inversion)

When two classes depend on each other, often both should depend on a shared interface that neither owns:

Shared Abstraction Resolution
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
// 🚨 BEFORE: Circular - A and B depend on each other
class OrderProcessor {
    constructor(private inventory: InventoryManager) {}
    
    processOrder(order: Order) {
        if (this.inventory.checkAvailability(order.items)) {
            this.inventory.reserve(order.items);
        }
    }
}
 
class InventoryManager {
    constructor(private orderProcessor: OrderProcessor) {} // CYCLE!
    
    onStockReplenished(items: Item[]) {
        // Need to process pending orders when stock arrives
        // This creates the cycle
    }
}
 
// ✅ AFTER: Both depend on abstraction, no cycle
 
interface IStockObserver {
    onStockReplenished(items: Item[]): void;
}
 
interface IInventoryChecker {
    checkAvailability(items: OrderItem[]): boolean;
    reserve(items: OrderItem[]): void;
}
 
class OrderProcessor implements IStockObserver {
    constructor(private inventory: IInventoryChecker) {}
    
    processOrder(order: Order) {
        if (this.inventory.checkAvailability(order.items)) {
            this.inventory.reserve(order.items);
        }
    }
    
    onStockReplenished(items: Item[]) {
        // Handle pending orders
    }
}
 
class InventoryManager implements IInventoryChecker {
    private observers: IStockObserver[] = [];
    
    registerObserver(observer: IStockObserver) {
        this.observers.push(observer);
    }
    
    replenishStock(items: Item[]) {
        // ... update inventory
        this.observers.forEach(o => o.onStockReplenished(items));
    }
    
    checkAvailability(items: OrderItem[]): boolean { /* ... */ }
    reserve(items: OrderItem[]): void { /* ... */ }
}
 
// Wiring at composition root:
const inventory = new InventoryManager();
const orderProcessor = new OrderProcessor(inventory);
inventory.registerObserver(orderProcessor);
// No circular constructor dependency - observer registered post-construction

Strategy 2: Extract Mediator

When multiple classes need bidirectional communication, extract a mediator that knows about all parties:

Mediator Resolution
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
// ✅ GOOD: Mediator coordinates multiple participants
 
interface IParticipant {
    setMediator(mediator: IOrderMediator): void;
}
 
interface IOrderMediator {
    notify(sender: IParticipant, event: OrderEvent): void;
}
 
class OrderMediator implements IOrderMediator {
    constructor(
        private orderService: OrderService,
        private paymentService: PaymentService,
        private inventoryService: InventoryService
    ) {
        // Wire participants to use mediator
        this.orderService.setMediator(this);
        this.paymentService.setMediator(this);
        this.inventoryService.setMediator(this);
    }
    
    notify(sender: IParticipant, event: OrderEvent) {
        if (event.type === 'ORDER_PLACED') {
            this.inventoryService.reserve(event.items);
            this.paymentService.processPayment(event.payment);
        }
        if (event.type === 'PAYMENT_COMPLETED') {
            this.inventoryService.confirmReservation(event.orderId);
        }
        if (event.type === 'PAYMENT_FAILED') {
            this.inventoryService.releaseReservation(event.orderId);
            this.orderService.cancelOrder(event.orderId);
        }
    }
}
 
// Each service NO LONGER depends on the others
// All services depend only on IOrderMediator
// The MediaTOR depends on all services (one-directional)

Strategy 3: Use Domain Events

Replace synchronous method calls with asynchronous events. Classes publish events; other classes subscribe without knowing who publishes:

Domain Events Resolution
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
// ✅ GOOD: Event-driven communication breaks coupling
 
interface DomainEvent {
    type: string;
    timestamp: Date;
    payload: unknown;
}
 
class EventBus {
    private subscribers = new Map<string, Array<(event: DomainEvent) => void>>();
    
    subscribe(eventType: string, handler: (event: DomainEvent) => void) {
        // Register handler
    }
    
    publish(event: DomainEvent) {
        // Dispatch to all subscribers
    }
}
 
class UserService {
    constructor(private eventBus: EventBus) {
        // Subscribe to events, not to concrete services
        this.eventBus.subscribe('PasswordResetRequested', this.handlePasswordReset.bind(this));
    }
    
    private handlePasswordReset(event: DomainEvent) {
        // Handle event without knowing who published it
    }
}
 
class AuthenticationService {
    constructor(private eventBus: EventBus) {}
    
    requestPasswordReset(email: string) {
        const resetToken = this.generateResetToken();
        // Publish event without knowing who handles it
        this.eventBus.publish({
            type: 'PasswordResetRequested',
            timestamp: new Date(),
            payload: { email, resetToken }
        });
    }
}
 
// UserService and AuthenticationService only depend on EventBus
// No circular dependency possible

Strategy 4: Method Parameter Injection

When a dependency is only needed for one method, pass it as a parameter instead of a constructor dependency:

Method Parameter Injection
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: Constructor injection of rarely-used dependency creates cycle
class ReportGenerator {
    constructor(private dataService: DataService) {}
    
    generateReport(reportType: string, formatter: IFormatter) {
        // dataService only used occasionally
    }
}
 
// ✅ AFTER: Pass dependency when needed, not at construction
class ReportGenerator {
    // No DataService constructor dependency
    
    generateReport(
        reportType: string, 
        dataService: IDataService,  // Passed when called
        formatter: IFormatter
    ) {
        const data = dataService.getData(reportType);
        return formatter.format(data);
    }
}
 
// The caller provides dataService, which may break the cycle

Strategy Selection Guide

•Extract Shared Abstraction — When classes have genuine mutual dependency, both should depend on interfaces in a shared module.
•Extract Mediator — When multiple classes need complex interaction coordination.
•Domain Events — When communication is truly asynchronous or spans bounded contexts.
•Method Parameter Injection — When a dependency is used by only one or two methods.
•Lazy/Provider Injection — Last resort; delays construction but doesn't fix the design flaw.

Anti-Pattern: Lazy Resolution as a 'Fix'

Many IoC containers offer lazy resolution features (providers, factories, lazy proxies) that can technically 'solve' circular dependencies by deferring construction. This is almost always the wrong approach.

Lazy Resolution (Anti-Pattern)
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
// 🚨 ANTI-PATTERN: Using Lazy to mask circular dependency
 
class ServiceA {
    constructor(
        // Inject a factory/provider instead of the actual service
        private serviceBProvider: () => ServiceB  // Lazy!
    ) {}
    
    doSomething() {
        const serviceB = this.serviceBProvider(); // Resolved when needed
        serviceB.doSomethingElse();
    }
}
 
class ServiceB {
    constructor(
        private serviceAProvider: () => ServiceA  // Also lazy!
    ) {}
    
    doSomethingElse() {
        const serviceA = this.serviceAProvider();
        serviceA.doAnother();
    }
}
 
// This "works" but the fundamental design problem remains:
// - A and B are still coupled
// - Testing is still awkward
// - Reasoning about the system is still difficult
// - You've just hidden the cycle behind indirection

Why Lazy Resolution Is Wrong

•Masks the symptom, not the cause
•The design flaw remains
•Testing still requires complex setup
•Code is harder to understand
•May create runtime null references
•Adds indirection complexity

When Lazy Resolution Is Acceptable

•Temporary fix while proper refactoring is planned
•Integration with legacy code you cannot modify
•Rare edge cases with no cleaner solution
•Performance optimization (not for cycle breaking)
•Never as the primary solution

Lazy Resolution Is Technical Debt

If you use lazy resolution to break a cycle, treat it as technical debt. Document it. Create a ticket for proper refactoring. Set a deadline. Lazy resolution buys time; it doesn't solve problems.

Architectural Prevention

The best circular dependency is one that never exists. These architectural practices prevent cycles from forming:

Architectural Prevention Strategies

•Layered Architecture with Strict Direction — Dependencies flow in one direction: UI → Application → Domain → Infrastructure adapters. Never upward.
•Bounded Contexts — Each context is self-contained. Cross-context communication uses events or APIs, not direct dependencies.
•Package by Feature, Not Layer — When related code is together, cross-feature dependencies become obvious and discouraged.
•Interface Segregation — Small, focused interfaces are less likely to create cycles than broad interfaces that invite misuse.
•Aggregate Roots Only Reference by ID — In DDD, aggregates never hold object references to other aggregates. Only IDs.
•Event-Driven Communication — Prefer events over direct calls for cross-module communication. Events are inherently one-directional.
•Regular Dependency Analysis — Run cycle detection weekly. Track and trend the results. Celebrate when cycles decrease.

Healthy Dependency Direction
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
Healthy Layered Architecture (Dependencies Flow Downward):
 
┌─────────────────────────────────────────────────────────────┐
│                     PRESENTATION LAYER                       │
│              (Controllers, Views, View Models)               │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼ (depends on)
┌─────────────────────────────────────────────────────────────┐
│                     APPLICATION LAYER                        │
│               (Use Cases, Application Services)              │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼ (depends on)
┌─────────────────────────────────────────────────────────────┐
│                       DOMAIN LAYER                           │
│         (Entities, Value Objects, Domain Services)           │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼ (depends on)
┌─────────────────────────────────────────────────────────────┐
│                   INFRASTRUCTURE LAYER                       │
│     (Repositories Impl, External Services, Persistence)      │
└─────────────────────────────────────────────────────────────┘
 
📌 Key principle: Arrows only point DOWN. Never up.
📌 When you need to notify "up", use events or observer patterns.
📌 Interfaces for infrastructure live in DOMAIN layer (Dependency Inversion)

The Acyclic Dependencies Principle

The Acyclic Dependencies Principle (ADP) states that the dependency graph of packages must have no cycles. This principle applies at all scales—classes, packages, modules, and services. When you design new code, consciously ensure arrows only point in valid directions.

Summary: Circular Dependencies

Let's consolidate the key insights about circular dependencies:

Key Takeaways

•Circular dependencies violate the DAG principle — Dependencies must form a Directed Acyclic Graph. Cycles make construction order undefined.
•Indirect cycles are the most dangerous — They span classes and teams, hiding until production explosions.
•Root causes are always design flaws — Misplaced responsibilities, missing abstractions, or bidirectional coupling without proper patterns.
•Detect with static analysis in CI — Tools like Madge, ArchUnit, and NDepend catch cycles before deployment.
•Resolution requires proper design — Extract shared abstractions, use mediators, introduce events, or apply method injection.
•Lazy resolution is a band-aid, not a fix — It masks the symptom while preserving the design flaw. Use only temporarily.
•Prevention through architecture — Layered direction, bounded contexts, and event-driven patterns prevent cycles structurally.

What's Next:

Constructor over-injection and circular dependencies are the most obvious DI anti-patterns. Our next topic, captive dependencies, is subtler—it involves lifetime mismatches where a long-lived service captures a short-lived dependency, causing resource leaks and stale data. This anti-pattern is particularly insidious because systems can run for months before symptoms appear.

Page Complete

You now understand circular dependencies—the anti-pattern where classes create cycles in the dependency graph. You can detect them with tooling, resolve them with proper design patterns, and prevent them through architectural discipline. Next, we'll explore captive dependencies and lifetime management pitfalls.

2 / 4

Loading learning content...

System Design (LLD)Dependency Injection Anti-Patterns

DI Anti-Patterns and Best Practices

LevelAdvanced

Duration75 mins

TopicDependency Injection Anti-Patterns

2 / 4

Circular Dependencies

The Initialization Order Nightmare

Why Circular Dependencies Are Dangerous

What You Will Learn

Understanding Circular Dependencies

A circular dependency exists when class A depends on class B, and class B (directly or indirectly) depends on class A. The cycle can involve any number of classes:

Direct cycle: A → B → A
Indirect cycle: A → B → C → D → A

When using constructor injection exclusively, circular dependencies make instantiation impossible. To create A, you need B. To create B, you need A. Neither can be created first.

CircularDependency.ts (Anti-Pattern)
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
// 🚨 ANTI-PATTERN: Direct Circular Dependency
// Neither class can be instantiated - each requires the other
 
class AuthenticationService {
    constructor(
        private readonly userService: UserService
    ) {}
    
    authenticate(token: string): AuthenticatedUser {
        const userId = this.decodeToken(token);
        return this.userService.getUser(userId); // Needs UserService
    }
    
    private decodeToken(token: string): string { /* ... */ }
}
 
class UserService {
    constructor(
        private readonly authService: AuthenticationService
    ) {}
    
    getUser(userId: string): User {
        // ... lookup user
    }
    
    sendPasswordResetEmail(userId: string): void {
        const user = this.getUser(userId);
        const resetToken = this.authService./* ??? */; // Needs AuthenticationService
        // ... send email with token
    }
}
 
// ❌ Impossible to construct:
// const auth = new AuthenticationService(???);  // Need UserService first
// const user = new UserService(???);            // Need AuthenticationService first

The Indirect Cycle—Harder to Detect:

More insidiously, cycles can span many classes. Consider this chain that seems reasonable in isolation:

Dependency Chain

OrderService 
    → PaymentService 
        → FraudDetectionService 
            → UserRiskProfileService 
                → OrderHistoryService 
                    → OrderService  // CYCLE DETECTED!
 
Each individual dependency seems reasonable. But together, they form an
unresolvable cycle that may span multiple packages and teams.

The Hidden Monster

How Circular Dependencies Manifest

Different IoC containers and runtime environments handle circular dependencies differently. Understanding these behaviors helps you diagnose issues faster:

Circular Dependency Behaviors by Environment
Environment/Container	Behavior	Symptoms
Node.js require()	Module returns partial exports	Undefined or incomplete objects at runtime; hard-to-trace bugs
Angular DI	Detection and error at bootstrap	Clear error message: 'Circular dependency detected'
Spring Framework	Attempts proxy-based resolution	May work but indicates design flaw; occasional cryptic failures
NestJS	Detection with clear error	Error message identifies the cycle path
Manual construction	Stack overflow or infinite loop	Recursive constructor calls until stack exhausted
Lazy resolution	Deferred construction allows startup	Null references when lazy property accessed before initialization

Manifestation Example in Node.js:

Node.js has notoriously subtle circular dependency behavior. When modules circularly require each other, you get partially initialized exports:

Node.js Circular Dependency Surprise
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// file: moduleA.ts
import { functionB } from './moduleB';
 
export function functionA() {
    console.log('A called');
    functionB();
}
 
// This runs at import time, BEFORE moduleB finishes loading
functionA();
 
// file: moduleB.ts  
import { functionA } from './moduleA';
 
export function functionB() {
    console.log('B called');
    functionA(); // 💥 UNDEFINED! moduleA hasn't finished exporting yet
}
 
// Runtime error: functionA is not a function
// The error appears unrelated to circular deps, causing hours of confusion

The Silent Corruption

Root Causes of Circular Dependencies

Circular dependencies are always symptoms of deeper design problems. Understanding these root causes is essential for prevention and resolution:

Root Causes of Circular Dependencies

•Misplaced Responsibilities — Methods or data are in the wrong class. The cycle exists because one class contains functionality that belongs elsewhere.
•Missing Abstraction — Two concrete classes depend on each other when both should depend on a shared abstraction that neither implements.
•Bidirectional Communication Without Events — Classes need to communicate in both directions but use direct dependencies instead of event-driven patterns.
•God Classes Fragmented Incorrectly — A monolithic class was split, but the split didn't follow natural domain boundaries. The fragments still need each other.
•Layering Violations — Lower layers depend on upper layers when the inverse should be true. Business logic depends on UI; data layer depends on application layer.
•Convenience Over Architecture — Developers add a handy method to an existing class rather than creating proper infrastructure, inadvertently creating cycles.
•Aggregate Boundary Confusion — In DDD, aggregates reference each other directly instead of through IDs, creating coupling that leads to cycles.

Case Study: The Misplaced Responsibility

Revisiting our earlier example, the cycle exists because AuthenticationService has a method that should be in a different class:

AuthenticationService.authenticate() → needs user lookup → needs UserService
UserService.sendPasswordResetEmail() → needs token generation → needs AuthenticationService

But wait—why does UserService send emails? That's not a user management concern. And why does it generate reset tokens? Token generation is an authentication concern. The method is misplaced.

Misplaced Responsibility Analysis
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// The problem: sendPasswordResetEmail() doesn't belong in UserService
// It combines authentication (token), notification (email), and user lookup
 
// UserService should ONLY manage user data
// AuthenticationService should ONLY handle security tokens
// NotificationService should ONLY handle email/SMS/push
// PasswordResetService should orchestrate the three
 
// Current (broken):
UserService ─────────────────→ AuthenticationService
    ↑                               │
    └───────────────────────────────┘
    
// Proper design eliminates the cycle:
PasswordResetService → AuthenticationService
                    → UserService  
                    → NotificationService
 
// Each arrow is uni-directional. No cycles.

Detection Strategies

Waiting for production failures to reveal circular dependencies is catastrophically expensive. Implement these detection strategies to catch cycles early:

Detection Methods

•Static Analysis Tools — Use tools like Madge (JavaScript), ArchUnit (Java), NDepend (.NET), or deptrac (PHP) to analyze import graphs and detect cycles at build time.
•IDE Plugins — Many IDEs have plugins that visualize dependency graphs and highlight cycles. IntelliJ's 'Analyze Dependencies' is particularly powerful.
•IoC Container Diagnostics — Most containers have diagnostic modes that report potential issues. Enable these in CI pipelines.
•Custom Graph Analysis — For complex projects, write a script that parses import statements and runs cycle detection (topological sort failure).
•Unit Test Isolation — If a unit test requires complex initialization order or fails with 'not initialized' errors, investigate for cycles.
•Dependency Graph Visualization — Regular visualization of the dependency graph reveals cycles visually. Tools like Graphviz transform import data into images.

Madge CLI Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Using Madge to detect circular dependencies in a TypeScript project
 
# Install
npm install -g madge
 
# Detect circular dependencies
madge --circular --extensions ts src/
 
# Output when cycle found:
# Circular dependency found:
#   src/services/OrderService.ts ->
#   src/services/PaymentService.ts ->
#   src/services/FraudDetectionService.ts ->
#   src/services/UserRiskProfileService.ts ->
#   src/services/OrderHistoryService.ts ->
#   src/services/OrderService.ts
 
# Generate visual graph
madge --circular --image cycle-graph.svg src/
 
# This command should be in CI pipeline to fail builds with cycles

CI Integration Is Non-Negotiable

Resolution Strategies: Breaking the Cycle

When you've identified a circular dependency, several strategies can break the cycle. Choose based on the root cause:

Strategy 1: Extract Shared Abstraction (Dependency Inversion)

When two classes depend on each other, often both should depend on a shared interface that neither owns:

Shared Abstraction Resolution
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
// 🚨 BEFORE: Circular - A and B depend on each other
class OrderProcessor {
    constructor(private inventory: InventoryManager) {}
    
    processOrder(order: Order) {
        if (this.inventory.checkAvailability(order.items)) {
            this.inventory.reserve(order.items);
        }
    }
}
 
class InventoryManager {
    constructor(private orderProcessor: OrderProcessor) {} // CYCLE!
    
    onStockReplenished(items: Item[]) {
        // Need to process pending orders when stock arrives
        // This creates the cycle
    }
}
 
// ✅ AFTER: Both depend on abstraction, no cycle
 
interface IStockObserver {
    onStockReplenished(items: Item[]): void;
}
 
interface IInventoryChecker {
    checkAvailability(items: OrderItem[]): boolean;
    reserve(items: OrderItem[]): void;
}
 
class OrderProcessor implements IStockObserver {
    constructor(private inventory: IInventoryChecker) {}
    
    processOrder(order: Order) {
        if (this.inventory.checkAvailability(order.items)) {
            this.inventory.reserve(order.items);
        }
    }
    
    onStockReplenished(items: Item[]) {
        // Handle pending orders
    }
}
 
class InventoryManager implements IInventoryChecker {
    private observers: IStockObserver[] = [];
    
    registerObserver(observer: IStockObserver) {
        this.observers.push(observer);
    }
    
    replenishStock(items: Item[]) {
        // ... update inventory
        this.observers.forEach(o => o.onStockReplenished(items));
    }
    
    checkAvailability(items: OrderItem[]): boolean { /* ... */ }
    reserve(items: OrderItem[]): void { /* ... */ }
}
 
// Wiring at composition root:
const inventory = new InventoryManager();
const orderProcessor = new OrderProcessor(inventory);
inventory.registerObserver(orderProcessor);
// No circular constructor dependency - observer registered post-construction

Strategy 2: Extract Mediator

When multiple classes need bidirectional communication, extract a mediator that knows about all parties:

Mediator Resolution
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
// ✅ GOOD: Mediator coordinates multiple participants
 
interface IParticipant {
    setMediator(mediator: IOrderMediator): void;
}
 
interface IOrderMediator {
    notify(sender: IParticipant, event: OrderEvent): void;
}
 
class OrderMediator implements IOrderMediator {
    constructor(
        private orderService: OrderService,
        private paymentService: PaymentService,
        private inventoryService: InventoryService
    ) {
        // Wire participants to use mediator
        this.orderService.setMediator(this);
        this.paymentService.setMediator(this);
        this.inventoryService.setMediator(this);
    }
    
    notify(sender: IParticipant, event: OrderEvent) {
        if (event.type === 'ORDER_PLACED') {
            this.inventoryService.reserve(event.items);
            this.paymentService.processPayment(event.payment);
        }
        if (event.type === 'PAYMENT_COMPLETED') {
            this.inventoryService.confirmReservation(event.orderId);
        }
        if (event.type === 'PAYMENT_FAILED') {
            this.inventoryService.releaseReservation(event.orderId);
            this.orderService.cancelOrder(event.orderId);
        }
    }
}
 
// Each service NO LONGER depends on the others
// All services depend only on IOrderMediator
// The MediaTOR depends on all services (one-directional)

Strategy 3: Use Domain Events

Replace synchronous method calls with asynchronous events. Classes publish events; other classes subscribe without knowing who publishes:

Domain Events Resolution
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
// ✅ GOOD: Event-driven communication breaks coupling
 
interface DomainEvent {
    type: string;
    timestamp: Date;
    payload: unknown;
}
 
class EventBus {
    private subscribers = new Map<string, Array<(event: DomainEvent) => void>>();
    
    subscribe(eventType: string, handler: (event: DomainEvent) => void) {
        // Register handler
    }
    
    publish(event: DomainEvent) {
        // Dispatch to all subscribers
    }
}
 
class UserService {
    constructor(private eventBus: EventBus) {
        // Subscribe to events, not to concrete services
        this.eventBus.subscribe('PasswordResetRequested', this.handlePasswordReset.bind(this));
    }
    
    private handlePasswordReset(event: DomainEvent) {
        // Handle event without knowing who published it
    }
}
 
class AuthenticationService {
    constructor(private eventBus: EventBus) {}
    
    requestPasswordReset(email: string) {
        const resetToken = this.generateResetToken();
        // Publish event without knowing who handles it
        this.eventBus.publish({
            type: 'PasswordResetRequested',
            timestamp: new Date(),
            payload: { email, resetToken }
        });
    }
}
 
// UserService and AuthenticationService only depend on EventBus
// No circular dependency possible

Strategy 4: Method Parameter Injection

When a dependency is only needed for one method, pass it as a parameter instead of a constructor dependency:

Method Parameter Injection
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: Constructor injection of rarely-used dependency creates cycle
class ReportGenerator {
    constructor(private dataService: DataService) {}
    
    generateReport(reportType: string, formatter: IFormatter) {
        // dataService only used occasionally
    }
}
 
// ✅ AFTER: Pass dependency when needed, not at construction
class ReportGenerator {
    // No DataService constructor dependency
    
    generateReport(
        reportType: string, 
        dataService: IDataService,  // Passed when called
        formatter: IFormatter
    ) {
        const data = dataService.getData(reportType);
        return formatter.format(data);
    }
}
 
// The caller provides dataService, which may break the cycle

Strategy Selection Guide

•Extract Shared Abstraction — When classes have genuine mutual dependency, both should depend on interfaces in a shared module.
•Extract Mediator — When multiple classes need complex interaction coordination.
•Domain Events — When communication is truly asynchronous or spans bounded contexts.
•Method Parameter Injection — When a dependency is used by only one or two methods.
•Lazy/Provider Injection — Last resort; delays construction but doesn't fix the design flaw.

Anti-Pattern: Lazy Resolution as a 'Fix'

Lazy Resolution (Anti-Pattern)
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
// 🚨 ANTI-PATTERN: Using Lazy to mask circular dependency
 
class ServiceA {
    constructor(
        // Inject a factory/provider instead of the actual service
        private serviceBProvider: () => ServiceB  // Lazy!
    ) {}
    
    doSomething() {
        const serviceB = this.serviceBProvider(); // Resolved when needed
        serviceB.doSomethingElse();
    }
}
 
class ServiceB {
    constructor(
        private serviceAProvider: () => ServiceA  // Also lazy!
    ) {}
    
    doSomethingElse() {
        const serviceA = this.serviceAProvider();
        serviceA.doAnother();
    }
}
 
// This "works" but the fundamental design problem remains:
// - A and B are still coupled
// - Testing is still awkward
// - Reasoning about the system is still difficult
// - You've just hidden the cycle behind indirection

Why Lazy Resolution Is Wrong

•Masks the symptom, not the cause
•The design flaw remains
•Testing still requires complex setup
•Code is harder to understand
•May create runtime null references
•Adds indirection complexity

When Lazy Resolution Is Acceptable

•Temporary fix while proper refactoring is planned
•Integration with legacy code you cannot modify
•Rare edge cases with no cleaner solution
•Performance optimization (not for cycle breaking)
•Never as the primary solution

Lazy Resolution Is Technical Debt

If you use lazy resolution to break a cycle, treat it as technical debt. Document it. Create a ticket for proper refactoring. Set a deadline. Lazy resolution buys time; it doesn't solve problems.

Architectural Prevention

The best circular dependency is one that never exists. These architectural practices prevent cycles from forming:

Architectural Prevention Strategies

•Layered Architecture with Strict Direction — Dependencies flow in one direction: UI → Application → Domain → Infrastructure adapters. Never upward.
•Bounded Contexts — Each context is self-contained. Cross-context communication uses events or APIs, not direct dependencies.
•Package by Feature, Not Layer — When related code is together, cross-feature dependencies become obvious and discouraged.
•Interface Segregation — Small, focused interfaces are less likely to create cycles than broad interfaces that invite misuse.
•Aggregate Roots Only Reference by ID — In DDD, aggregates never hold object references to other aggregates. Only IDs.
•Event-Driven Communication — Prefer events over direct calls for cross-module communication. Events are inherently one-directional.
•Regular Dependency Analysis — Run cycle detection weekly. Track and trend the results. Celebrate when cycles decrease.

Healthy Dependency Direction
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
Healthy Layered Architecture (Dependencies Flow Downward):
 
┌─────────────────────────────────────────────────────────────┐
│                     PRESENTATION LAYER                       │
│              (Controllers, Views, View Models)               │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼ (depends on)
┌─────────────────────────────────────────────────────────────┐
│                     APPLICATION LAYER                        │
│               (Use Cases, Application Services)              │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼ (depends on)
┌─────────────────────────────────────────────────────────────┐
│                       DOMAIN LAYER                           │
│         (Entities, Value Objects, Domain Services)           │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼ (depends on)
┌─────────────────────────────────────────────────────────────┐
│                   INFRASTRUCTURE LAYER                       │
│     (Repositories Impl, External Services, Persistence)      │
└─────────────────────────────────────────────────────────────┘
 
📌 Key principle: Arrows only point DOWN. Never up.
📌 When you need to notify "up", use events or observer patterns.
📌 Interfaces for infrastructure live in DOMAIN layer (Dependency Inversion)

The Acyclic Dependencies Principle

Summary: Circular Dependencies

Let's consolidate the key insights about circular dependencies:

Key Takeaways

•Circular dependencies violate the DAG principle — Dependencies must form a Directed Acyclic Graph. Cycles make construction order undefined.
•Indirect cycles are the most dangerous — They span classes and teams, hiding until production explosions.
•Root causes are always design flaws — Misplaced responsibilities, missing abstractions, or bidirectional coupling without proper patterns.
•Detect with static analysis in CI — Tools like Madge, ArchUnit, and NDepend catch cycles before deployment.
•Resolution requires proper design — Extract shared abstractions, use mediators, introduce events, or apply method injection.
•Lazy resolution is a band-aid, not a fix — It masks the symptom while preserving the design flaw. Use only temporarily.
•Prevention through architecture — Layered direction, bounded contexts, and event-driven patterns prevent cycles structurally.

What's Next:

Page Complete

2 / 4