System Design (HLD)Dependency Injection Fundamentals

Dependency Injection Fundamentals

LevelIntermediate

Duration60 mins

TopicDependency Injection Fundamentals

2 / 5

Constructor Injection

The Gold Standard of Dependency Injection

Among the various dependency injection techniques, Constructor Injection stands as the most widely adopted, frequently recommended, and conceptually sound approach. It is the default choice of experienced engineers and the standard pattern in most DI frameworks.

The principle is elegantly simple: a class declares its dependencies as constructor parameters. The injector provides concrete implementations when instantiating the class. From that moment forward, the class is fully initialized and ready to perform its function.

This simplicity conceals profound implications for object design—implications for immutability, testability, documentation, and the very semantics of what it means for an object to be "ready." This page explores Constructor Injection in its entirety.

What You Will Learn

By the end of this page, you will master Constructor Injection mechanics, understand why it's preferred over alternatives, know how to handle edge cases like optional dependencies and constructor explosion, implement robust error handling, and apply industry patterns for production-quality DI.

Constructor Injection Mechanics

Constructor Injection follows a precise mechanical pattern:

Declare dependencies as constructor parameters — Each required collaborator becomes a constructor parameter, typically typed to an interface (abstraction).
Store dependencies as instance fields — The constructor assigns parameters to private, readonly fields for later use.
Object is ready upon construction — Once the constructor completes, the object possesses everything it needs to function. No further initialization required.
Injector provides concrete implementations — The calling code (composition root or DI container) supplies actual instances.

constructor-injection-anatomy.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
// ANATOMY OF CONSTRUCTOR INJECTION
 
// Step 1: Define abstractions (interfaces)
interface OrderRepository {
    save(order: Order): Promise<void>;
    findById(id: string): Promise<Order | null>;
    findByCustomer(customerId: string): Promise<Order[]>;
}
 
interface PaymentGateway {
    charge(payment: PaymentDetails): Promise<PaymentResult>;
    refund(transactionId: string, amount: Money): Promise<RefundResult>;
}
 
interface EventPublisher {
    publish<T extends DomainEvent>(event: T): Promise<void>;
}
 
// Step 2: Declare dependencies as constructor parameters
class OrderProcessingService {
    // Step 3: Store as private readonly fields
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly paymentGateway: PaymentGateway,
        private readonly eventPublisher: EventPublisher
    ) {
        // TypeScript's parameter properties handle field declaration
        // No explicit assignment needed with 'private readonly' syntax
    }
    
    // Step 4: Use dependencies in methods
    async processOrder(order: Order): Promise<ProcessingResult> {
        // All dependencies are guaranteed available
        const paymentResult = await this.paymentGateway.charge(
            order.paymentDetails
        );
        
        if (paymentResult.success) {
            order.markAsPaid(paymentResult.transactionId);
            await this.orderRepository.save(order);
            await this.eventPublisher.publish(
                new OrderPaidEvent(order.id, paymentResult.transactionId)
            );
            return ProcessingResult.success(order);
        }
        
        return ProcessingResult.paymentFailed(paymentResult.error);
    }
}

The constructor as a contract:

The constructor signature serves as an explicit contract. Anyone reading the code immediately knows:

Exactly what this class needs — The parameter list is a complete manifest
Types of collaborators required — Interfaces reveal expected capabilities
No hidden dependencies — Everything required is visible
Object state after construction — All fields are initialized, object is ready

This transparency is invaluable for code comprehension, testing, and maintenance.

Why Constructor Injection Is Preferred

Constructor Injection is the preferred DI technique for fundamental reasons rooted in object-oriented design principles. Let's examine each advantage in depth:

Fundamental Advantages

•Immutability — Dependencies stored in readonly/final fields cannot change after construction. The object's collaborators are fixed for its lifetime, eliminating an entire category of bugs related to changing dependencies mid-execution.
•Complete initialization — The object is fully functional immediately upon construction. There's no "partially initialized" state where some dependencies are present and others are missing.
•Explicit requirements — The constructor signature is a complete manifest of what the class needs. Dependencies are visible, not hidden in setters or service locators.
•Fail-fast construction — If dependencies are missing or invalid, construction fails immediately. You discover problems at startup, not when a method is called hours later.
•Easier testing — Mocks are injected through the constructor. No special reflection tricks or framework magic needed—just pass dependencies as arguments.
•Framework compatibility — Virtually every DI framework supports constructor injection as the primary mechanism. It's the universal pattern.

With Setter Injection

•Object exists in incomplete state after construction
•Setters might not all be called
•Dependencies can change mid-execution
•Methods must check if dependencies exist
•Temporal coupling: call order matters
•Thread-safety concerns with mutable fields

With Constructor Injection

•Object is complete and ready immediately
•All dependencies guaranteed present
•Dependencies are immutable
•Methods can assume dependencies exist
•No temporal coupling
•Thread-safe by design (immutable)

The Immutability Bonus

Immutable objects are inherently thread-safe. When dependencies cannot change after construction, concurrent access poses no risk of race conditions on the dependency references themselves. This "thread-safety for free" is a significant benefit in concurrent systems.

Null Safety, Validation, and Defensive Programming

A well-designed constructor validates its dependencies, failing fast if invalid inputs are provided. This defensive programming prevents subtle bugs from null or invalid dependencies surfacing at unexpected times.

The principle: If a dependency is required, verify it's not null/undefined immediately upon construction. Throw a descriptive error that pinpoints exactly which dependency is missing.

defensive-constructor.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
// ❌ NAIVE: Assumes dependencies are valid
class OrderService {
    constructor(
        private readonly repository: OrderRepository,
        private readonly logger: Logger
    ) { }
    
    // If repository is null, this throws cryptic error deep in call stack
    async getOrder(id: string): Promise<Order> {
        return await this.repository.findById(id);
        // TypeError: Cannot read property 'findById' of null
    }
}
 
// ✅ DEFENSIVE: Validates dependencies immediately
class OrderService {
    private readonly repository: OrderRepository;
    private readonly logger: Logger;
    
