Dependency Injection System

Relevant source files

• integration/hello-world/e2e/middleware-execute-order.spec.ts
• packages/common/interfaces/modules/dynamic-module.interface.ts
• packages/common/interfaces/modules/provider.interface.ts
• packages/common/interfaces/nest-application-context.interface.ts
• packages/common/interfaces/scope-options.interface.ts
• packages/core/injector/container.ts
• packages/core/injector/injector.ts
• packages/core/injector/instance-loader.ts
• packages/core/injector/instance-wrapper.ts
• packages/core/injector/module-ref.ts
• packages/core/injector/module.ts
• packages/core/injector/topology-tree/topology-tree.ts
• packages/core/injector/topology-tree/tree-node.ts
• packages/core/nest-application-context.ts
• packages/core/scanner.ts
• packages/core/test/injector/container.spec.ts
• packages/core/test/injector/injector.spec.ts
• packages/core/test/injector/instance-wrapper.spec.ts
• packages/core/test/injector/module.spec.ts
• packages/core/test/scanner.spec.ts

The Dependency Injection (DI) system manages component instantiation, dependency resolution, and instance lifecycle in NestJS. The core consists of NestContainer (holds all modules), Injector (resolves and instantiates dependencies), Module (organizes providers), and InstanceWrapper (wraps provider instances with metadata).

Core Architecture

The DI system has four primary components that work together during application bootstrap and runtime:

DI System Component Interaction

Sources:

• packages/core/injector/container.ts31-367
• packages/core/injector/injector.ts86-1109
• packages/core/injector/module.ts44-680
• packages/core/injector/instance-wrapper.ts61-544
• packages/core/scanner.ts75-755
• packages/core/injector/instance-loader.ts11-116

NestContainer and Module Hierarchy

NestContainer maintains the module graph and coordinates global operations. Each Module instance stores providers, controllers, and injectables in separate maps, tracks imports/exports, and has a calculated distance from the root module.

Container Structure

The container hierarchy operates through these mechanisms:

1. Module Registration: NestContainer.addModule() calls ModuleCompiler.compile() to generate a unique token, then creates a Module instance and stores it in modules map at packages/core/injector/container.ts92-127

2. Provider Registration: Module.addProvider() creates an InstanceWrapper and adds it to _providers map. Custom providers use addCustomClass(), addCustomValue(), addCustomFactory(), or addCustomUseExisting() at packages/core/injector/module.ts244-285

3. Global Scope Binding: NestContainer.bindGlobalScope() iterates modules and calls bindGlobalsToImports() to link global modules to all other modules at packages/core/injector/container.ts318-333

4. Module Distance: DependenciesScanner.calculateModulesDistance() uses TopologyTree to calculate each module's depth from root, stored in Module.distance property at packages/core/scanner.ts397-416

Sources:

• packages/core/injector/container.ts31-367
• packages/core/injector/module.ts44-680
• packages/core/injector/instance-wrapper.ts61-544
• packages/core/scanner.ts397-416

Provider Types and Registration

NestJS supports four provider types defined in packages/common/interfaces/modules/provider.interface.ts10-167 Each type has distinct registration and instantiation behavior:

Provider Type	Interface	Module Method	InstanceWrapper Configuration
Class Provider	ClassProvider<T> with useClass	addCustomClass()	metatype: useClass, inject: null, constructor called
Value Provider	ValueProvider<T> with useValue	addCustomValue()	metatype: null, instance: useValue, isResolved: true
Factory Provider	FactoryProvider<T> with useFactory	addCustomFactory()	metatype: useFactory, inject: inject[], factory invoked
Existing Provider	ExistingProvider<T> with useExisting	addCustomUseExisting()	inject: [useExisting], isAlias: true, references existing

Provider Registration Flow

The registration process flows through DependenciesScanner:

