Class Container

Unified Container for DI management

Manages the two-tier container hierarchy:

Global scope: Singletons, base instances of request-scoped services
Request scope: Context-enriched instances per HTTP request

Example: Basic registration

import { container as tsyringeRootContainer } from 'tsyringe'

const container = new Container({
  env,
  ctx,
  container: tsyringeRootContainer.createChildContainer()
})

// Auto-extract token and scope from decorator
container.register(I18nService)

// Explicit token with auto-scope detection
container.register(MY_TOKEN, MyService)

// Explicit singleton registration
container.registerSingleton(ConfigService)

// Register a value
container.registerValue(MY_TOKEN, myInstance)

Example: Resolution

// Resolves from container
const service = container.resolve(MY_TOKEN)

Example: Request scope (automatic lifecycle)

await container.runInRequestScope(routerContext, async () => {
  const i18n = container.resolve(I18N_TOKEN)
  // i18n is context-enriched for this request
})

Example: Request scope (manual lifecycle)

const reqContainer = container.createRequestScope(routerContext)
await reqContainer.runWithContextStore(async () => {
  // use reqContainer...
})
// Cleanup is automatic

Index

Constructors

constructor

new Container(options: ContainerOptions): Container
Parameters
- options: ContainerOptions
Returns Container
- Defined in packages/core/src/di/container.ts:110

Accessors

logger

get logger(): LoggerService
Returns LoggerService
- Defined in packages/core/src/di/container.ts:125

Methods

createRequestScope

createRequestScope(routerContext: RouterContext): Container
Create request scope container

Use when you need manual control over the request container lifecycle, typically in middleware. Returns a new Container instance wrapping a request-scoped child container.

Can only be called on global container (not request-scoped).
Parameters
- routerContext: RouterContext
  RouterContext for the current request
Returns Container
Request-scoped Container instance
Example
```
const reqContainer = container.createRequestScope(routerContext)
await reqContainer.runWithContextStore(async () => {
  // use reqContainer...
})
// Cleanup is automatic
```
- Defined in packages/core/src/di/container.ts:479

dispose

dispose(): void | Promise<void>
Returns void | Promise<void>
- Defined in packages/core/src/di/container.ts:590

extend

extend<T>(token: InjectionToken<T>, decorator: ExtensionDecorator<T>): void
Replace a service registration with a decorated version

Resolves the current instance, applies the decorator, and re-registers the decorated instance. This is a one-time operation at initialization time.

IMPORTANT: This method can only be used in a module's onInitialize() method. The onInitialize() hook runs after all modules have registered their services via the @Module decorator, ensuring all dependencies are available for resolution.
Type Parameters
- T
Parameters
- token: InjectionToken<T>
  DI token of the service to extend
- decorator: ExtensionDecorator<T>
  Function that receives the service and returns decorated version
Returns void
Example: Add logging to database service (in onInitialize)
```
// In your module's onInitialize() method:
import type { OnInitialize, ModuleContext } from 'stratal/module'

@Module({ providers: [...] })
export class MyModule implements OnInitialize {
  onInitialize({ container }: ModuleContext): void {
    container.extend(DI_TOKENS.Database, (db, c) => {
      const logger = c.resolve(LOGGER_TOKENS.LoggerService)
      return new LoggingDatabaseDecorator(db, logger)
    })
  }
}
// DI_TOKENS.Database now resolves to LoggingDatabaseDecorator
```
Example: Chain multiple decorators
```
// In onInitialize()
container.extend(SERVICE_TOKEN, (svc) => new LoggingDecorator(svc))
container.extend(SERVICE_TOKEN, (svc) => new CachingDecorator(svc))
// SERVICE_TOKEN now resolves to CachingDecorator(LoggingDecorator(original))
```
- Defined in packages/core/src/di/container.ts:393

getRequestContainer

getRequestContainer(): DependencyContainer | undefined
Get current request container from context store (if in request context)

Returns DependencyContainer | undefined
Request container if in request context, undefined otherwise

Deprecated
Use container.runWithContextStore() instead
- Defined in packages/core/src/di/container.ts:547

getTsyringeContainer

getTsyringeContainer(): DependencyContainer
Get underlying tsyringe container

Use sparingly - prefer Container methods for most operations. Useful for advanced scenarios or compatibility with existing code.

Returns DependencyContainer
The underlying DependencyContainer
- Defined in packages/core/src/di/container.ts:538

isInRequestContext

isInRequestContext(): boolean
Check if currently in request context

Returns boolean
true if in request context (inside runInRequestScope or runWithContextStore)
- Defined in packages/core/src/di/container.ts:413

isRegistered