    constructor(repository: OrderRepository, logger: Logger) {
        if (!repository) {
            throw new Error("OrderService requires OrderRepository but received null/undefined");
        }
        if (!logger) {
            throw new Error("OrderService requires Logger but received null/undefined");
        }
        
        this.repository = repository;
        this.logger = logger;
    }
}
 
// ✅ EVEN BETTER: Create a utility for consistent validation
function requireDependency<T>(value: T | null | undefined, name: string): T {
    if (value === null || value === undefined) {
        throw new Error(`Required dependency '${name}' was not provided`);
    }
    return value;
}
 
class OrderService {
    private readonly repository: OrderRepository;
    private readonly logger: Logger;
    
    constructor(repository: OrderRepository, logger: Logger) {
        this.repository = requireDependency(repository, "OrderRepository");
        this.logger = requireDependency(logger, "Logger");
    }
}

Beyond null checks: semantic validation

Some dependencies require more than null checks. They might need semantic validation—verifying that the dependency is in a usable state:

semantic-validation.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
class DatabaseOrderRepository implements OrderRepository {
    constructor(private readonly connectionPool: ConnectionPool) {
        if (!connectionPool) {
            throw new Error("ConnectionPool is required");
        }
        
        // Semantic validation: is the pool actually usable?
        if (connectionPool.size === 0) {
            throw new Error("ConnectionPool must have at least one connection");
        }
        
        if (!connectionPool.isInitialized) {
            throw new Error("ConnectionPool must be initialized before injection");
        }
    }
}
 
// For configuration objects, validate structure
class EmailNotificationService {
    constructor(
        private readonly emailClient: EmailClient,
        private readonly config: EmailConfig
    ) {
        this.emailClient = requireDependency(emailClient, "EmailClient");
        
        // Validate config structure
        if (!config) {
            throw new Error("EmailConfig is required");
        }
        if (!config.fromAddress || !this.isValidEmail(config.fromAddress)) {
            throw new Error("EmailConfig.fromAddress must be a valid email");
        }
        if (!config.templatesPath) {
            throw new Error("EmailConfig.templatesPath is required");
        }
        
        this.config = config;
    }
    
    private isValidEmail(email: string): boolean {
        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
    }
}

Don't Over-Validate

Balance defensive programming with practicality. Validate what matters: null/undefined values, required configuration, and invariants that would cause cryptic failures. Don't add validation for unlikely scenarios that would never occur in a properly configured system—this adds noise without value.

Dealing with Many Dependencies (Constructor Explosion)

A common concern with Constructor Injection is "constructor explosion"—constructors with an unwieldy number of parameters:

// Constructor Explosion — a warning sign
class OrderProcessingService {
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly customerRepository: CustomerRepository,
        private readonly inventoryService: InventoryService,
        private readonly paymentGateway: PaymentGateway,
        private readonly shippingCalculator: ShippingCalculator,
        private readonly taxCalculator: TaxCalculator,
        private readonly discountEngine: DiscountEngine,
        private readonly emailNotifier: EmailNotifier,
        private readonly smsNotifier: SmsNotifier,
        private readonly analyticsTracker: AnalyticsTracker,
        private readonly auditLogger: AuditLogger,
        private readonly featureFlags: FeatureFlags
    ) { }
}

This is painful—but it's a feature, not a bug. The pain is signaling a design problem: this class has too many responsibilities.

Constructor Explosion as Design Feedback

Constructor Injection makes dependency problems visible. A long parameter list screams "I'm doing too much!" This visibility is valuable—it forces you to confront poor design rather than hiding it behind property injection or service locators.

Solutions to constructor explosion:

Don't hide the problem—solve it. There are several legitimate approaches:

1. Decompose the Class (Preferred)

•The class likely violates Single Responsibility Principle
•Extract cohesive groups of dependencies into separate classes
•Each smaller class takes fewer dependencies
•Compose the smaller classes to achieve the original functionality

decompose-class.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
// BEFORE: Giant class with many dependencies
class OrderProcessingService {
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly inventoryService: InventoryService,
        private readonly paymentGateway: PaymentGateway,
        private readonly shippingCalculator: ShippingCalculator,
        private readonly taxCalculator: TaxCalculator,
        private readonly discountEngine: DiscountEngine,
        private readonly emailNotifier: EmailNotifier,
        private readonly smsNotifier: SmsNotifier
    ) { }
}
 
// AFTER: Decomposed into focused classes
 
// Handles pricing concerns
class OrderPricingService {
    constructor(
        private readonly shippingCalculator: ShippingCalculator,
        private readonly taxCalculator: TaxCalculator,
        private readonly discountEngine: DiscountEngine
    ) { }
    
    calculateTotal(order: Order): OrderPricing { /* ... */ }
}
 
// Handles notification concerns
class OrderNotificationService {
    constructor(
        private readonly emailNotifier: EmailNotifier,
        private readonly smsNotifier: SmsNotifier
    ) { }
    
    notifyOrderPlaced(order: Order): Promise<void> { /* ... */ }
}
 
// Handles order fulfillment
class OrderFulfillmentService {
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly inventoryService: InventoryService,
        private readonly paymentGateway: PaymentGateway
    ) { }
    
    fulfill(order: Order): Promise<FulfillmentResult> { /* ... */ }
}
 
// Composes the above - still uses constructor injection
class OrderProcessingService {
    constructor(
        private readonly pricing: OrderPricingService,
        private readonly notifications: OrderNotificationService,
        private readonly fulfillment: OrderFulfillmentService
    ) { }
    
    async process(order: Order): Promise<ProcessingResult> {
        const pricing = this.pricing.calculateTotal(order);
        const result = await this.fulfillment.fulfill(order);
        await this.notifications.notifyOrderPlaced(order);
        return result;
    }
}

2. Use Facade/Aggregate Dependencies

•Group related dependencies behind a single interface
•The facade provides access to individual components
•Reduces constructor parameters while maintaining access
•Useful when decomposition isn't practical

facade-dependencies.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Create a facade for related dependencies
interface NotificationServices {
    readonly email: EmailNotifier;
    readonly sms: SmsNotifier;
    readonly push: PushNotifier;
}
 
interface AnalyticsServices {
    readonly tracker: AnalyticsTracker;
    readonly auditLog: AuditLogger;
    readonly metrics: MetricsCollector;
}
 
