InstanceWrapper

Kind: Class

Source: packages/core/injector/instance-wrapper.ts

Part of: Core

InstanceWrapper is the internal dependency-injection record for a provider, storing its token, metatype, scope, and resolved instances. It manages provider instances per request context or transient inquirer, while also retaining constructor and property dependency metadata used during resolution.

Methods

Properties

Where it refuses work

• InstanceWrapper stops the work with an early return when this.scope === Scope.TRANSIENT && inquirerId, in 3 places.
• InstanceWrapper stops the work with an early return when !this.isTransient, in 2 places.
• InstanceWrapper stops the work with an early return when !collection.
• InstanceWrapper stops the work with an early return when !isUndefined(this.isTreeDurable).
• InstanceWrapper stops the work with an early return when isStatic.
• InstanceWrapper stops the work with an early return when lookupRegistry.includes(this[INSTANCE_ID_SYMBOL]).

Diagram

mermaid
graph LR
  Injector[Injector / Resolver] --> Wrapper[InstanceWrapper]
  Wrapper --> Metadata[Constructor & Property Metadata]
  Wrapper --> ContextStore[Context ID Instance Store]
  Wrapper --> TransientStore[Inquirer ID Instance Store]
  ContextStore --> RequestInstance[InstancePerContext]
  TransientStore --> TransientInstance[InstancePerContext]

Usage

ts
import { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
import { ContextIdFactory } from '@nestjs/core/helpers/context-id-factory';

class LoggerService {
  log(message: string) {
    console.log(message);
  }
}

const loggerWrapper = new InstanceWrapper<LoggerService>({
  token: LoggerService,
  name: LoggerService.name,
  metatype: LoggerService,
});

const contextId = ContextIdFactory.create();

loggerWrapper.setInstanceByContextId(contextId, {
  instance: new LoggerService(),
  isResolved: true,
});

const instanceRecord = loggerWrapper.getInstanceByContextId(contextId);

instanceRecord.instance.log('Resolved from the current context');

// Remove request-scoped data when the context is no longer needed.
loggerWrapper.removeInstanceByContextId(contextId);

AI Coding Instructions

• Treat InstanceWrapper as DI-container infrastructure; application code should normally consume providers through injection instead of creating wrappers directly.
• Use getInstanceByContextId() and setInstanceByContextId() for request- or context-specific provider state.
• For transient providers, preserve the inquirer ID when reading or storing instances so each consumer receives the correct instance.
• Register constructor dependencies with addCtorMetadata() and property dependencies with addPropertiesMetadata() using the resolved dependency wrappers.
• Remove context-bound instances after a request or custom context completes to avoid retaining unnecessary scoped instances.

Used by

5 references from 5 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.

Imported by (5)

• ExceptionFiltersContext — packages/microservices/context/exception-filters-context.ts:16
• ListenersController — packages/microservices/listeners-controller.ts:45
• MicroservicesModule — packages/microservices/microservices-module.ts:23
• TestingInjector — packages/testing/testing-injector.ts:23
• SocketModule — packages/websockets/socket-module.ts:27