Container

The Container is the central component of the dependency injection system. It is responsible for registering, resolving and managing the lifecycle of dependencies.

Import

import { Container } from "@brushy/di";

Creating a Container

// Basic container
const container = new Container();

// Container with initial providers
const container = new Container({
  providers: [
    {
      provide: "HTTP_CLIENT",
      useClass: HttpClient,
      lifecycle: "singleton",
      dependencies: ["CONFIG_SERVICE"],
    },
    {
      provide: "CONFIG_SERVICE",
      useValue: { apiUrl: "https://api.example.com" },
    },
    {
      provide: "LOGGER",
      useFactory: () => new Logger("app"),
      lifecycle: "transient",
    },
    {
      provide: "QUERY_CLIENT",
      useFactory: () => new QueryClient(),
      lifecycle: "immutable",
    },
  ],
  debug: true,
  name: "AppContainer",
});

Typed Tokens and Factory Dependencies

Use createToken<T>() so register and resolve infer types automatically. For factories, wrap dependencies with deps() to type the factory arguments:

import { Container, createToken, deps } from "@brushy/di";

const LOGGER = createToken<Logger>("LOGGER");
const USER_SERVICE = createToken<UserService>("USER_SERVICE");

const container = new Container();

container.register(LOGGER, { useClass: Logger });

container.register(USER_SERVICE, {
  useFactory: (logger) => new UserService(logger),
  dependencies: deps([LOGGER]), // logger: Logger
  lifecycle: "scoped",
});

const userService = container.resolve(USER_SERVICE); // UserService - no manual generic

Legacy tokens (string / Symbol) still work but need an explicit generic: container.resolve<UserService>("USER_SERVICE").

API

Dependency Registration

// Class registration
container.register("USER_SERVICE", {
  useClass: UserService,
  dependencies: ["HTTP_CLIENT", "LOGGER"],
});

// Value registration
container.register("API_URL", {
  useValue: "https://api.example.com",
});

// Factory registration
container.register("DATABASE", {
  useFactory: () => createDatabaseConnection(),
  lifecycle: "singleton",
});

// Immutable registration
container.register("QUERY_CLIENT", {
  useFactory: () => new QueryClient(),
  lifecycle: "immutable",
});

Dependency Resolution

// Synchronous resolution
const userService = container.resolve<UserService>("USER_SERVICE");

// Asynchronous resolution
const database = await container.resolveAsync<Database>("DATABASE");

Lifecycle Management

// Clear request scope
container.clearRequestScope();

// Start garbage collector
container.startGarbageCollector(60000, 30000);

// Stop garbage collector
container.stopGarbageCollector();

// Invalidate dependency cache
container.invalidateCache("USER_SERVICE");

// Verify immutable integrity
const verifyIntegrity = container.verifyImmutableIntegrity();
const isIntact = verifyIntegrity("QUERY_CLIENT");

React Integration

// Get a cached promise for use with the 'use' hook
const data = use(container.getPromise("HTTP_CLIENT", "fetchData", ["/users"]));

Observability

// Observe container events
const unsubscribe = container.observe((event) => {
  console.log(`Event: ${event.type}`, event);
});

// Stop observing
unsubscribe();

Import/Export

// Import providers from another container
container.import(otherContainer, {
  prefix: "other",
  overrideExisting: false,
});

// Export providers
const providers = container.exportProviders();

Debug Mode

The Container has a powerful debug mode that allows detailed visualization of the dependency resolution process. When enabled, it displays colored console logs showing:

Dependency registration
Dependency resolution
Dependency graph
Cached instances
Resolution errors and issues
Instance lifecycles

Enabling Debug Mode

// When creating the container
const container = new Container({
  debug: true,
  name: "AppContainer",
});

// Example log output
// [DEBUG] Resolved USER_SERVICE (UserServiceImpl) synchronously
// [DEBUG] Dependencies for USER_SERVICE: HTTP_CLIENT, LOGGER
// [INFO] Dependency Relationships:
// [DEBUG] • HTTP_CLIENT (HttpClientImpl) ← Used by: USER_SERVICE (UserServiceImpl)
// [DEBUG] • LOGGER (ConsoleLogger) ← Used by: USER_SERVICE (UserServiceImpl)