// Now the class takes fewer parameters
class OrderProcessingService {
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly paymentGateway: PaymentGateway,
        private readonly notifications: NotificationServices,
        private readonly analytics: AnalyticsServices
    ) { }
    
    async processOrder(order: Order): Promise<void> {
        // Access individual services through facades
        await this.notifications.email.send(/*...*/);
        this.analytics.tracker.track(/*...*/);
    }
}

3. Use a Parameter Object (Configuration)

•Group configuration values into a single config object
•Appropriate for primitive values, not service dependencies
•Keeps service dependencies visible, hides configuration complexity

What NOT to Do

Don't solve constructor explosion by switching to setter injection. This trades visibility for hidden problems. The dependencies still exist—they're just not visible in the constructor. You've hidden the smell, not fixed it.

Handling Optional Dependencies

Not all dependencies are required. Some are optional—the class can function without them, perhaps with reduced capabilities. Constructor Injection handles optional dependencies through several patterns:

1. Nullable/Optional Parameters with Defaults

The simplest approach: allow null/undefined and provide default behavior:

optional-dependencies.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// Option 1: Null/undefined with conditional logic
class OrderService {
    constructor(
        private readonly repository: OrderRepository,
        private readonly cache?: OrderCache,  // Optional
        private readonly analytics?: AnalyticsTracker  // Optional
    ) {
        // Required dependency validated
        if (!repository) {
            throw new Error("OrderRepository is required");
        }
        // Optional dependencies not validated - they can be undefined
    }
    
    async getOrder(id: string): Promise<Order> {
        // Check if optional cache is available
        if (this.cache) {
            const cached = await this.cache.get(id);
            if (cached) return cached;
        }
        
        const order = await this.repository.findById(id);
        
        // Only cache if cache is available
        if (this.cache && order) {
            await this.cache.set(id, order);
        }
        
        // Only track if analytics is available
        this.analytics?.track("order_viewed", { orderId: id });
        
        return order;
    }
}

2. Null Object Pattern (Preferred)

Provide a "null object" that has no behavior but satisfies the interface. This eliminates conditional checks throughout the code:

null-object-pattern.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
// Null objects that satisfy the interface but do nothing
class NullCache implements OrderCache {
    async get(id: string): Promise<Order | null> {
        return null;  // Always cache miss
    }
    
    async set(id: string, order: Order): Promise<void> {
        // Do nothing - no-op
    }
    
    async invalidate(id: string): Promise<void> {
        // Do nothing - no-op
    }
}
 
class NullAnalytics implements AnalyticsTracker {
    track(event: string, data: object): void {
        // Do nothing - no-op
    }
}
 
// The class no longer needs conditional checks
class OrderService {
    constructor(
        private readonly repository: OrderRepository,
        private readonly cache: OrderCache = new NullCache(),
        private readonly analytics: AnalyticsTracker = new NullAnalytics()
    ) {
        if (!repository) {
            throw new Error("OrderRepository is required");
        }
        // cache and analytics always have values (possibly nullobjects)
    }
    
    async getOrder(id: string): Promise<Order> {
        // No conditionals needed - cache handles miss internally
        const cached = await this.cache.get(id);
        if (cached) return cached;
        
        const order = await this.repository.findById(id);
        
        if (order) {
            await this.cache.set(id, order);  // No-op if NullCache
        }
        
        this.analytics.track("order_viewed", { orderId: id });  // No-op if NullAnalytics
        
        return order;
    }
}

3. Constructor Overloading

Some languages support multiple constructors. The "convenience" constructor provides defaults:

overloaded-constructor.java
Java
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
public class OrderService {
    private final OrderRepository repository;
    private final OrderCache cache;
    private final AnalyticsTracker analytics;
    
    // Full constructor with all dependencies
    public OrderService(
            OrderRepository repository,
            OrderCache cache,
            AnalyticsTracker analytics) {
        this.repository = Objects.requireNonNull(repository);
        this.cache = cache != null ? cache : new NullCache();
        this.analytics = analytics != null ? analytics : new NullAnalytics();
    }
    
    // Convenience constructor for required dependencies only
    public OrderService(OrderRepository repository) {
        this(repository, null, null);  // Delegates to full constructor
    }
    
    // Convenience with cache
    public OrderService(OrderRepository repository, OrderCache cache) {
        this(repository, cache, null);
    }
}

Prefer Null Object Pattern

The Null Object pattern yields cleaner code than conditional checks. Methods don't need to know which dependencies are "real" and which are optional. The polymorphism handles it—NullCache always returns miss, NullAnalytics silently ignores calls. Code stays clean, testable, and intention-revealing.

Testing with Constructor Injection

Constructor Injection shines brightest in testing scenarios. Mocks, stubs, and fakes are trivially injected—no reflection, no special frameworks, just normal constructor invocation.

The testing advantage:

Create mocks that satisfy the interface — Any object implementing the interface can be injected
Pass mocks through constructor — Standard constructor invocation, nothing special
Verify behavior — Mocks can track calls, return controlled values
Isolated tests — The class under test has no external dependencies

constructor-injection-tests.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
// Testing OrderProcessingService with constructor injection
 