isRegistered<T>(token: InjectionToken<T>): boolean
Check if a token is registered
Type Parameters
- T
Parameters
- token: InjectionToken<T>
  DI token to check
Returns boolean
true if token is registered
- Defined in packages/core/src/di/container.ts:306

register

register<T extends object>(serviceClass: Constructor<T>, scope?: Scope): void
Register a service with optional explicit token and scope

Lifecycle is controlled via the scope parameter, which maps to tsyringe's Lifecycle. If no scope is provided, defaults to Transient (new instance per resolution).

register(serviceClass, scope?) - Use class as token register(token, serviceClass, scope?) - Explicit token
Type Parameters
- T extends object
Parameters
- serviceClass: Constructor<T>
- Optionalscope: Scope
Returns void
Example
```
container.register(MyService)  // Transient by default
container.register(MyService, Scope.Singleton)  // Singleton
container.register(MY_TOKEN, MyService, Scope.Request)  // Request-scoped with token
```
- Defined in packages/core/src/di/container.ts:150
register<T extends object>(
    token: InjectionToken<T>,
    serviceClass: Constructor<T>,
    scope?: Scope,
): void
Register a service with optional explicit token and scope

Lifecycle is controlled via the scope parameter, which maps to tsyringe's Lifecycle. If no scope is provided, defaults to Transient (new instance per resolution).

register(serviceClass, scope?) - Use class as token register(token, serviceClass, scope?) - Explicit token
Type Parameters
- T extends object
Parameters
- token: InjectionToken<T>
- serviceClass: Constructor<T>
- Optionalscope: Scope
Returns void
Example
```
container.register(MyService)  // Transient by default
container.register(MyService, Scope.Singleton)  // Singleton
container.register(MY_TOKEN, MyService, Scope.Request)  // Request-scoped with token
```
- Defined in packages/core/src/di/container.ts:151

registerExisting

registerExisting<T>(alias: InjectionToken<T>, target: InjectionToken<T>): void
Register an alias to an existing token

Creates a redirect so that resolving the alias token returns the same instance as the target token. This is useful for:
- Interface tokens that alias concrete implementations
- Multiple entry points to the same service
Type Parameters
- T
Parameters
- alias: InjectionToken<T>
  The alias token to register
- target: InjectionToken<T>
  The target token to redirect to
Returns void
Example: Interface abstraction
```
// Register concrete implementation
container.register(UserService)

// Create alias for interface token
container.registerExisting(I_USER_SERVICE, UserService)

// Both resolve to the same instance
const a = container.resolve(UserService)
const b = container.resolve(I_USER_SERVICE)
// a === b (same instance)
```
- Defined in packages/core/src/di/container.ts:276

registerFactory

registerFactory<T>(
token: InjectionToken<T>,
factory: (container: Container) => T,
): void
Register with factory function

Use when instance creation requires custom logic or other resolved dependencies.
Type Parameters
- T
Parameters
- token: InjectionToken<T>
  DI token for resolution
- factory: (container: Container) => T
  Factory function that receives the Container
Returns void
Example
```
container.registerFactory(FORMATTER_TOKEN, (c) => {
  const config = c.resolve(CONFIG_TOKEN)
  return config.get('logging').formatter === 'pretty'
    ? new PrettyFormatter()
    : new JsonFormatter()
}, Scope.Singleton)
```
- Defined in packages/core/src/di/container.ts:244

registerSingleton

registerSingleton<T extends object>(serviceClass: Constructor<T>): void
Register a service as singleton

Passthrough to tsyringe's registerSingleton method.

registerSingleton(serviceClass) - Use class as token registerSingleton(token, serviceClass) - Explicit token
Type Parameters
- T extends object
Parameters
- serviceClass: Constructor<T>
Returns void
Example
```
container.registerSingleton(LoggerService)  // Uses class as token
container.registerSingleton(CONFIG_TOKEN, ConfigService)  // Explicit token
```
- Defined in packages/core/src/di/container.ts:194
registerSingleton<T extends object>(
token: InjectionToken<T>,
serviceClass: Constructor<T>,
): void
Register a service as singleton

Passthrough to tsyringe's registerSingleton method.

registerSingleton(serviceClass) - Use class as token registerSingleton(token, serviceClass) - Explicit token
Type Parameters
- T extends object
Parameters
- token: InjectionToken<T>
- serviceClass: Constructor<T>
Returns void
Example
```
container.registerSingleton(LoggerService)  // Uses class as token
container.registerSingleton(CONFIG_TOKEN, ConfigService)  // Explicit token
```
- Defined in packages/core/src/di/container.ts:195

registerValue

registerValue<T>(token: InjectionToken<T>, value: T): void
Register a value (instance) directly