Logging System

The debug mode uses an internal logging system with color formatting for easy visualization:

INFO (green): General information and section titles
DEBUG (cyan): Details about dependency resolution and registration
WARN (yellow): Warnings about potential issues
ERROR (red): Critical errors like circular dependencies

Additionally, the logger uses specific colors for different types of information:

Tokens (magenta): Dependency identifiers
Classes (bright yellow): Implementation names
Lifecycle (bright cyan): Lifecycle types

// Example colored output (represented textually)
[INFO] Registered Tokens:
[DEBUG] • USER_SERVICE: UserServiceImpl (singleton)
[DEBUG] • HTTP_CLIENT: HttpClientImpl (singleton)
[DEBUG] • LOGGER: ConsoleLogger (transient)
[DEBUG] • QUERY_CLIENT: QueryClient (immutable)

[ERROR] Circular dependency detected: AUTH_SERVICE -> USER_SERVICE -> AUTH_SERVICE

Note: The logging system has an intelligent mechanism to prevent duplicate messages. Identical messages emitted within a 200ms interval are automatically suppressed, preventing console pollution during repetitive operations or loops.

Information Displayed in Debug Mode

Debug mode displays detailed information about:

Dependency Resolution: Shows when and how each dependency is resolved
[DEBUG] Resolved USER_SERVICE (UserServiceImpl) synchronously

Dependency Graph: Displays the complete dependency graph after first resolution

[INFO] Dependency Relationships:
[DEBUG] • HTTP_CLIENT (HttpClientImpl) ← Used by: USER_SERVICE (UserServiceImpl)

Cached Instances: Lists all currently cached instances

[INFO] Cached Instances:
[DEBUG] • HTTP_CLIENT (HttpClientImpl) - Last used: 10:30:45
[DEBUG] • QUERY_CLIENT (QueryClient) - Immutable

Problem Detection: Alerts about potential issues like circular dependencies

[ERROR] Circular dependency detected: USER_SERVICE -> AUTH_SERVICE -> USER_SERVICE

Instance Creation Process: Details how instances are created

[DEBUG] Creating instance of USER_SERVICE
[DEBUG] Dependencies for USER_SERVICE: HTTP_CLIENT, LOGGER
[DEBUG] Successfully created instance of USER_SERVICE (UserServiceImpl)

Promise Cache: Information about promise caching for asynchronous methods

[DEBUG] Using cached promise for HTTP_CLIENT.fetchData()
[DEBUG] Creating new promise for HTTP_CLIENT.fetchData()

Dependency Resolution Flow

Debug mode allows visualization of the complete dependency resolution flow:

Circular Dependency Check: First, checks for circular dependencies
Cache Check: Checks if the instance already exists in cache
Instance Creation: If not cached, creates a new instance
Dependency Resolution: Recursively resolves all required dependencies
Cache Storage: Stores the instance in cache according to configured lifecycle
Dependency Tracking: Records dependency relationships for future invalidation

When to Use Debug Mode

Debug mode is especially useful during:

Initial application development
Debugging dependency injection issues
Performance analysis and optimization
Understanding dependency resolution flow
Memory leak identification

Note: Debug mode can impact production performance, so it’s recommended to use it only in development environments.

Lifecycles

The container supports four types of lifecycles:

singleton: A single instance is created and reused (default)
transient: A new instance is created for each resolution
scoped: An instance is created per scope (e.g., per HTTP request)
immutable: A single instance is created and never invalidated or garbage collected

Lifecycle Comparison

Lifecycle	Creation	Invalidation	Garbage Collection	Recommended Use
singleton	Once	Yes	Yes	Stateless services
transient	Each injection	N/A	N/A	Factories, utilities
scoped	Per request	Per request	Per request	Request context
immutable	Once	Never	Never	State managers, Query clients