describe("OrderProcessingService", () => {
    // Mock implementations
    let mockRepository: jest.Mocked<OrderRepository>;
    let mockPaymentGateway: jest.Mocked<PaymentGateway>;
    let mockEventPublisher: jest.Mocked<EventPublisher>;
    let service: OrderProcessingService;
    
    beforeEach(() => {
        // Create fresh mocks for each test
        mockRepository = {
            save: jest.fn(),
            findById: jest.fn(),
            findByCustomer: jest.fn()
        };
        
        mockPaymentGateway = {
            charge: jest.fn(),
            refund: jest.fn()
        };
        
        mockEventPublisher = {
            publish: jest.fn()
        };
        
        // Inject mocks through constructor - trivially simple!
        service = new OrderProcessingService(
            mockRepository,
            mockPaymentGateway,
            mockEventPublisher
        );
    });
    
    describe("processOrder", () => {
        it("should charge payment, save order, and publish event on success", async () => {
            // Arrange
            const order = createTestOrder({ total: 100 });
            mockPaymentGateway.charge.mockResolvedValue({
                success: true,
                transactionId: "txn-123"
            });
            mockRepository.save.mockResolvedValue(undefined);
            mockEventPublisher.publish.mockResolvedValue(undefined);
            
            // Act
            const result = await service.processOrder(order);
            
            // Assert
            expect(result.success).toBe(true);
            expect(mockPaymentGateway.charge).toHaveBeenCalledWith(
                order.paymentDetails
            );
            expect(mockRepository.save).toHaveBeenCalledWith(
                expect.objectContaining({ id: order.id })
            );
            expect(mockEventPublisher.publish).toHaveBeenCalledWith(
                expect.any(OrderPaidEvent)
            );
        });
        
        it("should NOT save or publish when payment fails", async () => {
            // Arrange
            const order = createTestOrder();
            mockPaymentGateway.charge.mockResolvedValue({
                success: false,
                error: "Insufficient funds"
            });
            
            // Act
            const result = await service.processOrder(order);
            
            // Assert
            expect(result.success).toBe(false);
            expect(mockRepository.save).not.toHaveBeenCalled();
            expect(mockEventPublisher.publish).not.toHaveBeenCalled();
        });
        
        it("should propagate payment gateway errors", async () => {
            // Arrange
            const order = createTestOrder();
            mockPaymentGateway.charge.mockRejectedValue(
                new Error("Gateway timeout")
            );
            
            // Act & Assert
            await expect(service.processOrder(order))
                .rejects.toThrow("Gateway timeout");
        });
    });
});

Testing edge cases and error paths:

With Constructor Injection, you control the entire environment. Testing error handling becomes straightforward:

testing-error-paths.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
describe("error handling scenarios", () => {
    it("should retry on transient database error", async () => {
        // Simulate transient failure
        let callCount = 0;
        mockRepository.save.mockImplementation(async () => {
            callCount++;
            if (callCount < 3) {
                throw new TransientDatabaseError("Connection lost");
            }
            return undefined;  // Success on 3rd try
        });
        
        const result = await service.processOrder(createTestOrder());
        
        expect(result.success).toBe(true);
        expect(mockRepository.save).toHaveBeenCalledTimes(3);
    });
    
    it("should refund payment if order save fails permanently", async () => {
        mockPaymentGateway.charge.mockResolvedValue({
            success: true,
            transactionId: "txn-456"
        });
        mockRepository.save.mockRejectedValue(
            new Error("Database unavailable")
        );
        mockPaymentGateway.refund.mockResolvedValue({
            success: true
        });
        
        await expect(service.processOrder(createTestOrder()))
            .rejects.toThrow("Database unavailable");
        
        // Verify compensating transaction
        expect(mockPaymentGateway.refund).toHaveBeenCalledWith(
            "txn-456",
            expect.any(Object)
        );
    });
});

No Magic Required

Notice how testing requires no special DI framework, no reflection, no annotation processing. Just construct the object with mocks. This simplicity is the hallmark of good design—testability emerges from the design itself, not from framework workarounds.

Framework Integration

Most DI frameworks prioritize Constructor Injection and integrate seamlessly with it. The framework identifies constructor parameters, resolves their types from its registry, and invokes the constructor with concrete implementations.

NestJS (TypeScript):

nestjs-constructor-injection.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import { Injectable, Inject } from "@nestjs/common";
 
// Services are marked @Injectable
@Injectable()
export class OrderRepository {
    async findById(id: string): Promise<Order> { /* ... */ }
}
 
@Injectable()
export class EmailNotifier {
    async send(email: Email): Promise<void> { /* ... */ }
}
 
// NestJS automatically injects constructor parameters
@Injectable()
export class OrderService {
    constructor(
        private readonly repository: OrderRepository,
        private readonly notifier: EmailNotifier
    ) { }
    // NestJS sees OrderRepository and EmailNotifier in constructor,
    // finds instances in its container, and injects them automatically
}
 
// Module wiring
@Module({
    providers: [
        OrderRepository,
        EmailNotifier,
        OrderService  // NestJS wires dependencies automatically
    ]
})
export class OrderModule { }

Spring Framework (Java):

spring-constructor-injection.java
Java
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
import org.springframework.stereotype.Service;
import org.springframework.stereotype.Repository;
 
@Repository
public class OrderRepositoryImpl implements OrderRepository {
    // Implementation...
}
 
@Service
public class EmailNotifierImpl implements EmailNotifier {
    // Implementation...
}
 
@Service
public class OrderService {
    private final OrderRepository repository;
    private final EmailNotifier notifier;
    
    // Spring detects single constructor and autowires automatically
    // @Autowired is optional with single constructor (Spring 4.3+)
    public OrderService(OrderRepository repository, EmailNotifier notifier) {
        this.repository = repository;
        this.notifier = notifier;
    }
}
 
// Spring finds implementations, creates instances, injects them

InversifyJS (TypeScript):

inversify-constructor-injection.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import { injectable, inject, Container } from "inversify";
 
// Symbols for binding identifiers
const TYPES = {
    OrderRepository: Symbol.for("OrderRepository"),
    EmailNotifier: Symbol.for("EmailNotifier"),
    OrderService: Symbol.for("OrderService")
};
 
@injectable()
class PostgresOrderRepository implements OrderRepository {
    // Implementation...
}
 
@injectable()
class SmtpEmailNotifier implements EmailNotifier {
    // Implementation...
}
 
@injectable()
class OrderService {
    constructor(
        @inject(TYPES.OrderRepository) private repository: OrderRepository,
        @inject(TYPES.EmailNotifier) private notifier: EmailNotifier
    ) { }
}
 
// Container configuration
const container = new Container();
container.bind<OrderRepository>(TYPES.OrderRepository)
    .to(PostgresOrderRepository);
container.bind<EmailNotifier>(TYPES.EmailNotifier)
    .to(SmtpEmailNotifier);
container.bind<OrderService>(TYPES.OrderService)
    .to(OrderService);
 
// Get wired instance
const orderService = container.get<OrderService>(TYPES.OrderService);

Framework Invariant

