System Design (LLD)Inversion of Control Containers

Inversion of Control Containers

LevelIntermediate

Duration60 mins

TopicInversion of Control Containers

1 / 4

What is an IoC Container

The Missing Piece in Dependency Management

Throughout our exploration of the Dependency Inversion Principle, we've established that high-level modules should depend on abstractions, not concrete implementations. We've learned that dependency injection allows us to supply those dependencies from outside, making our code testable and flexible. But as applications grow in complexity, a fundamental question emerges: Who creates and wires together all these objects?

Consider a real-world enterprise application. A single request might touch dozens of components: controllers, services, repositories, caches, validators, loggers, and external API clients. Each component might have five to ten dependencies. Those dependencies have their own dependencies. Manually constructing this object graph becomes a maintenance nightmare of exponential complexity.

This is where Inversion of Control (IoC) containers enter the picture—not as mere convenience utilities, but as architectural infrastructure that fundamentally changes how enterprise applications are structured and maintained.

What You Will Learn

By the end of this page, you will understand the fundamental concepts of IoC containers: what problems they solve, how they relate to DIP and dependency injection, the core services they provide (object creation, lifecycle management, dependency resolution), and why they are considered essential infrastructure in modern enterprise applications.

The Inversion of Control Paradigm

Before diving into containers, we must understand the paradigm they implement: Inversion of Control (IoC). This is a fundamental principle that extends far beyond dependency injection and represents a profound shift in how we structure software.

Traditional Control Flow:

In traditional procedural programming, your application code controls the flow of execution. Your code calls library functions when needed. Your code decides when to create objects. Your code determines the order of operations. The application is the active party; frameworks and libraries are passive tools waiting to be invoked.

Inverted Control Flow:

Under IoC, this relationship reverses. A framework takes control of the application flow. It calls your code at appropriate times. It creates objects when needed. It determines orchestration. Your code becomes the passive party—components that plug into a framework-controlled structure.

This inversion isn't new. If you've ever written a callback function, implemented an event handler, or created a template method subclass, you've experienced IoC. The framework calls you; you don't call the framework.

Traditional Control vs Inversion of Control
Aspect	Traditional Control	Inversion of Control
Who calls whom	Application calls library	Framework calls application code
Object creation	Application creates objects explicitly	Framework creates objects on demand
Lifecycle management	Application tracks object lifetimes	Framework manages lifecycles
Configuration	Hardcoded in application	External, declarative configuration
Flow control	Application determines execution order	Framework orchestrates execution
Extension mechanism	Modify existing code	Implement interfaces, register callbacks

The Hollywood Principle

IoC is often summarized as the 'Hollywood Principle': Don't call us, we'll call you. Just as aspiring actors don't pester casting directors but wait to be contacted, application components don't actively seek dependencies but wait for the framework to provide them. This passive posture is key to achieving loose coupling.

From IoC to IoC Containers

IoC is a broad principle with many manifestations. Dependency Injection is one specific form of IoC—perhaps the most architecturally significant for application structure. And an IoC container is a specialized framework that automates dependency injection at scale.

Definition: IoC Container

An IoC container (also called a DI container or dependency injection container) is a framework component responsible for:

Creating objects — Instantiating classes when dependencies are needed
Managing lifecycles — Controlling when objects are created and destroyed
Resolving dependencies — Determining what concrete types satisfy abstract dependencies
Wiring the object graph — Connecting objects to their dependencies recursively

The term 'container' reflects that all your application's managed objects 'live' within this framework. The container is aware of every registered component, their dependencies, and their configuration. It acts as a central registry and factory for the entire application.

IoC Container Conceptual Model
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
// Conceptual model of what an IoC container provides
// (This is illustrative, not a real implementation)
 
interface IoCContainer {
  /**
   * Register a type with the container.
   * When someone needs IService, give them ConcreteService.
   */
  register<TInterface, TConcrete extends TInterface>(
    interfaceType: Constructor<TInterface>,
    concreteType: Constructor<TConcrete>,
    lifecycle?: Lifecycle
  ): void;
 
  /**
   * Resolve a dependency.
   * The container creates the object and all its dependencies.
   */
  resolve<T>(type: Constructor<T>): T;
 
  /**
   * Create a scope within which singleton-scoped objects live.
   * Useful for request-scoped dependencies in web apps.
   */
  createScope(): IContainerScope;
}
 
// Usage conceptually looks like:
container.register(ILogger, ConsoleLogger, Lifecycle.Singleton);
container.register(IUserRepository, PostgresUserRepository, Lifecycle.Scoped);
container.register(IUserService, UserService, Lifecycle.Transient);
 
// When we need a UserService, the container:
// 1. Creates a new UserService (transient)
// 2. Resolves IUserRepository → creates/reuses PostgresUserRepository
// 3. Resolves ILogger → reuses the singleton ConsoleLogger
// 4. Injects all dependencies into constructors
const userService = container.resolve(IUserService);

The Key Insight:

Without a container, dependency injection still requires someone to manually construct objects and wire them together. In a trivial application, this is manageable. In an enterprise application with hundreds of classes, manual wiring becomes a significant portion of the codebase—error-prone, hard to maintain, and scattered across multiple locations.

The container centralizes this responsibility. Registration happens in one place (or is automated through conventions). Resolution happens automatically. The container becomes the single source of truth for how objects are created and connected.

The Problem IoC Containers Solve

To appreciate IoC containers fully, let's examine what application composition looks like without one. Consider a moderately complex business application with layered architecture.

Manual Wiring Without Container

•Every dependency must be explicitly created
•Creation order must be manually managed
•Lifecycle management is ad-hoc
•Changes ripple through composition code
•Testing requires rebuilding object graphs
•Configuration is scattered across files
•Singleton management requires extra patterns

With IoC Container