Use for registering pre-created instances or primitive values.
Type Parameters
- T
Parameters
- token: InjectionToken<T>
  DI token for resolution
- value: T
  Value to register
Returns void
Example
```
container.registerValue(CONFIG_TOKEN, configInstance)
container.registerValue(DI_TOKENS.Application, app)
```
- Defined in packages/core/src/di/container.ts:222

resolve

resolve<T>(token: InjectionToken<T>): T
Resolve a service from the container
Type Parameters
- T
Parameters
- token: InjectionToken<T>
  DI token for the service
Returns T
Resolved service instance
Example
```
const logger = container.resolve(LOGGER_TOKEN)
const config = container.resolve<IConfigService>(CONFIG_TOKEN)
```
- Defined in packages/core/src/di/container.ts:296

runInRequestScope

runInRequestScope<T>(
routerContext: RouterContext,
callback: () => T | Promise<T>,
): Promise<T>
Run callback within request scope

Creates a child container with fresh instances for services registered with scope: Scope.Request. Automatically handles lifecycle (setup and cleanup).

Also wraps with RequestContextStore for Zod i18n validation support.

Can only be called on global container (not request-scoped).
Type Parameters
- T
Parameters
- routerContext: RouterContext
  RouterContext for the current request
- callback: () => T | Promise<T>
  Async operation to run with request context
Returns Promise<T>
Result of callback execution
Example
```
await container.runInRequestScope(routerContext, async () => {
  const i18n = container.resolve(I18N_TOKEN)
  const message = i18n.t('common.welcome')
  // ...
})
```
- Defined in packages/core/src/di/container.ts:440

runWithContextStore

runWithContextStore<T>(callback: () => T | Promise<T>): Promise<T>
Run callback within request scope context store

Wraps callback with RequestContextStore (for Zod i18n validation) and automatically handles cleanup after callback completes.

Can only be called on request-scoped container (not global).
Type Parameters
- T
Parameters
- callback: () => T | Promise<T>
  Async operation to run with context
Returns Promise<T>
Result of callback execution
Example
```
const reqContainer = container.createRequestScope(routerContext)
await reqContainer.runWithContextStore(async () => {
  const i18n = reqContainer.resolve(I18N_TOKENS.I18nService)
  // ...
})
// Cleanup is automatic
```
- Defined in packages/core/src/di/container.ts:515

when

when(
predicate: (container: PredicateContainer) => boolean,
options?: WhenOptions,
): ConditionalBindingBuilder
Start a conditional binding with predicate evaluation

Creates a fluent builder for registering a service that chooses between two implementations based on a predicate evaluated at resolution time.
Parameters
- predicate: (container: PredicateContainer) => boolean
  Function that returns true/false to determine implementation. Receives a container with resolve() method for resolving dependencies.
- options: WhenOptions = {}
  Optional configuration (cache: whether to cache predicate result)
Returns ConditionalBindingBuilder
Fluent builder for specifying token and implementations
Example: Environment-based implementation selection
```
container
  .when((c) => c.resolve(CONFIG_TOKEN).get('env') === 'development')
  .use(FORMATTER_TOKEN)
  .give(PrettyFormatter)
  .otherwise(JsonFormatter)
```
Example: Feature flag with cached predicate
```
container
  .when((c) => c.resolve(FEATURE_FLAGS_TOKEN).isEnabled('newPaymentGateway'), { cache: true })
  .use(PAYMENT_TOKEN)
  .give(StripePaymentService)
  .otherwise(LegacyPaymentService)
```
- Defined in packages/core/src/di/container.ts:343

Class Container

Example: Basic registration

Example: Resolution

Example: Request scope (automatic lifecycle)

Example: Request scope (manual lifecycle)

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns Container

Accessors

logger

Returns LoggerService

Methods

createRequestScope

Parameters

Returns Container

Example

dispose

Returns void | Promise<void>

extend

Type Parameters

Parameters

Returns void

Example: Add logging to database service (in onInitialize)

Example: Chain multiple decorators

getRequestContainer

Returns DependencyContainer | undefined

Deprecated

getTsyringeContainer

Returns DependencyContainer

isInRequestContext

Returns boolean

isRegistered

Type Parameters

Parameters

Returns boolean

register

Type Parameters

Parameters

Returns void

Example

Type Parameters

Parameters

Returns void

Example

registerExisting

Type Parameters

Parameters

Returns void

Example: Interface abstraction

registerFactory

Type Parameters

Parameters

Returns void

Example

registerSingleton

Type Parameters

Parameters

Returns void

Example

Type Parameters

Parameters

Returns void

Example

registerValue

Type Parameters

Parameters

Returns void

Example

resolve

Type Parameters

Parameters

Returns T

Example

runInRequestScope

Type Parameters