Immutable Lifecycle

The immutable lifecycle is particularly useful for:

State management libraries (React Query, Redux, Zustand)
API clients that need to maintain stable connections
Services that need to maintain consistent state across components

// React Query example
container.register(QUERY_CLIENT, {
  useFactory: () => new QueryClient(),
  lifecycle: "immutable" // Never invalidated
});

// Redux Store example
container.register(REDUX_STORE, {
  useFactory: () => createStore(rootReducer),
  lifecycle: "immutable"
});

Immutable Integrity Verification

The container provides a method to verify the integrity of immutable instances:

// Create a verifier function
const verifyIntegrity = container.verifyImmutableIntegrity();

// Check integrity
const isQueryClientIntact = verifyIntegrity(QUERY_CLIENT);
const isReduxStoreIntact = verifyIntegrity(REDUX_STORE);

if (!isQueryClientIntact || !isReduxStoreIntact) {
  console.error("Immutable integrity violation detected!");
  // Take appropriate action
}

This is useful for:

Debugging issues with state management
Ensuring critical services maintain their identity
Detecting unexpected modifications to immutable instances

Complete Example

// Define tokens
const HTTP_CLIENT = Symbol("HTTP_CLIENT");
const USER_SERVICE = Symbol("USER_SERVICE");
const API_CONFIG = Symbol("API_CONFIG");
const QUERY_CLIENT = Symbol("QUERY_CLIENT");

// Create container
const container = new Container({
  providers: [
    {
      provide: API_CONFIG,
      useValue: {
        baseUrl: "https://api.example.com",
        timeout: 5000,
      },
    },
    {
      provide: QUERY_CLIENT,
      useFactory: () => new QueryClient(),
      lifecycle: "immutable",
    },
  ],
  debug: true,
});

// Register dependencies
container.register(HTTP_CLIENT, {
  useClass: HttpClient,
  dependencies: [API_CONFIG],
  lifecycle: "singleton",
});

container.register(USER_SERVICE, {
  useClass: UserService,
  dependencies: [HTTP_CLIENT],
  lifecycle: "scoped",
});

// Resolve dependencies
const userService = container.resolve<UserService>(USER_SERVICE);
const users = await userService.getUsers();

// Verify immutable integrity
const verifyIntegrity = container.verifyImmutableIntegrity();
console.log("QueryClient integrity:", verifyIntegrity(QUERY_CLIENT));

// Clean up resources when done
container.clearRequestScope();

Introduction

@brushy/di-core

Guides

@brushy/di-monitor

React

Migration

Container

Container

Import

Creating a Container

Typed Tokens and Factory Dependencies

API

Dependency Registration

Dependency Resolution

Lifecycle Management

React Integration

Observability

Import/Export

Debug Mode

Enabling Debug Mode

Logging System

Information Displayed in Debug Mode

Dependency Resolution Flow

When to Use Debug Mode

Lifecycles

Lifecycle Comparison

Immutable Lifecycle

Immutable Integrity Verification

Complete Example

​Container

​Import

​Creating a Container

​Typed Tokens and Factory Dependencies

​API

​Dependency Registration

​Dependency Resolution

​Lifecycle Management

​React Integration

​Observability

​Import/Export

​Debug Mode

​Enabling Debug Mode

​Logging System

​Information Displayed in Debug Mode

​Dependency Resolution Flow

​When to Use Debug Mode

​Lifecycles

​Lifecycle Comparison

​Immutable Lifecycle

​Immutable Integrity Verification

​Complete Example

Container

Import

Creating a Container

Typed Tokens and Factory Dependencies

API

Dependency Registration

Dependency Resolution

Lifecycle Management

React Integration

Observability

Import/Export

Debug Mode

Enabling Debug Mode

Logging System

Information Displayed in Debug Mode

Dependency Resolution Flow

When to Use Debug Mode

Lifecycles

Lifecycle Comparison

Immutable Lifecycle

Immutable Integrity Verification

Complete Example