•Container creates objects on demand
•Dependency graph resolved automatically
•Lifecycle policies declared, not coded
•Adding dependency = one registration
•Test configuration swaps implementations
•Configuration centralized and declarative
•Singletons are a lifecycle option

manual-wiring-problem.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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
// WITHOUT IOC CONTAINER: Manual Object Composition
// This is the "composition root" - where we wire everything together
 
function createApplication(): Application {
  // Infrastructure layer - must create first
  const config = new ConfigurationReader();
  const connectionString = config.get("DATABASE_URL");
  
  const logger = new ConsoleLogger(config.get("LOG_LEVEL"));
  const metricsClient = new PrometheusMetricsClient(config.get("METRICS_ENDPOINT"));
  
  // Data access layer - depends on infrastructure
  const dbConnection = new PostgresConnection(connectionString, logger);
  const userRepository = new PostgresUserRepository(dbConnection, logger);
  const orderRepository = new PostgresOrderRepository(dbConnection, logger);
  const productRepository = new PostgresProductRepository(dbConnection, logger);
  const inventoryRepository = new PostgresInventoryRepository(dbConnection, logger);
  
  // Caching layer - depends on infrastructure
  const redisClient = new RedisClient(config.get("REDIS_URL"), logger);
  const userCache = new RedisUserCache(redisClient, logger);
  const productCache = new RedisProductCache(redisClient, logger);
  
  // External services - depends on infrastructure
  const httpClient = new HttpClient(logger, metricsClient);
  const paymentGateway = new StripePaymentGateway(
    config.get("STRIPE_API_KEY"),
    httpClient,
    logger
  );
  const emailService = new SendGridEmailService(
    config.get("SENDGRID_API_KEY"),
    httpClient,
    logger
  );
  const notificationService = new NotificationService(emailService, logger);
  
  // Validation services
  const userValidator = new UserValidator();
  const orderValidator = new OrderValidator();
  const paymentValidator = new PaymentValidator();
  
  // Business services - depends on everything above
  const userService = new UserService(
    userRepository,
    userCache,
    userValidator,
    logger,
    metricsClient
  );
  
  const inventoryService = new InventoryService(
    inventoryRepository,
    productCache,
    logger,
    metricsClient
  );
  
  const orderService = new OrderService(
    orderRepository,
    inventoryService,
    paymentGateway,
    orderValidator,
    notificationService,
    logger,
    metricsClient
  );
  
  const checkoutService = new CheckoutService(
    userService,
    orderService,
    inventoryService,
    paymentValidator,
    logger,
    metricsClient
  );
  
  // Controllers - depends on business services
  const userController = new UserController(userService, logger);
  const orderController = new OrderController(orderService, checkoutService, logger);
  const productController = new ProductController(inventoryService, logger);
  
  // Middleware
  const authMiddleware = new AuthenticationMiddleware(userService, logger);
  const loggingMiddleware = new LoggingMiddleware(logger);
  const metricsMiddleware = new MetricsMiddleware(metricsClient);
  
  // Router
  const router = new Router([
    { path: "/users", controller: userController },
    { path: "/orders", controller: orderController },
    { path: "/products", controller: productController },
  ]);
  
  // Application
  return new Application(
    router,
    [loggingMiddleware, metricsMiddleware, authMiddleware],
    logger
  );
}
 
// PROBLEMS WITH THIS APPROACH:
// 1. This function is 80+ lines and growing
// 2. Order matters - PostgresConnection before PostgresUserRepository
// 3. Adding one dependency changes this file
// 4. Hard to test - can't easily swap implementations
// 5. No lifecycle management - all singletons? Who knows?
// 6. Configuration is interleaved with construction

The Maintenance Burden

This example shows ~25 objects being manually wired. Real enterprise applications often have hundreds. Every new service means updating this composition code. Every refactored dependency ripples through it. The composition root becomes a bottleneck for development velocity and a source of merge conflicts.

Core Services of an IoC Container

Every IoC container, regardless of language or framework, provides a core set of services. Understanding these services is essential for effective container usage.

Core Container Services

•Type Registration — The mechanism by which you tell the container 'when someone needs this interface, give them this implementation.' Registration creates the mapping between abstractions and concretions.
•Dependency Resolution — When you request a type, the container constructs it and all its dependencies recursively. This is automatic graph traversal—if A needs B and B needs C, requesting A creates C, then B, then A.
•Lifecycle Management — Different objects need different lifetimes. Some should be singletons (one instance forever). Some should be scoped (one instance per request). Some should be transient (new instance every time). The container manages this.
•Configuration Binding — Modern containers can bind configuration values (from files, environment, etc.) to objects, separating configuration from code entirely.
•Interception/AOP — Advanced containers support aspect-oriented programming, allowing you to wrap resolved objects with cross-cutting concerns like logging, caching, or transaction management.

Service 1: Type Registration

Registration tells the container about your types. There are several registration patterns:

Explicit Registration — You manually register each type mapping
Convention-Based Registration — Types are auto-registered based on naming conventions (e.g., IFoo maps to Foo)
Assembly Scanning — The container scans assemblies for types implementing certain interfaces
Attribute-Based Registration — Decorators/attributes on classes indicate registration

The choice of registration pattern affects development velocity and explicitness tradeoffs.

registration-patterns.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
// REGISTRATION PATTERNS ILLUSTRATED
 
// 1. EXPLICIT REGISTRATION - Most control, most verbose
container.register<IUserRepository, PostgresUserRepository>();
container.register<IOrderRepository, PostgresOrderRepository>();
container.register<IProductRepository, PostgresProductRepository>();
// ... repeat for every type
 
// 2. CONVENTION-BASED REGISTRATION - Less verbose, requires naming discipline
container.registerByConvention({
  // All classes implementing interfaces matching "I{Name}" → "{Name}"
  pattern: /^I(.+)$/,
  in: "./src/repositories",
});
 