Regardless of framework, the pattern is consistent: declare dependencies in the constructor, let the framework handle resolution. Your class code remains the same whether using Spring, NestJS, Guice, or plain manual composition. This is the universality of Constructor Injection.

Summary: Constructor Injection Mastery

Constructor Injection is the cornerstone of practical dependency injection. Let's consolidate the essential knowledge:

Key Takeaways

•Mechanics — Declare dependencies as constructor parameters, store in private readonly fields, object is ready immediately upon construction.
•Preference — Constructor Injection is preferred for immutability, completeness, explicit requirements, fail-fast construction, and easy testing.
•Validation — Validate required dependencies immediately in the constructor. Fail fast with descriptive errors.
•Constructor Explosion — Many parameters indicate design problems (SRP violations). Decompose the class rather than hiding dependencies.
•Optional Dependencies — Use the Null Object pattern to eliminate conditional checks while supporting optional collaborators.
•Testing — Mocks are injected through normal constructor invocation. No reflection, no framework magic—just simple, readable test code.
•Frameworks — All major DI frameworks support Constructor Injection as the primary pattern. Your class code is framework-agnostic.

What's next:

While Constructor Injection is preferred, it's not always sufficient. The next page explores Setter Injection—when it's appropriate, how to implement it safely, and patterns for combining it with Constructor Injection. You'll learn when setter injection adds value and when it introduces risk.

The Default Choice

Constructor Injection should be your default choice for dependency injection. When in doubt, use constructor injection. Only consider alternatives when specific constraints make it impossible or impractical. The next pages explore those specific scenarios.

2 / 5

Loading learning content...

System Design (HLD)Dependency Injection Fundamentals

Dependency Injection Fundamentals

LevelIntermediate

Duration60 mins

TopicDependency Injection Fundamentals

2 / 5

Constructor Injection

The Gold Standard of Dependency Injection

What You Will Learn

Constructor Injection Mechanics

Constructor Injection follows a precise mechanical pattern:

Declare dependencies as constructor parameters — Each required collaborator becomes a constructor parameter, typically typed to an interface (abstraction).
Store dependencies as instance fields — The constructor assigns parameters to private, readonly fields for later use.
Object is ready upon construction — Once the constructor completes, the object possesses everything it needs to function. No further initialization required.
Injector provides concrete implementations — The calling code (composition root or DI container) supplies actual instances.

constructor-injection-anatomy.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
// ANATOMY OF CONSTRUCTOR INJECTION
 
// Step 1: Define abstractions (interfaces)
interface OrderRepository {
    save(order: Order): Promise<void>;
    findById(id: string): Promise<Order | null>;
    findByCustomer(customerId: string): Promise<Order[]>;
}
 
interface PaymentGateway {
    charge(payment: PaymentDetails): Promise<PaymentResult>;
    refund(transactionId: string, amount: Money): Promise<RefundResult>;
}
 
interface EventPublisher {
    publish<T extends DomainEvent>(event: T): Promise<void>;
}
 
// Step 2: Declare dependencies as constructor parameters
class OrderProcessingService {
    // Step 3: Store as private readonly fields
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly paymentGateway: PaymentGateway,
        private readonly eventPublisher: EventPublisher
    ) {
        // TypeScript's parameter properties handle field declaration
        // No explicit assignment needed with 'private readonly' syntax
    }
    
    // Step 4: Use dependencies in methods
    async processOrder(order: Order): Promise<ProcessingResult> {
        // All dependencies are guaranteed available
        const paymentResult = await this.paymentGateway.charge(
            order.paymentDetails
        );
        
        if (paymentResult.success) {
            order.markAsPaid(paymentResult.transactionId);
            await this.orderRepository.save(order);
            await this.eventPublisher.publish(
                new OrderPaidEvent(order.id, paymentResult.transactionId)
            );
            return ProcessingResult.success(order);
        }
        
        return ProcessingResult.paymentFailed(paymentResult.error);
    }
}

The constructor as a contract:

The constructor signature serves as an explicit contract. Anyone reading the code immediately knows:

Exactly what this class needs — The parameter list is a complete manifest
Types of collaborators required — Interfaces reveal expected capabilities
No hidden dependencies — Everything required is visible
Object state after construction — All fields are initialized, object is ready

This transparency is invaluable for code comprehension, testing, and maintenance.

Why Constructor Injection Is Preferred

Constructor Injection is the preferred DI technique for fundamental reasons rooted in object-oriented design principles. Let's examine each advantage in depth:

Fundamental Advantages

•Immutability — Dependencies stored in readonly/final fields cannot change after construction. The object's collaborators are fixed for its lifetime, eliminating an entire category of bugs related to changing dependencies mid-execution.
•Complete initialization — The object is fully functional immediately upon construction. There's no "partially initialized" state where some dependencies are present and others are missing.
•Explicit requirements — The constructor signature is a complete manifest of what the class needs. Dependencies are visible, not hidden in setters or service locators.
•Fail-fast construction — If dependencies are missing or invalid, construction fails immediately. You discover problems at startup, not when a method is called hours later.
•Easier testing — Mocks are injected through the constructor. No special reflection tricks or framework magic needed—just pass dependencies as arguments.
•Framework compatibility — Virtually every DI framework supports constructor injection as the primary mechanism. It's the universal pattern.

With Setter Injection

•Object exists in incomplete state after construction
•Setters might not all be called
•Dependencies can change mid-execution
•Methods must check if dependencies exist
•Temporal coupling: call order matters
•Thread-safety concerns with mutable fields

With Constructor Injection

•Object is complete and ready immediately
•All dependencies guaranteed present
•Dependencies are immutable
•Methods can assume dependencies exist
•No temporal coupling
•Thread-safe by design (immutable)

The Immutability Bonus

Null Safety, Validation, and Defensive Programming

The principle: If a dependency is required, verify it's not null/undefined immediately upon construction. Throw a descriptive error that pinpoints exactly which dependency is missing.

defensive-constructor.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
// ❌ NAIVE: Assumes dependencies are valid
class OrderService {
    constructor(
        private readonly repository: OrderRepository,
        private readonly logger: Logger
    ) { }
    
    // If repository is null, this throws cryptic error deep in call stack
    async getOrder(id: string): Promise<Order> {
        return await this.repository.findById(id);
        // TypeError: Cannot read property 'findById' of null
    }
}
 