1. reflectProviders() reads MODULE_METADATA.PROVIDERS from decorator metadata at packages/core/scanner.ts230-242
2. insertProvider() checks isCustomProvider() (has provide property) at packages/core/scanner.ts438-485
3. For standard classes: NestContainer.addProvider() → Module.addProvider() → creates InstanceWrapper with metatype set to class
4. For custom providers: Module.addCustomProvider() routes to specific handler based on type detection at packages/core/injector/module.ts305-324
5. Controllers use insertController() → NestContainer.addController() → Module.addController(), stored in _controllers map at packages/core/scanner.ts532-534
6. Injectables (guards, pipes, etc.) use insertInjectable() → NestContainer.addInjectable() → Module.addInjectable() with enhancerSubtype at packages/core/scanner.ts487-520

Sources:

• packages/core/injector/module.ts244-455
• packages/core/scanner.ts230-242
• packages/core/scanner.ts428-534
• packages/common/interfaces/modules/provider.interface.ts10-167

Dependency Resolution Process

Injector resolves dependencies through a multi-phase process involving metadata reflection, token resolution, recursive lookup across modules, and instance creation.

Complete Dependency Resolution Flow

Metadata Reflection Mechanism

Dependency metadata is extracted using reflect-metadata:

1. Constructor Parameters: reflectConstructorParams() reads PARAMTYPES_METADATA (set by TypeScript's emitDecoratorMetadata) at packages/core/injector/injector.ts440-448

2. Self-Declared Dependencies: reflectSelfParams() reads SELF_DECLARED_DEPS_METADATA (set by @Inject() decorator) at packages/core/injector/injector.ts454-456

3. Optional Dependencies: reflectOptionalParams() reads OPTIONAL_DEPS_METADATA (set by @Optional() decorator) at packages/core/injector/injector.ts450-452

4. Property Dependencies: reflectProperties() reads PROPERTY_DEPS_METADATA and OPTIONAL_PROPERTY_DEPS_METADATA at packages/core/injector/injector.ts795-805

5. Factory Dependencies: getFactoryProviderDependencies() processes the inject array, identifying OptionalFactoryDependency objects at packages/core/injector/injector.ts400-438

Cross-Module Lookup Algorithm

When a dependency is not found in the current module, lookupComponentInImports() performs a breadth-first search:

1. Maintains moduleRegistry: Set<string> to track visited modules and prevent infinite loops at packages/core/injector/injector.ts638-703
2. Filters moduleRef.imports by checking if traversing (only considers exported modules) at packages/core/injector/injector.ts653-658
3. For each imported module, checks exports.has(name) && providers.has(name) at packages/core/injector/injector.ts667
4. If not found, recursively calls itself with isTraversing = true parameter at packages/core/injector/injector.ts668-677
5. Calls loadProvider() for unresolved providers found in imports at packages/core/injector/injector.ts537-542

Instance Creation Strategy

instantiateClass() creates instances based on provider type at packages/core/injector/injector.ts819-863:

• Class providers: Checks isNil(inject), then executes new metatype(...instances) or merges with existing prototype if wrapper.forwardRef is true
• Factory providers: Calls metatype(...instances) and awaits if it returns a Promise
• Value providers: Already resolved, instance set during registration
• Existing providers: Resolves to the aliased provider's instance

The instance is passed through instanceDecorator() if configured (for instrumentation) and stored via setInstanceByContextId().

Sources:

• packages/core/injector/injector.ts128-205
• packages/core/injector/injector.ts290-388
• packages/core/injector/injector.ts440-487
• packages/core/injector/injector.ts575-636
• packages/core/injector/injector.ts638-703
• packages/core/injector/injector.ts705-793
• packages/core/injector/injector.ts819-863

Injection Scopes and Context Management

NestJS supports three injection scopes defined in packages/common/interfaces/scope-options.interface.ts4-19: DEFAULT, TRANSIENT, and REQUEST. Each scope uses different storage strategies in InstanceWrapper.

Scope-based Instance Storage Architecture

Instance Retrieval by Scope

InstanceWrapper.getInstanceByContextId() implements scope-specific retrieval logic at packages/core/injector/instance-wrapper.ts125-142:

DEFAULT scope:
  - Always returns instance from STATIC_CONTEXT
  - Single instance shared across entire application
  
REQUEST scope:
  - If contextId === STATIC_CONTEXT, returns from values.get(STATIC_CONTEXT)
  - Otherwise, returns from values.get(contextId) or clones static instance
  - Each HTTP request gets its own ContextId via createContextId()
  
TRANSIENT scope:
  - If inquirerId provided, calls getInstanceByInquirerId(contextId, inquirerId)
  - Uses transientMap.get(inquirerId).get(contextId)
  - Each consumer (parent provider) gets unique instances
  - Inquirer is the InstanceWrapper requesting the dependency

ContextId and Instance Isolation

ContextId is created per request and propagated through the resolution chain:

1. Creation: createContextId() generates {id: number} for each HTTP request at packages/core/helpers/context-id-factory.ts
2. Registration: NestContainer.registerRequestProvider() stores the request object with its ContextId at packages/core/injector/container.ts356-362
3. Propagation: All loadInstance() calls pass contextId parameter through the resolution tree
4. Durable Providers: Can have durable: true flag with REQUEST scope, making subtree persistent across requests via isDependencyTreeDurable() at packages/core/injector/instance-wrapper.ts234-264

Transient Provider Inquirer Mechanism

For TRANSIENT scope, the inquirer parameter identifies the parent requesting the dependency:

1. Inquirer Tracking: Each loadInstance() call passes inquirer?: InstanceWrapper parameter at packages/core/injector/injector.ts128-205
2. Inquirer ID Extraction: getInquirerId(inquirer) returns inquirer?.id at packages/core/injector/injector.ts964-968
3. Nested Transients: getEffectiveInquirer() handles TRANSIENT → TRANSIENT chains, returning parentInquirer for nested transients at packages/core/injector/injector.ts977-989
4. Instance Isolation: getInstanceByInquirerId() retrieves from transientMap.get(inquirerId).get(contextId) at packages/core/injector/instance-wrapper.ts144-157

This ensures each consumer of a transient provider gets its own instance, even within the same request context.

Sources:

• packages/core/injector/instance-wrapper.ts125-196
• packages/core/injector/injector.ts128-205
• packages/core/injector/injector.ts964-989
• packages/core/injector/instance-wrapper.ts300-320
• packages/core/injector/instance-wrapper.ts234-264
• packages/common/interfaces/scope-options.interface.ts4-38

Circular Dependency Handling

The DI system detects and resolves circular dependencies using SettlementSignal and forward references.

Circular Dependency Detection Flow

SettlementSignal Mechanism

SettlementSignal tracks the resolution chain to detect cycles at packages/core/injector/settlement-signal.ts1-50:

Resolution process:

1. applySettlementSignal() creates SettlementSignal and stores in wrapper.settlementSignal at packages/core/injector/injector.ts278-288
2. settlementSignal.insertRef(wrapper.id) adds current wrapper to resolution chain at packages/core/injector/injector.ts535
3. settlementSignal.isCycle(inquirer.id) checks if inquirer is already resolving at packages/core/injector/injector.ts143
4. If cycle detected, throws CircularDependencyException

Forward Reference Resolution

forwardRef() allows referencing classes before definition:

1. Detection: resolveParamToken() checks if param.forwardRef exists at packages/core/injector/injector.ts489-498
2. Marking: Sets wrapper.forwardRef = true flag
3. Extraction: Calls param.forwardRef() to get actual class token
4. Deferred Loading: In resolveComponentHost(), checks !instanceHost.isResolved && instanceWrapper.forwardRef at packages/core/injector/injector.ts543-563
5. Prototype Merging: For REQUEST/TRANSIENT with contextId, defers loading with donePromise.then()
6. Instance Assignment: Uses Object.assign(instanceHost.instance, new metatype(...)) to merge with pre-created prototype at packages/core/injector/injector.ts844-848

This enables:

• ServiceA depends on ServiceB (via forwardRef)
• ServiceB depends on ServiceA
• Both can resolve by creating prototypes first, then filling in dependencies

Optional Dependencies

Three mechanisms for optional dependencies:

1. Constructor Optionals: @Optional() decorator adds to OPTIONAL_DEPS_METADATA, checked in resolveConstructorParams() catch block at packages/core/injector/injector.ts379-384

2. Property Optionals: @Optional() on properties adds to OPTIONAL_PROPERTY_DEPS_METADATA, checked via item.isOptional in resolveProperties() at packages/core/injector/injector.ts782-786

3. Factory Optionals: OptionalFactoryDependency object with {token, optional: true} in inject array, processed by getFactoryProviderDependencies() at packages/core/injector/injector.ts400-438

When resolution fails and dependency is optional, returns undefined instead of throwing.

Sources:

• packages/core/injector/injector.ts141-151
• packages/core/injector/injector.ts278-288
• packages/core/injector/injector.ts489-498
• packages/core/injector/injector.ts523-573
• packages/core/injector/injector.ts844-848
• packages/core/injector/settlement-signal.ts1-50
• packages/core/injector/injector.ts379-384
• packages/core/injector/injector.ts774-786
• packages/core/injector/injector.ts400-438

InstanceWrapper Internal Structure

InstanceWrapper stores provider metadata and manages per-context instances using WeakMaps and internal metadata storage.

InstanceWrapper Architecture

Dependency Metadata Storage

InstanceWrapper maintains dependency metadata in INSTANCE_METADATA_SYMBOL internal property at packages/core/injector/instance-wrapper.ts55-59:

Metadata is populated by:

• addCtorMetadata(index, wrapper): Stores constructor param at index at packages/core/injector/instance-wrapper.ts198-203
• addPropertiesMetadata(key, wrapper): Stores property dependency at packages/core/injector/instance-wrapper.ts209-217
• addEnhancerMetadata(wrapper): Stores enhancer (guard/pipe/etc.) at packages/core/injector/instance-wrapper.ts223-228

Retrieved by:

• getCtorMetadata(): Returns dependencies array at packages/core/injector/instance-wrapper.ts205-207
• getPropertiesMetadata(): Returns properties array at packages/core/injector/instance-wrapper.ts219-221
• getEnhancersMetadata(): Returns enhancers array at packages/core/injector/instance-wrapper.ts230-232

Used by Injector to traverse dependency tree in introspectDepsAttribute() at packages/core/injector/instance-wrapper.ts266-298

Dependency Tree Analysis

InstanceWrapper analyzes its dependency tree to determine scope properties:

Static Tree Detection (isDependencyTreeStatic() at packages/core/injector/instance-wrapper.ts300-320):

• Returns false if wrapper has scope === Scope.REQUEST
• Recursively checks all dependencies, properties, enhancers
• Caches result in isTreeStatic property
• Used to determine if wrapper can be singleton

Durable Tree Detection (isDependencyTreeDurable() at packages/core/injector/instance-wrapper.ts234-264):

• For REQUEST scope: returns durable ?? false
• For non-REQUEST: checks if all dependencies are durable
• Recursively introspects dependency tree
• Caches result in isTreeDurable property
• Enables partial DI tree persistence across requests

Module Distance Calculation

DependenciesScanner.calculateModulesDistance() uses TopologyTree to compute module distances from root at packages/core/scanner.ts397-416:

TopologyTree builds an acyclic tree:

1. Creates TreeNode for each module with parent/children relationships at packages/core/injector/topology-tree/topology-tree.ts8-15
2. traverseAndMapToTree() processes imports recursively, handling cycles at packages/core/injector/topology-tree/topology-tree.ts25-56
3. If module already visited but at shallower depth, calls relink() to move closer to root at packages/core/injector/topology-tree/tree-node.ts19-24
4. walk() performs depth-first traversal to set distances at packages/core/injector/topology-tree/topology-tree.ts17-23

Distance is used for lifecycle hook execution order (modules sorted by distance in getModulesToTriggerHooksOn() at packages/core/nest-application-context.ts490-504).

Sources:

• packages/core/injector/instance-wrapper.ts61-544
• packages/core/injector/instance-wrapper.ts198-232
• packages/core/injector/instance-wrapper.ts234-320
• packages/core/scanner.ts397-416
• packages/core/injector/topology-tree/topology-tree.ts4-57
• packages/core/injector/topology-tree/tree-node.ts1-65

Bootstrap and Instance Loading

The DI system initializes during application bootstrap through a coordinated sequence of scanning, registration, and instantiation.

Application Bootstrap Sequence

InstanceLoader Orchestration

InstanceLoader.createInstancesOfDependencies() orchestrates the two-phase loading at packages/core/injector/instance-loader.ts25-60:

Phase 1: Prototype Creation

• Calls createPrototypes(modules) at packages/core/injector/instance-loader.ts40-46
• For each module: createPrototypesOfProviders(), createPrototypesOfInjectables(), createPrototypesOfControllers()
• Injector.loadPrototype() calls wrapper.createPrototype() which executes Object.create(metatype.prototype) at packages/core/injector/instance-wrapper.ts358-364
• Creates empty prototype objects before dependency resolution

Phase 2: Instance Creation

• Calls createInstances(modules) with parallel resolution using Promise.all() at packages/core/injector/instance-loader.ts48-60
• For each module: createInstancesOfProviders(), createInstancesOfInjectables(), createInstancesOfControllers()
• Each calls respective Injector.loadProvider/loadInjectable/loadController() methods
• All delegate to Injector.loadInstance() for actual instantiation
• GraphInspector.inspectInstanceWrapper() records resolution for debugging

Global Provider Application

After instance loading, global enhancers (guards, pipes, interceptors, filters) are registered:

1. DependenciesScanner.addScopedEnhancersMetadata() at packages/core/scanner.ts629-649:

   • Iterates applicationProvidersApplyMap (APP_GUARD, APP_PIPE, etc.)
   • For REQUEST/TRANSIENT scope enhancers, adds to all controllers' metadata via addEnhancerMetadata()

2. DependenciesScanner.applyApplicationProviders() at packages/core/scanner.ts651-688:

   • Gets instance from module's providers or injectables map
   • Calls ApplicationConfig.addGlobalInterceptor/Guard/Pipe/Filter() for DEFAULT scope
   • Calls ApplicationConfig.addGlobalRequestInterceptor/Guard/Pipe/Filter() for REQUEST/TRANSIENT scope
   • Global enhancers stored in ApplicationConfig and applied during request pipeline

Sources:

• packages/core/injector/instance-loader.ts11-116
• packages/core/injector/injector.ts109-276
• packages/core/scanner.ts86-104
• packages/core/scanner.ts629-688
• packages/core/injector/instance-wrapper.ts358-364

Integration with Application Lifecycle

The DI system integrates deeply with NestJS application lifecycle through several key processes:

Application Bootstrap Integration

System Integration Points

1. Module System: The DependenciesScanner uses reflectImports(), reflectProviders(), reflectControllers() to build the module dependency graph
2. Request Contexts: NestApplicationContext.registerRequestByContextId() integrates with the REQUEST scope for per-request provider instances
3. Enhancers System: Guards, interceptors, pipes are registered via insertInjectable() with specific enhancerSubtype values
4. Application Context: NestApplicationContext.get() and resolve() methods delegate to the DI system through find() and resolvePerContext()

The InstanceLoader coordinates the creation of all instances during application startup, calling createInstancesOfProviders(), createInstancesOfControllers(), and createInstancesOfInjectables() in sequence.

Sources:

• packages/core/nest-factory.ts200-244
• packages/core/nest-application-context.ts67-80
• packages/core/nest-application-context.ts135-174
• packages/core/scanner.ts86-104
• packages/core/injector/instance-loader.ts25-60
• packages/core/scanner.ts282-332

Conclusion

The NestJS Dependency Injection system provides a powerful foundation for the framework, enabling modular, testable, and maintainable applications. Its sophisticated dependency resolution, scoping mechanisms, and circular dependency handling make it suitable for complex enterprise applications while remaining performant and intuitive to use.

The DI system is built on solid OOP principles and inspired by Angular's DI system, providing a familiar experience for developers coming from that ecosystem while adding unique features tailored for server-side NodeJS applications.