// 3. ASSEMBLY/MODULE SCANNING - Automatic, requires marker interfaces
container.scan("./src/**/*.ts", {
  includeInterfaces: [IRepository, IService],
  lifecycle: Lifecycle.Scoped,
});
 
// 4. ATTRIBUTE/DECORATOR-BASED - Self-documenting, tight coupling to container
@Injectable({ lifecycle: "singleton" })
class ConsoleLogger implements ILogger {
  log(message: string) { console.log(message); }
}
 
// The container finds all @Injectable classes automatically

Service 2: Dependency Resolution

Resolution is where the magic happens. When you request a type, the container:

Looks up the registration for that type
Examines the constructor to find required dependencies
Recursively resolves each dependency
Creates instances according to lifecycle rules
Injects dependencies and returns the fully-constructed object

This process is transparent to your application code. You ask for IUserService; you get a fully-wired UserService with all its dependencies satisfied.

Converting Mermaid diagram...

Lifecycle Management In Depth

Object lifecycle is one of the most critical services an IoC container provides. Different objects have different lifetime requirements, and mixing these incorrectly is a common source of subtle bugs.

The Three Standard Lifecycles:

Standard Object Lifecycles
Lifecycle	Also Known As	Behavior	Use Cases
Singleton	Single Instance	One instance for entire application lifetime	Loggers, configuration, connection pools, caches
Scoped	Per-Request, Per-Session	One instance per scope (e.g., HTTP request)	Database contexts, user session data, unit of work
Transient	Per-Resolution, Per-Dependency	New instance every time resolved	Stateless services, validators, factories

The Captive Dependency Problem

A singleton that takes a scoped dependency captures a reference that outlives its intended lifetime. The first request creates the scoped dependency; all subsequent requests reuse that stale instance. This is called the 'captive dependency' problem and is a common IoC container pitfall. Most containers detect and warn about this misconfiguration.

lifecycle-examples.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
// LIFECYCLE MANAGEMENT EXAMPLES
 
// SINGLETON: Created once, reused forever
// Good for stateless infrastructure services
container.register<ILogger, ConsoleLogger>(Lifecycle.Singleton);
container.register<IConfiguration, AppConfiguration>(Lifecycle.Singleton);
container.register<IConnectionPool, PostgresConnectionPool>(Lifecycle.Singleton);
 
// SCOPED: Created once per scope (e.g., HTTP request)
// Good for stateful-per-request services
container.register<IDbContext, EfDbContext>(Lifecycle.Scoped);
container.register<ICurrentUser, HttpContextUser>(Lifecycle.Scoped);
container.register<IUnitOfWork, DatabaseUnitOfWork>(Lifecycle.Scoped);
 
// TRANSIENT: Created every time requested
// Good for stateless operations and when fresh state is required
container.register<IValidator, InputValidator>(Lifecycle.Transient);
container.register<IEmailBuilder, HtmlEmailBuilder>(Lifecycle.Transient);
container.register<ICommandHandler, ProcessOrderHandler>(Lifecycle.Transient);
 
// ============================================
// CAPTIVE DEPENDENCY ANTI-PATTERN
// ============================================
 
// ❌ WRONG: Singleton depends on Scoped
class BadUserCache implements IUserCache {
  constructor(
    private dbContext: IDbContext  // Scoped! Will be captured!
  ) {}
  
  getUser(id: string): User {
    // This dbContext was created for the first request
    // and will be reused incorrectly for all future requests
    return this.dbContext.users.findById(id);
  }
}
 
// ✅ CORRECT: Singleton depends on factory for scoped service
class GoodUserCache implements IUserCache {
  constructor(
    private dbContextFactory: () => IDbContext  // Factory function
  ) {}
  
  getUser(id: string): User {
    // Create fresh DbContext for each operation
    const dbContext = this.dbContextFactory();
    try {
      return dbContext.users.findById(id);
    } finally {
      dbContext.dispose();
    }
  }
}
 
// Registration with factory
container.register<IUserCache>(
  Lifecycle.Singleton,
  (resolver) => new GoodUserCache(
    () => resolver.resolve<IDbContext>()
  )
);

Scope Hierarchies:

Scopes often form hierarchies. An HTTP request scope might be a child of an application scope. A background job might create its own scope. Understanding scope hierarchy is crucial for proper lifecycle management.

Disposal and Cleanup:

Containers track disposable objects and dispose them when their scope ends. A scoped DbContext is automatically disposed when the request completes. This automatic resource management prevents resource leaks that manual composition often introduces.

The Composition Root

A critical architectural concept when using IoC containers is the Composition Root—the single location in an application where the container is configured and where the object graph is first resolved.

Definition:

The Composition Root is the application's entry point for dependency injection. It's where you:

Create the container
Configure all registrations
Resolve the root object(s) of the application
Hand control to the resolved objects

After the Composition Root, no application code should reference the container directly. The container is infrastructure, not a service locator to be passed around.

Container as Infrastructure, Not Service Locator

A common anti-pattern is injecting the container itself into classes and calling container.resolve() throughout the application. This is the Service Locator pattern—an anti-pattern that hides dependencies, makes code harder to test, and defeats the purpose of dependency injection. The container should be invisible after the Composition Root.

composition-root.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
// COMPOSITION ROOT PATTERN
 
// ===============================================
// 1. Container Setup (Composition Root)
// ===============================================
// File: src/main.ts or src/composition-root.ts
 
import { Container } from "./container";
import { InfrastructureModule } from "./modules/infrastructure.module";
import { DataAccessModule } from "./modules/data-access.module";
import { BusinessModule } from "./modules/business.module";
import { PresentationModule } from "./modules/presentation.module";
 