// ✅ DEFENSIVE: Validates dependencies immediately
class OrderService {
    private readonly repository: OrderRepository;
    private readonly logger: Logger;
    
    constructor(repository: OrderRepository, logger: Logger) {
        if (!repository) {
            throw new Error("OrderService requires OrderRepository but received null/undefined");
        }
        if (!logger) {
            throw new Error("OrderService requires Logger but received null/undefined");
        }
        
        this.repository = repository;
        this.logger = logger;
    }
}
 
// ✅ EVEN BETTER: Create a utility for consistent validation
function requireDependency<T>(value: T | null | undefined, name: string): T {
    if (value === null || value === undefined) {
        throw new Error(`Required dependency '${name}' was not provided`);
    }
    return value;
}
 
class OrderService {
    private readonly repository: OrderRepository;
    private readonly logger: Logger;
    
    constructor(repository: OrderRepository, logger: Logger) {
        this.repository = requireDependency(repository, "OrderRepository");
        this.logger = requireDependency(logger, "Logger");
    }
}

Beyond null checks: semantic validation

Some dependencies require more than null checks. They might need semantic validation—verifying that the dependency is in a usable state:

semantic-validation.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
class DatabaseOrderRepository implements OrderRepository {
    constructor(private readonly connectionPool: ConnectionPool) {
        if (!connectionPool) {
            throw new Error("ConnectionPool is required");
        }
        
        // Semantic validation: is the pool actually usable?
        if (connectionPool.size === 0) {
            throw new Error("ConnectionPool must have at least one connection");
        }
        
        if (!connectionPool.isInitialized) {
            throw new Error("ConnectionPool must be initialized before injection");
        }
    }
}
 
// For configuration objects, validate structure
class EmailNotificationService {
    constructor(
        private readonly emailClient: EmailClient,
        private readonly config: EmailConfig
    ) {
        this.emailClient = requireDependency(emailClient, "EmailClient");
        
        // Validate config structure
        if (!config) {
            throw new Error("EmailConfig is required");
        }
        if (!config.fromAddress || !this.isValidEmail(config.fromAddress)) {
            throw new Error("EmailConfig.fromAddress must be a valid email");
        }
        if (!config.templatesPath) {
            throw new Error("EmailConfig.templatesPath is required");
        }
        
        this.config = config;
    }
    
    private isValidEmail(email: string): boolean {
        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
    }
}

Don't Over-Validate

Dealing with Many Dependencies (Constructor Explosion)

A common concern with Constructor Injection is "constructor explosion"—constructors with an unwieldy number of parameters:

// Constructor Explosion — a warning sign
class OrderProcessingService {
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly customerRepository: CustomerRepository,
        private readonly inventoryService: InventoryService,
        private readonly paymentGateway: PaymentGateway,
        private readonly shippingCalculator: ShippingCalculator,
        private readonly taxCalculator: TaxCalculator,
        private readonly discountEngine: DiscountEngine,
        private readonly emailNotifier: EmailNotifier,
        private readonly smsNotifier: SmsNotifier,
        private readonly analyticsTracker: AnalyticsTracker,
        private readonly auditLogger: AuditLogger,
        private readonly featureFlags: FeatureFlags
    ) { }
}

This is painful—but it's a feature, not a bug. The pain is signaling a design problem: this class has too many responsibilities.

Constructor Explosion as Design Feedback

Solutions to constructor explosion:

Don't hide the problem—solve it. There are several legitimate approaches:

1. Decompose the Class (Preferred)

•The class likely violates Single Responsibility Principle
•Extract cohesive groups of dependencies into separate classes
•Each smaller class takes fewer dependencies
•Compose the smaller classes to achieve the original functionality

decompose-class.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
// BEFORE: Giant class with many dependencies
class OrderProcessingService {
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly inventoryService: InventoryService,
        private readonly paymentGateway: PaymentGateway,
        private readonly shippingCalculator: ShippingCalculator,
        private readonly taxCalculator: TaxCalculator,
        private readonly discountEngine: DiscountEngine,
        private readonly emailNotifier: EmailNotifier,
        private readonly smsNotifier: SmsNotifier
    ) { }
}
 
// AFTER: Decomposed into focused classes
 
// Handles pricing concerns
class OrderPricingService {
    constructor(
        private readonly shippingCalculator: ShippingCalculator,
        private readonly taxCalculator: TaxCalculator,
        private readonly discountEngine: DiscountEngine
    ) { }
    
    calculateTotal(order: Order): OrderPricing { /* ... */ }
}
 
// Handles notification concerns
class OrderNotificationService {
    constructor(
        private readonly emailNotifier: EmailNotifier,
        private readonly smsNotifier: SmsNotifier
    ) { }
    
    notifyOrderPlaced(order: Order): Promise<void> { /* ... */ }
}
 
// Handles order fulfillment
class OrderFulfillmentService {
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly inventoryService: InventoryService,
        private readonly paymentGateway: PaymentGateway
    ) { }
    
    fulfill(order: Order): Promise<FulfillmentResult> { /* ... */ }
}
 
// Composes the above - still uses constructor injection
class OrderProcessingService {
    constructor(
        private readonly pricing: OrderPricingService,
        private readonly notifications: OrderNotificationService,
        private readonly fulfillment: OrderFulfillmentService
    ) { }
    
    async process(order: Order): Promise<ProcessingResult> {
        const pricing = this.pricing.calculateTotal(order);
        const result = await this.fulfillment.fulfill(order);
        await this.notifications.notifyOrderPlaced(order);
        return result;
    }
}

2. Use Facade/Aggregate Dependencies

•Group related dependencies behind a single interface
•The facade provides access to individual components
•Reduces constructor parameters while maintaining access
•Useful when decomposition isn't practical

facade-dependencies.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Create a facade for related dependencies
interface NotificationServices {
    readonly email: EmailNotifier;
    readonly sms: SmsNotifier;
    readonly push: PushNotifier;
}
 
interface AnalyticsServices {
    readonly tracker: AnalyticsTracker;
    readonly auditLog: AuditLogger;
    readonly metrics: MetricsCollector;
}
 
