API Reference

Complete reference for all APIs provided by the DI framework.

Decorators

@Container(options?)

Marks a class as injectable and automatically registers it with the DI container.

Options:

singleton?: boolean (default: true) - Create a new instance each time or reuse the same instance
container?: DIContainer - Specify a custom container (defaults to global container)

Example:

import { Container } from 'di-framework/decorators';

// Singleton service (default)
@Container()
export class DatabaseService {
  connect() {
    console.log('Connected');
  }
}

// Non-singleton service
@Container({ singleton: false })
export class RequestScopedService {
  // New instance created for each resolution
}

// Custom container
import { Container as DIContainer } from 'di-framework/container';
const customContainer = new DIContainer();

@Container({ container: customContainer })
export class CustomService {
  // Registered in custom container
}

@Component(target)

Marks a constructor parameter or property for dependency injection.

Parameters:

target - The class to inject or a string identifier for factory-registered services

Example - Constructor Parameter:

@Container()
export class OrderService {
  constructor(@Component(DatabaseService) private db: DatabaseService) {}
}

Example - Property Injection:

@Container()
export class ReportService {
  @Component(DatabaseService)
  private db!: DatabaseService;
}

Example - Factory Service:

@Container()
export class UserService {
  constructor(@Component('config') private config: any) {}
}

Container API

useContainer()

Returns the global DI container instance.

Returns: Container

Example:

import { useContainer } from 'di-framework/container';

const container = useContainer();

container.register(serviceClass, options?)

Manually register a service class.

Parameters:

serviceClass - The class to register
options? - Registration options
- singleton?: boolean (default: true)

Example:

container.register(UserService, { singleton: true });

container.registerFactory(name, factory, options?)

Parameters:

name: string - Identifier for the service
factory: () => T - Factory function that creates the service instance
options? - Registration options
- singleton?: boolean (default: true)

Example:

container.registerFactory('config', () => ({
  apiKey: process.env.API_KEY,
  dbUrl: process.env.DATABASE_URL
}), { singleton: true });

// Use in services
@Container()
export class UserService {
  constructor(@Component('config') private config: any) {}
}

container.resolve(serviceClass)

Resolve and get an instance of a service.

Parameters:

serviceClass - The class or string identifier to resolve

Returns: Instance of the service with all dependencies injected

Example:

// By class
const userService = container.resolve<UserService>(UserService);

// By name (for factory-registered services)
const config = container.resolve('config');

container.has(serviceClass)

Check if a service is registered in the container.

Parameters:

serviceClass - The class or string identifier to check

Returns: boolean

Example:

if (container.has(UserService)) {
  const service = container.resolve(UserService);
}

container.getServiceNames()

Get all registered service names.

Returns: string[] - Array of all registered service identifiers

Example:

const names = container.getServiceNames();
console.log(names); // ['DatabaseService', 'UserService', ...]

container.on(event, listener) / container.off(event, listener)

Subscribe to container lifecycle events (observer pattern). Returns an unsubscribe function from on.

Events:

registered - { key, singleton, kind }
resolved - { key, instance, singleton, fromCache }
constructed - { key, instance, overrides }
cleared - { count }

Example:

const stop = container.on('resolved', ({ key, fromCache }) => {
  const name = typeof key === 'string' ? key : key.name;
  console.log(`Resolved ${name} (from cache: ${fromCache})`);
});

// Later, to unsubscribe
stop();

container.construct(serviceClass, overrides?)

Create a fresh instance without registering it, while still resolving dependencies. Use overrides to supply specific constructor arguments (by index) such as primitives or config values.

Example:

import { Component } from 'di-framework/decorators';
import { container } from 'di-framework/container';
import { LoggerService } from 'di-framework/services/LoggerService';

class Greeter {
  constructor(@Component(LoggerService) private logger: LoggerService, private greeting: string) {}
}

const greeter = container.construct(Greeter, { 1: 'Hello from config' });

container.fork(options?)

Clone all registrations into a new container (prototype pattern). Pass { carrySingletons: true } to reuse existing singleton instances; default is to start with fresh instances.

Example:

const child = container.fork({ carrySingletons: true });
const app = child.resolve(ApplicationContext); // shares singletons, isolated registrations

Lifecycle Methods

Services can optionally implement lifecycle methods that are called by the framework or your application code.

setEnv(env: Record<string, any>)

Called to initialize environment-specific configuration.

Example:

@Container()
export class DatabaseService {
  setEnv(env: Record<string, any>) {
    console.log('DB URL:', env.DATABASE_URL);
  }
}

const db = container.resolve(DatabaseService);
db.setEnv(process.env);

setCtx(context: any)

Called to set execution context (e.g., request context).

Example:

@Container()
export class RequestService {
  setCtx(context: any) {
    console.log('Context:', context);
  }
}

const service = container.resolve(RequestService);
service.setCtx({ userId: '123', requestId: 'abc' });

Types

Container

The DI container class.

class Container {
  register<T>(serviceClass: new (...args: any[]) => T, options?: { singleton?: boolean }): void;
  registerFactory<T>(name: string, factory: () => T, options?: { singleton?: boolean }): void;
  resolve<T>(serviceClass: new (...args: any[]) => T | string): T;
  has(serviceClass: any): boolean;
  getServiceNames(): string[];
}

Next Steps

Advanced Usage - Learn advanced patterns and techniques
Error Handling - Understand error scenarios and how to handle them
Testing - Learn how to test services with the DI framework

Last modified: 23 November 2025