async function bootstrap() {
  // Create the container
  const container = new Container();
  
  // Configure registrations (often organized into modules)
  container.installModule(InfrastructureModule);
  container.installModule(DataAccessModule);
  container.installModule(BusinessModule);
  container.installModule(PresentationModule);
  
  // Resolve the root object
  const app = container.resolve<Application>(Application);
  
  // Hand control to the application
  // From here, the container is invisible to application code
  await app.start();
}
 
bootstrap().catch(console.error);
 
// ===============================================
// 2. Module Organization
// ===============================================
// File: src/modules/business.module.ts
 
export const BusinessModule: ContainerModule = {
  register(container: Container) {
    // All business layer registrations in one place
    container.register<IUserService, UserService>(Lifecycle.Scoped);
    container.register<IOrderService, OrderService>(Lifecycle.Scoped);
    container.register<IInventoryService, InventoryService>(Lifecycle.Scoped);
    container.register<IPaymentService, StripePaymentService>(Lifecycle.Scoped);
    container.register<INotificationService, NotificationService>(Lifecycle.Scoped);
  }
};
 
// ===============================================
// 3. Application Code - Container is Invisible
// ===============================================
// File: src/services/order-service.ts
 
// ✅ CORRECT: No container reference, pure constructor injection
class OrderService implements IOrderService {
  constructor(
    private readonly repository: IOrderRepository,
    private readonly inventory: IInventoryService,
    private readonly payment: IPaymentService,
    private readonly notifications: INotificationService,
    private readonly logger: ILogger
  ) {}
  
  async processOrder(order: Order): Promise<OrderResult> {
    // Business logic only - no container.resolve() calls
    await this.inventory.reserve(order.items);
    const paymentResult = await this.payment.charge(order.total);
    if (paymentResult.success) {
      const savedOrder = await this.repository.save(order);
      await this.notifications.sendConfirmation(savedOrder);
      return OrderResult.success(savedOrder);
    }
    return OrderResult.failure(paymentResult.error);
  }
}
 
// ❌ WRONG: Container used as Service Locator
class BadOrderService implements IOrderService {
  constructor(private container: IContainer) {}  // Anti-pattern!
  
  async processOrder(order: Order): Promise<OrderResult> {
    // Dependencies are hidden, not visible in constructor
    const repository = this.container.resolve<IOrderRepository>();
    const inventory = this.container.resolve<IInventoryService>();
    // ... harder to test, harder to understand dependencies
  }
}

IoC Containers and Testability

One of the most significant benefits of IoC containers is the testability they enable. By centralizing dependency configuration, you can easily swap implementations for testing without changing application code.

Testing Benefits of IoC Containers

•Unit Testing — Classes receive dependencies through constructors, making it trivial to provide mock implementations without container involvement
•Integration Testing — Create a test container configuration that swaps only specific services (e.g., in-memory database instead of PostgreSQL)
•Environment-Based Configuration — Container configuration can vary by environment—production, staging, test—allowing environment-appropriate implementations
•Stub Implementations — Register stub implementations for external services (payment gateways, email) during testing
•Scope Isolation — Each test can have its own container scope, ensuring tests don't leak state to each other

testing-with-ioc.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
92
93
94
95
96
97
98
99
100
// TESTING PATTERNS WITH IOC CONTAINERS
 
// ===============================================
// 1. Unit Tests - No Container Needed
// ===============================================
describe("OrderService", () => {
  it("should reserve inventory before charging payment", async () => {
    // Create mocks directly - no container required for unit tests
    const mockRepository = { save: jest.fn() };
    const mockInventory = { reserve: jest.fn() };
    const mockPayment = { 
      charge: jest.fn().mockResolvedValue({ success: true }) 
    };
    const mockNotifications = { sendConfirmation: jest.fn() };
    const mockLogger = { log: jest.fn() };
    
    // Inject mocks through constructor
    const service = new OrderService(
      mockRepository as any,
      mockInventory as any,
      mockPayment as any,
      mockNotifications as any,
      mockLogger as any
    );
    
    await service.processOrder(testOrder);
    
    // Assert order of operations
    expect(mockInventory.reserve).toHaveBeenCalledBefore(mockPayment.charge);
  });
});
 
// ===============================================
// 2. Integration Tests - Test Container Configuration  
// ===============================================
describe("OrderService Integration", () => {
  let container: Container;
  
  beforeEach(() => {
    container = new Container();
    
    // Keep most production registrations
    container.installModule(BusinessModule);
    
    // Override specific services for testing
    container.register<IOrderRepository, InMemoryOrderRepository>();
    container.register<IPaymentService, FakePaymentService>();
    container.register<INotificationService, NullNotificationService>();
    
    // Use real implementations for what we're actually testing
    // container.register<IInventoryService, InventoryService>(); // From module
  });
  
  afterEach(() => {
    container.dispose();
  });
  
  it("should process complete order flow", async () => {
    const scope = container.createScope();
    const service = scope.resolve<IOrderService>();
    
    const result = await service.processOrder(testOrder);
    
    expect(result.success).toBe(true);
    
    // Verify in-memory repository received the order
    const repository = scope.resolve<IOrderRepository>();
    expect(repository.findById(result.orderId)).toBeDefined();
  });
});
 
// ===============================================
// 3. Test Utilities - Container Factory
// ===============================================
function createTestContainer(overrides?: Partial<RegistrationMap>) {
  const container = new Container();
  
  // Base test configuration
  container.register<ILogger, NullLogger>();
  container.register<IMetrics, NullMetrics>();
  container.register<IConfiguration, TestConfiguration>();
  
  // Apply all production modules
  container.installModule(AllProductionModules);
  
  // Apply overrides for specific tests
  if (overrides) {
    for (const [type, implementation] of Object.entries(overrides)) {
      container.register(type, implementation);
    }
  }
  
  return container;
}
 