// Now the class takes fewer parameters
class OrderProcessingService {
    constructor(
        private readonly orderRepository: OrderRepository,
        private readonly paymentGateway: PaymentGateway,
        private readonly notifications: NotificationServices,
        private readonly analytics: AnalyticsServices
    ) { }
    
    async processOrder(order: Order): Promise<void> {
        // Access individual services through facades
        await this.notifications.email.send(/*...*/);
        this.analytics.tracker.track(/*...*/);
    }
}

3. Use a Parameter Object (Configuration)

•Group configuration values into a single config object
•Appropriate for primitive values, not service dependencies
•Keeps service dependencies visible, hides configuration complexity

What NOT to Do

Handling Optional Dependencies

1. Nullable/Optional Parameters with Defaults

The simplest approach: allow null/undefined and provide default behavior:

optional-dependencies.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// Option 1: Null/undefined with conditional logic
class OrderService {
    constructor(
        private readonly repository: OrderRepository,
        private readonly cache?: OrderCache,  // Optional
        private readonly analytics?: AnalyticsTracker  // Optional
    ) {
        // Required dependency validated
        if (!repository) {
            throw new Error("OrderRepository is required");
        }
        // Optional dependencies not validated - they can be undefined
    }
    
    async getOrder(id: string): Promise<Order> {
        // Check if optional cache is available
        if (this.cache) {
            const cached = await this.cache.get(id);
            if (cached) return cached;
        }
        
        const order = await this.repository.findById(id);
        
        // Only cache if cache is available
        if (this.cache && order) {
            await this.cache.set(id, order);
        }
        
        // Only track if analytics is available
        this.analytics?.track("order_viewed", { orderId: id });
        
        return order;
    }
}

2. Null Object Pattern (Preferred)

Provide a "null object" that has no behavior but satisfies the interface. This eliminates conditional checks throughout the code:

null-object-pattern.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
// Null objects that satisfy the interface but do nothing
class NullCache implements OrderCache {
    async get(id: string): Promise<Order | null> {
        return null;  // Always cache miss
    }
    
    async set(id: string, order: Order): Promise<void> {
        // Do nothing - no-op
    }
    
    async invalidate(id: string): Promise<void> {
        // Do nothing - no-op
    }
}
 
class NullAnalytics implements AnalyticsTracker {
    track(event: string, data: object): void {
        // Do nothing - no-op
    }
}
 
// The class no longer needs conditional checks
class OrderService {
    constructor(
        private readonly repository: OrderRepository,
        private readonly cache: OrderCache = new NullCache(),
        private readonly analytics: AnalyticsTracker = new NullAnalytics()
    ) {
        if (!repository) {
            throw new Error("OrderRepository is required");
        }
        // cache and analytics always have values (possibly nullobjects)
    }
    
    async getOrder(id: string): Promise<Order> {
        // No conditionals needed - cache handles miss internally
        const cached = await this.cache.get(id);
        if (cached) return cached;
        
        const order = await this.repository.findById(id);
        
        if (order) {
            await this.cache.set(id, order);  // No-op if NullCache
        }
        
        this.analytics.track("order_viewed", { orderId: id });  // No-op if NullAnalytics
        
        return order;
    }
}

3. Constructor Overloading

Some languages support multiple constructors. The "convenience" constructor provides defaults:

overloaded-constructor.java
Java
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
public class OrderService {
    private final OrderRepository repository;
    private final OrderCache cache;
    private final AnalyticsTracker analytics;
    
    // Full constructor with all dependencies
    public OrderService(
            OrderRepository repository,
            OrderCache cache,
            AnalyticsTracker analytics) {
        this.repository = Objects.requireNonNull(repository);
        this.cache = cache != null ? cache : new NullCache();
        this.analytics = analytics != null ? analytics : new NullAnalytics();
    }
    
    // Convenience constructor for required dependencies only
    public OrderService(OrderRepository repository) {
        this(repository, null, null);  // Delegates to full constructor
    }
    
    // Convenience with cache
    public OrderService(OrderRepository repository, OrderCache cache) {
        this(repository, cache, null);
    }
}

Prefer Null Object Pattern

Testing with Constructor Injection

Constructor Injection shines brightest in testing scenarios. Mocks, stubs, and fakes are trivially injected—no reflection, no special frameworks, just normal constructor invocation.

The testing advantage:

Create mocks that satisfy the interface — Any object implementing the interface can be injected
Pass mocks through constructor — Standard constructor invocation, nothing special
Verify behavior — Mocks can track calls, return controlled values
Isolated tests — The class under test has no external dependencies

constructor-injection-tests.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
// Testing OrderProcessingService with constructor injection
 
describe("OrderProcessingService", () => {
    // Mock implementations
    let mockRepository: jest.Mocked<OrderRepository>;
    let mockPaymentGateway: jest.Mocked<PaymentGateway>;
    let mockEventPublisher: jest.Mocked<EventPublisher>;
    let service: OrderProcessingService;
    
    beforeEach(() => {
        // Create fresh mocks for each test
        mockRepository = {
            save: jest.fn(),
            findById: jest.fn(),
            findByCustomer: jest.fn()
        };
        
        mockPaymentGateway = {
            charge: jest.fn(),
            refund: jest.fn()
        };
        
        mockEventPublisher = {
            publish: jest.fn()
        };
        
        // Inject mocks through constructor - trivially simple!
        service = new OrderProcessingService(
            mockRepository,
            mockPaymentGateway,
            mockEventPublisher
        );
    });
    
    describe("processOrder", () => {
        it("should charge payment, save order, and publish event on success", async () => {
            // Arrange
            const order = createTestOrder({ total: 100 });
            mockPaymentGateway.charge.mockResolvedValue({
                success: true,
                transactionId: "txn-123"
            });
            mockRepository.save.mockResolvedValue(undefined);
            mockEventPublisher.publish.mockResolvedValue(undefined);
            
            // Act
            const result = await service.processOrder(order);
            
            // Assert
            expect(result.success).toBe(true);
            expect(mockPaymentGateway.charge).toHaveBeenCalledWith(
                order.paymentDetails
            );
            expect(mockRepository.save).toHaveBeenCalledWith(
                expect.objectContaining({ id: order.id })
            );
            expect(mockEventPublisher.publish).toHaveBeenCalledWith(
                expect.any(OrderPaidEvent)
            );
        });
        
        it("should NOT save or publish when payment fails", async () => {
            // Arrange
            const order = createTestOrder();
            mockPaymentGateway.charge.mockResolvedValue({
                success: false,
                error: "Insufficient funds"
            });
            
            // Act
            const result = await service.processOrder(order);
            
            // Assert
            expect(result.success).toBe(false);
            expect(mockRepository.save).not.toHaveBeenCalled();
            expect(mockEventPublisher.publish).not.toHaveBeenCalled();
        });
        
        it("should propagate payment gateway errors", async () => {
            // Arrange
            const order = createTestOrder();
            mockPaymentGateway.charge.mockRejectedValue(
                new Error("Gateway timeout")
            );
            
            // Act & Assert
            await expect(service.processOrder(order))
                .rejects.toThrow("Gateway timeout");
        });
    });
});