// Usage in tests:
const container = createTestContainer({
  IPaymentService: MockPaymentService,
  IEmailService: NullEmailService,
});

When to Use IoC Containers

IoC containers are powerful tools, but they're not universally appropriate. Understanding when they add value—and when they add unnecessary complexity—is a mark of engineering maturity.

Use IoC Containers When

•Application has many interdependent services
•Different environments need different implementations
•Testability is a priority
•Object lifecycle management is complex
•Team is familiar with DI principles
•Framework already includes container support
•Application will grow and evolve significantly

Consider Alternatives When

•Application is small and unlikely to grow
•Dependency graph is simple (few services)
•Team is unfamiliar with DI concepts
•Adding a container would be the only reason to add a framework dependency
•Performance-critical code paths can't afford reflection overhead
•Scripting or utility applications

The Alternative: Pure DI

For applications that don't warrant a full container, 'Pure DI' (also called 'Poor Man's DI') uses constructor injection without any container. You manually wire objects in a composition root. This is simpler, has no framework dependency, but scales poorly. For applications with 10-20 services, Pure DI is often sufficient. Beyond that, containers earn their keep.

Summary: The Role of IoC Containers

We've covered fundamental ground in understanding what IoC containers are and why they matter. Let's consolidate these insights:

Key Takeaways

•IoC inverts control flow — Frameworks call your code; your code doesn't call frameworks. This enables loose coupling and flexible architectures.
•IoC containers automate dependency injection — They create objects, resolve dependencies recursively, and manage lifecycles without manual wiring code.
•Containers provide core services — Type registration, dependency resolution, lifecycle management, and often configuration binding and AOP support.
•Lifecycle management prevents resource leaks — Singleton, scoped, and transient lifecycles ensure objects live exactly as long as needed.
•The Composition Root centralizes configuration — One location where the container is configured; after that, it's invisible to application code.
•Containers enable testability — Easy swapping of implementations for testing without changing business logic.
•Not always necessary — Simple applications may use Pure DI; containers add value as complexity grows.

What's Next:

Now that we understand what IoC containers are and the services they provide, the next page will dive into container configuration—the various approaches to registering types, organizing registrations into modules, and handling complex registration scenarios like open generics, decorators, and conditional registration.

Page Complete

You now understand the fundamental concepts of IoC containers: the inversion of control paradigm, how containers automate dependency injection, core container services, lifecycle management, the composition root pattern, and testability benefits. Next, we'll explore how to configure containers effectively.

1 / 4

Loading learning content...

What is an IoC Container - Inversion of Control Containers | OneNoughtOne

System Design (LLD)Inversion of Control Containers

Inversion of Control Containers

LevelIntermediate

Duration60 mins

TopicInversion of Control Containers

1 / 4

What is an IoC Container

The Missing Piece in Dependency Management

What You Will Learn

The Inversion of Control Paradigm

Traditional Control Flow:

Inverted Control Flow:

Traditional Control vs Inversion of Control
Aspect	Traditional Control	Inversion of Control
Who calls whom	Application calls library	Framework calls application code
Object creation	Application creates objects explicitly	Framework creates objects on demand
Lifecycle management	Application tracks object lifetimes	Framework manages lifecycles
Configuration	Hardcoded in application	External, declarative configuration
Flow control	Application determines execution order	Framework orchestrates execution
Extension mechanism	Modify existing code	Implement interfaces, register callbacks

The Hollywood Principle

From IoC to IoC Containers

Definition: IoC Container

An IoC container (also called a DI container or dependency injection container) is a framework component responsible for:

Creating objects — Instantiating classes when dependencies are needed
Managing lifecycles — Controlling when objects are created and destroyed
Resolving dependencies — Determining what concrete types satisfy abstract dependencies
Wiring the object graph — Connecting objects to their dependencies recursively

IoC Container Conceptual Model
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
// Conceptual model of what an IoC container provides
// (This is illustrative, not a real implementation)
 
interface IoCContainer {
  /**
   * Register a type with the container.
   * When someone needs IService, give them ConcreteService.
   */
  register<TInterface, TConcrete extends TInterface>(
    interfaceType: Constructor<TInterface>,
    concreteType: Constructor<TConcrete>,
    lifecycle?: Lifecycle
  ): void;
 
  /**
   * Resolve a dependency.
   * The container creates the object and all its dependencies.
   */
  resolve<T>(type: Constructor<T>): T;
 
  /**
   * Create a scope within which singleton-scoped objects live.
   * Useful for request-scoped dependencies in web apps.
   */
  createScope(): IContainerScope;
}
 
// Usage conceptually looks like:
container.register(ILogger, ConsoleLogger, Lifecycle.Singleton);
container.register(IUserRepository, PostgresUserRepository, Lifecycle.Scoped);
container.register(IUserService, UserService, Lifecycle.Transient);
 
// When we need a UserService, the container:
// 1. Creates a new UserService (transient)
// 2. Resolves IUserRepository → creates/reuses PostgresUserRepository
// 3. Resolves ILogger → reuses the singleton ConsoleLogger
// 4. Injects all dependencies into constructors
const userService = container.resolve(IUserService);

The Key Insight:

The Problem IoC Containers Solve

To appreciate IoC containers fully, let's examine what application composition looks like without one. Consider a moderately complex business application with layered architecture.

Manual Wiring Without Container

•Every dependency must be explicitly created
•Creation order must be manually managed
•Lifecycle management is ad-hoc
•Changes ripple through composition code
•Testing requires rebuilding object graphs
•Configuration is scattered across files
•Singleton management requires extra patterns

With IoC Container

•Container creates objects on demand
•Dependency graph resolved automatically
•Lifecycle policies declared, not coded
•Adding dependency = one registration
•Test configuration swaps implementations
•Configuration centralized and declarative
•Singletons are a lifecycle option

manual-wiring-problem.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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
// WITHOUT IOC CONTAINER: Manual Object Composition
// This is the "composition root" - where we wire everything together
 
function createApplication(): Application {
  // Infrastructure layer - must create first
  const config = new ConfigurationReader();
  const connectionString = config.get("DATABASE_URL");
  
  const logger = new ConsoleLogger(config.get("LOG_LEVEL"));
  const metricsClient = new PrometheusMetricsClient(config.get("METRICS_ENDPOINT"));
  
  // Data access layer - depends on infrastructure
  const dbConnection = new PostgresConnection(connectionString, logger);
  const userRepository = new PostgresUserRepository(dbConnection, logger);
  const orderRepository = new PostgresOrderRepository(dbConnection, logger);
  const productRepository = new PostgresProductRepository(dbConnection, logger);
  const inventoryRepository = new PostgresInventoryRepository(dbConnection, logger);
  
  // Caching layer - depends on infrastructure
  const redisClient = new RedisClient(config.get("REDIS_URL"), logger);
  const userCache = new RedisUserCache(redisClient, logger);
  const productCache = new RedisProductCache(redisClient, logger);
  
  // External services - depends on infrastructure
  const httpClient = new HttpClient(logger, metricsClient);
  const paymentGateway = new StripePaymentGateway(
    config.get("STRIPE_API_KEY"),
    httpClient,
    logger
  );
  const emailService = new SendGridEmailService(
    config.get("SENDGRID_API_KEY"),
    httpClient,
    logger
  );
  const notificationService = new NotificationService(emailService, logger);
  
  // Validation services
  const userValidator = new UserValidator();
  const orderValidator = new OrderValidator();
  const paymentValidator = new PaymentValidator();
  
  // Business services - depends on everything above
  const userService = new UserService(
    userRepository,
    userCache,
    userValidator,
    logger,
    metricsClient
  );
  
  const inventoryService = new InventoryService(
    inventoryRepository,
    productCache,
    logger,
    metricsClient
  );
  
  const orderService = new OrderService(
    orderRepository,
    inventoryService,
    paymentGateway,
    orderValidator,
    notificationService,
    logger,
    metricsClient
  );
  
  const checkoutService = new CheckoutService(
    userService,
    orderService,
    inventoryService,
    paymentValidator,
    logger,
    metricsClient
  );
  
  // Controllers - depends on business services
  const userController = new UserController(userService, logger);
  const orderController = new OrderController(orderService, checkoutService, logger);
  const productController = new ProductController(inventoryService, logger);
  
  // Middleware
  const authMiddleware = new AuthenticationMiddleware(userService, logger);
  const loggingMiddleware = new LoggingMiddleware(logger);
  const metricsMiddleware = new MetricsMiddleware(metricsClient);
  
  // Router
  const router = new Router([
    { path: "/users", controller: userController },
    { path: "/orders", controller: orderController },
    { path: "/products", controller: productController },
  ]);
  
  // Application
  return new Application(
    router,
    [loggingMiddleware, metricsMiddleware, authMiddleware],
    logger
  );
}
 
// PROBLEMS WITH THIS APPROACH:
// 1. This function is 80+ lines and growing
// 2. Order matters - PostgresConnection before PostgresUserRepository
// 3. Adding one dependency changes this file
// 4. Hard to test - can't easily swap implementations
// 5. No lifecycle management - all singletons? Who knows?
// 6. Configuration is interleaved with construction

The Maintenance Burden

Core Services of an IoC Container

Every IoC container, regardless of language or framework, provides a core set of services. Understanding these services is essential for effective container usage.

Core Container Services

•Type Registration — The mechanism by which you tell the container 'when someone needs this interface, give them this implementation.' Registration creates the mapping between abstractions and concretions.
•Dependency Resolution — When you request a type, the container constructs it and all its dependencies recursively. This is automatic graph traversal—if A needs B and B needs C, requesting A creates C, then B, then A.
•Lifecycle Management — Different objects need different lifetimes. Some should be singletons (one instance forever). Some should be scoped (one instance per request). Some should be transient (new instance every time). The container manages this.
•Configuration Binding — Modern containers can bind configuration values (from files, environment, etc.) to objects, separating configuration from code entirely.
•Interception/AOP — Advanced containers support aspect-oriented programming, allowing you to wrap resolved objects with cross-cutting concerns like logging, caching, or transaction management.

Service 1: Type Registration

Registration tells the container about your types. There are several registration patterns:

Explicit Registration — You manually register each type mapping
Convention-Based Registration — Types are auto-registered based on naming conventions (e.g., IFoo maps to Foo)
Assembly Scanning — The container scans assemblies for types implementing certain interfaces
Attribute-Based Registration — Decorators/attributes on classes indicate registration

The choice of registration pattern affects development velocity and explicitness tradeoffs.

registration-patterns.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
// REGISTRATION PATTERNS ILLUSTRATED
 
// 1. EXPLICIT REGISTRATION - Most control, most verbose
container.register<IUserRepository, PostgresUserRepository>();
container.register<IOrderRepository, PostgresOrderRepository>();
container.register<IProductRepository, PostgresProductRepository>();
// ... repeat for every type
 
// 2. CONVENTION-BASED REGISTRATION - Less verbose, requires naming discipline
container.registerByConvention({
  // All classes implementing interfaces matching "I{Name}" → "{Name}"
  pattern: /^I(.+)$/,
  in: "./src/repositories",
});
 
// 3. ASSEMBLY/MODULE SCANNING - Automatic, requires marker interfaces
container.scan("./src/**/*.ts", {
  includeInterfaces: [IRepository, IService],
  lifecycle: Lifecycle.Scoped,
});
 
// 4. ATTRIBUTE/DECORATOR-BASED - Self-documenting, tight coupling to container
@Injectable({ lifecycle: "singleton" })
class ConsoleLogger implements ILogger {
  log(message: string) { console.log(message); }
}
 