Testing edge cases and error paths:

With Constructor Injection, you control the entire environment. Testing error handling becomes straightforward:

testing-error-paths.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
describe("error handling scenarios", () => {
    it("should retry on transient database error", async () => {
        // Simulate transient failure
        let callCount = 0;
        mockRepository.save.mockImplementation(async () => {
            callCount++;
            if (callCount < 3) {
                throw new TransientDatabaseError("Connection lost");
            }
            return undefined;  // Success on 3rd try
        });
        
        const result = await service.processOrder(createTestOrder());
        
        expect(result.success).toBe(true);
        expect(mockRepository.save).toHaveBeenCalledTimes(3);
    });
    
    it("should refund payment if order save fails permanently", async () => {
        mockPaymentGateway.charge.mockResolvedValue({
            success: true,
            transactionId: "txn-456"
        });
        mockRepository.save.mockRejectedValue(
            new Error("Database unavailable")
        );
        mockPaymentGateway.refund.mockResolvedValue({
            success: true
        });
        
        await expect(service.processOrder(createTestOrder()))
            .rejects.toThrow("Database unavailable");
        
        // Verify compensating transaction
        expect(mockPaymentGateway.refund).toHaveBeenCalledWith(
            "txn-456",
            expect.any(Object)
        );
    });
});

No Magic Required

Framework Integration

NestJS (TypeScript):

nestjs-constructor-injection.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import { Injectable, Inject } from "@nestjs/common";
 
// Services are marked @Injectable
@Injectable()
export class OrderRepository {
    async findById(id: string): Promise<Order> { /* ... */ }
}
 
@Injectable()
export class EmailNotifier {
    async send(email: Email): Promise<void> { /* ... */ }
}
 
// NestJS automatically injects constructor parameters
@Injectable()
export class OrderService {
    constructor(
        private readonly repository: OrderRepository,
        private readonly notifier: EmailNotifier
    ) { }
    // NestJS sees OrderRepository and EmailNotifier in constructor,
    // finds instances in its container, and injects them automatically
}
 
// Module wiring
@Module({
    providers: [
        OrderRepository,
        EmailNotifier,
        OrderService  // NestJS wires dependencies automatically
    ]
})
export class OrderModule { }

Spring Framework (Java):

spring-constructor-injection.java
Java
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
import org.springframework.stereotype.Service;
import org.springframework.stereotype.Repository;
 
@Repository
public class OrderRepositoryImpl implements OrderRepository {
    // Implementation...
}
 
@Service
public class EmailNotifierImpl implements EmailNotifier {
    // Implementation...
}
 
@Service
public class OrderService {
    private final OrderRepository repository;
    private final EmailNotifier notifier;
    
    // Spring detects single constructor and autowires automatically
    // @Autowired is optional with single constructor (Spring 4.3+)
    public OrderService(OrderRepository repository, EmailNotifier notifier) {
        this.repository = repository;
        this.notifier = notifier;
    }
}
 
// Spring finds implementations, creates instances, injects them

InversifyJS (TypeScript):

inversify-constructor-injection.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import { injectable, inject, Container } from "inversify";
 
// Symbols for binding identifiers
const TYPES = {
    OrderRepository: Symbol.for("OrderRepository"),
    EmailNotifier: Symbol.for("EmailNotifier"),
    OrderService: Symbol.for("OrderService")
};
 
@injectable()
class PostgresOrderRepository implements OrderRepository {
    // Implementation...
}
 
@injectable()
class SmtpEmailNotifier implements EmailNotifier {
    // Implementation...
}
 
@injectable()
class OrderService {
    constructor(
        @inject(TYPES.OrderRepository) private repository: OrderRepository,
        @inject(TYPES.EmailNotifier) private notifier: EmailNotifier
    ) { }
}
 
// Container configuration
const container = new Container();
container.bind<OrderRepository>(TYPES.OrderRepository)
    .to(PostgresOrderRepository);
container.bind<EmailNotifier>(TYPES.EmailNotifier)
    .to(SmtpEmailNotifier);
container.bind<OrderService>(TYPES.OrderService)
    .to(OrderService);
 
// Get wired instance
const orderService = container.get<OrderService>(TYPES.OrderService);

Framework Invariant

Summary: Constructor Injection Mastery

Constructor Injection is the cornerstone of practical dependency injection. Let's consolidate the essential knowledge:

Key Takeaways

•Mechanics — Declare dependencies as constructor parameters, store in private readonly fields, object is ready immediately upon construction.
•Preference — Constructor Injection is preferred for immutability, completeness, explicit requirements, fail-fast construction, and easy testing.
•Validation — Validate required dependencies immediately in the constructor. Fail fast with descriptive errors.
•Constructor Explosion — Many parameters indicate design problems (SRP violations). Decompose the class rather than hiding dependencies.
•Optional Dependencies — Use the Null Object pattern to eliminate conditional checks while supporting optional collaborators.
•Testing — Mocks are injected through normal constructor invocation. No reflection, no framework magic—just simple, readable test code.
•Frameworks — All major DI frameworks support Constructor Injection as the primary pattern. Your class code is framework-agnostic.

What's next:

The Default Choice

2 / 5