// The container finds all @Injectable classes automatically

Service 2: Dependency Resolution

Resolution is where the magic happens. When you request a type, the container:

Looks up the registration for that type
Examines the constructor to find required dependencies
Recursively resolves each dependency
Creates instances according to lifecycle rules
Injects dependencies and returns the fully-constructed object

This process is transparent to your application code. You ask for IUserService; you get a fully-wired UserService with all its dependencies satisfied.

Converting Mermaid diagram...

Lifecycle Management In Depth

The Three Standard Lifecycles:

Standard Object Lifecycles
Lifecycle	Also Known As	Behavior	Use Cases
Singleton	Single Instance	One instance for entire application lifetime	Loggers, configuration, connection pools, caches
Scoped	Per-Request, Per-Session	One instance per scope (e.g., HTTP request)	Database contexts, user session data, unit of work
Transient	Per-Resolution, Per-Dependency	New instance every time resolved	Stateless services, validators, factories

The Captive Dependency Problem

lifecycle-examples.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
// LIFECYCLE MANAGEMENT EXAMPLES
 
// SINGLETON: Created once, reused forever
// Good for stateless infrastructure services
container.register<ILogger, ConsoleLogger>(Lifecycle.Singleton);
container.register<IConfiguration, AppConfiguration>(Lifecycle.Singleton);
container.register<IConnectionPool, PostgresConnectionPool>(Lifecycle.Singleton);
 
// SCOPED: Created once per scope (e.g., HTTP request)
// Good for stateful-per-request services
container.register<IDbContext, EfDbContext>(Lifecycle.Scoped);
container.register<ICurrentUser, HttpContextUser>(Lifecycle.Scoped);
container.register<IUnitOfWork, DatabaseUnitOfWork>(Lifecycle.Scoped);
 
// TRANSIENT: Created every time requested
// Good for stateless operations and when fresh state is required
container.register<IValidator, InputValidator>(Lifecycle.Transient);
container.register<IEmailBuilder, HtmlEmailBuilder>(Lifecycle.Transient);
container.register<ICommandHandler, ProcessOrderHandler>(Lifecycle.Transient);
 
// ============================================
// CAPTIVE DEPENDENCY ANTI-PATTERN
// ============================================
 
// ❌ WRONG: Singleton depends on Scoped
class BadUserCache implements IUserCache {
  constructor(
    private dbContext: IDbContext  // Scoped! Will be captured!
  ) {}
  
  getUser(id: string): User {
    // This dbContext was created for the first request
    // and will be reused incorrectly for all future requests
    return this.dbContext.users.findById(id);
  }
}
 
// ✅ CORRECT: Singleton depends on factory for scoped service
class GoodUserCache implements IUserCache {
  constructor(
    private dbContextFactory: () => IDbContext  // Factory function
  ) {}
  
  getUser(id: string): User {
    // Create fresh DbContext for each operation
    const dbContext = this.dbContextFactory();
    try {
      return dbContext.users.findById(id);
    } finally {
      dbContext.dispose();
    }
  }
}
 
// Registration with factory
container.register<IUserCache>(
  Lifecycle.Singleton,
  (resolver) => new GoodUserCache(
    () => resolver.resolve<IDbContext>()
  )
);

Scope Hierarchies:

Disposal and Cleanup:

The Composition Root

Definition:

The Composition Root is the application's entry point for dependency injection. It's where you:

Create the container
Configure all registrations
Resolve the root object(s) of the application
Hand control to the resolved objects

After the Composition Root, no application code should reference the container directly. The container is infrastructure, not a service locator to be passed around.

Container as Infrastructure, Not Service Locator

composition-root.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
// COMPOSITION ROOT PATTERN
 
// ===============================================
// 1. Container Setup (Composition Root)
// ===============================================
// File: src/main.ts or src/composition-root.ts
 
import { Container } from "./container";
import { InfrastructureModule } from "./modules/infrastructure.module";
import { DataAccessModule } from "./modules/data-access.module";
import { BusinessModule } from "./modules/business.module";
import { PresentationModule } from "./modules/presentation.module";
 
async function bootstrap() {
  // Create the container
  const container = new Container();
  
  // Configure registrations (often organized into modules)
  container.installModule(InfrastructureModule);
  container.installModule(DataAccessModule);
  container.installModule(BusinessModule);
  container.installModule(PresentationModule);
  
  // Resolve the root object
  const app = container.resolve<Application>(Application);
  
  // Hand control to the application
  // From here, the container is invisible to application code
  await app.start();
}
 
bootstrap().catch(console.error);
 
// ===============================================
// 2. Module Organization
// ===============================================
// File: src/modules/business.module.ts
 
export const BusinessModule: ContainerModule = {
  register(container: Container) {
    // All business layer registrations in one place
    container.register<IUserService, UserService>(Lifecycle.Scoped);
    container.register<IOrderService, OrderService>(Lifecycle.Scoped);
    container.register<IInventoryService, InventoryService>(Lifecycle.Scoped);
    container.register<IPaymentService, StripePaymentService>(Lifecycle.Scoped);
    container.register<INotificationService, NotificationService>(Lifecycle.Scoped);
  }
};
 
// ===============================================
// 3. Application Code - Container is Invisible
// ===============================================
// File: src/services/order-service.ts
 
// ✅ CORRECT: No container reference, pure constructor injection
class OrderService implements IOrderService {
  constructor(
    private readonly repository: IOrderRepository,
    private readonly inventory: IInventoryService,
    private readonly payment: IPaymentService,
    private readonly notifications: INotificationService,
    private readonly logger: ILogger
  ) {}
  
  async processOrder(order: Order): Promise<OrderResult> {
    // Business logic only - no container.resolve() calls
    await this.inventory.reserve(order.items);
    const paymentResult = await this.payment.charge(order.total);
    if (paymentResult.success) {
      const savedOrder = await this.repository.save(order);
      await this.notifications.sendConfirmation(savedOrder);
      return OrderResult.success(savedOrder);
    }
    return OrderResult.failure(paymentResult.error);
  }
}
 
// ❌ WRONG: Container used as Service Locator
class BadOrderService implements IOrderService {
  constructor(private container: IContainer) {}  // Anti-pattern!
  
  async processOrder(order: Order): Promise<OrderResult> {
    // Dependencies are hidden, not visible in constructor
    const repository = this.container.resolve<IOrderRepository>();
    const inventory = this.container.resolve<IInventoryService>();
    // ... harder to test, harder to understand dependencies
  }
}

IoC Containers and Testability

Testing Benefits of IoC Containers

•Unit Testing — Classes receive dependencies through constructors, making it trivial to provide mock implementations without container involvement
•Integration Testing — Create a test container configuration that swaps only specific services (e.g., in-memory database instead of PostgreSQL)
•Environment-Based Configuration — Container configuration can vary by environment—production, staging, test—allowing environment-appropriate implementations
•Stub Implementations — Register stub implementations for external services (payment gateways, email) during testing
•Scope Isolation — Each test can have its own container scope, ensuring tests don't leak state to each other

testing-with-ioc.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
92
93
94
95
96
97
98
99
100
// TESTING PATTERNS WITH IOC CONTAINERS
 
// ===============================================
// 1. Unit Tests - No Container Needed
// ===============================================
describe("OrderService", () => {
  it("should reserve inventory before charging payment", async () => {
    // Create mocks directly - no container required for unit tests
    const mockRepository = { save: jest.fn() };
    const mockInventory = { reserve: jest.fn() };
    const mockPayment = { 
      charge: jest.fn().mockResolvedValue({ success: true }) 
    };
    const mockNotifications = { sendConfirmation: jest.fn() };
    const mockLogger = { log: jest.fn() };
    
    // Inject mocks through constructor
    const service = new OrderService(
      mockRepository as any,
      mockInventory as any,
      mockPayment as any,
      mockNotifications as any,
      mockLogger as any
    );
    
    await service.processOrder(testOrder);
    
    // Assert order of operations
    expect(mockInventory.reserve).toHaveBeenCalledBefore(mockPayment.charge);
  });
});
 
// ===============================================
// 2. Integration Tests - Test Container Configuration  
// ===============================================
describe("OrderService Integration", () => {
  let container: Container;
  
  beforeEach(() => {
    container = new Container();
    
    // Keep most production registrations
    container.installModule(BusinessModule);
    
    // Override specific services for testing
    container.register<IOrderRepository, InMemoryOrderRepository>();
    container.register<IPaymentService, FakePaymentService>();
    container.register<INotificationService, NullNotificationService>();
    
    // Use real implementations for what we're actually testing
    // container.register<IInventoryService, InventoryService>(); // From module
  });
  
  afterEach(() => {
    container.dispose();
  });
  
  it("should process complete order flow", async () => {
    const scope = container.createScope();
    const service = scope.resolve<IOrderService>();
    
    const result = await service.processOrder(testOrder);
    
    expect(result.success).toBe(true);
    
    // Verify in-memory repository received the order
    const repository = scope.resolve<IOrderRepository>();
    expect(repository.findById(result.orderId)).toBeDefined();
  });
});
 
// ===============================================
// 3. Test Utilities - Container Factory
// ===============================================
function createTestContainer(overrides?: Partial<RegistrationMap>) {
  const container = new Container();
  
  // Base test configuration
  container.register<ILogger, NullLogger>();
  container.register<IMetrics, NullMetrics>();
  container.register<IConfiguration, TestConfiguration>();
  
  // Apply all production modules
  container.installModule(AllProductionModules);
  
  // Apply overrides for specific tests
  if (overrides) {
    for (const [type, implementation] of Object.entries(overrides)) {
      container.register(type, implementation);
    }
  }
  
  return container;
}
 
// Usage in tests:
const container = createTestContainer({
  IPaymentService: MockPaymentService,
  IEmailService: NullEmailService,
});

When to Use IoC Containers

IoC containers are powerful tools, but they're not universally appropriate. Understanding when they add value—and when they add unnecessary complexity—is a mark of engineering maturity.

Use IoC Containers When

•Application has many interdependent services
•Different environments need different implementations
•Testability is a priority
•Object lifecycle management is complex
•Team is familiar with DI principles
•Framework already includes container support
•Application will grow and evolve significantly

Consider Alternatives When

•Application is small and unlikely to grow
•Dependency graph is simple (few services)
•Team is unfamiliar with DI concepts
•Adding a container would be the only reason to add a framework dependency
•Performance-critical code paths can't afford reflection overhead
•Scripting or utility applications

The Alternative: Pure DI

Summary: The Role of IoC Containers

We've covered fundamental ground in understanding what IoC containers are and why they matter. Let's consolidate these insights:

Key Takeaways

•IoC inverts control flow — Frameworks call your code; your code doesn't call frameworks. This enables loose coupling and flexible architectures.
•IoC containers automate dependency injection — They create objects, resolve dependencies recursively, and manage lifecycles without manual wiring code.
•Containers provide core services — Type registration, dependency resolution, lifecycle management, and often configuration binding and AOP support.
•Lifecycle management prevents resource leaks — Singleton, scoped, and transient lifecycles ensure objects live exactly as long as needed.
•The Composition Root centralizes configuration — One location where the container is configured; after that, it's invisible to application code.
•Containers enable testability — Easy swapping of implementations for testing without changing business logic.
•Not always necessary — Simple applications may use Pure DI; containers add value as complexity grows.

What's Next:

Page Complete

1 / 4