@half0wl/container / Container
Class: Container<TDeps>
Defined in: container.ts:31
A dependency injection container that lazily creates and caches singleton service instances.
Supports both a global singleton (via Container.getGlobalInstance) and isolated instances (via Container.create) for test environments.
Example
// Production usage
const container = Container.create<ContainerDeps>({ db, logger });
const auth = container.get(AuthService);
// Test usage (isolated)
const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });
testContainer.register(UserService, mockUserService);
const auth = testContainer.get(AuthService);Type Parameters
| Type Parameter | Default type | Description |
|---|---|---|
TDeps | unknown | User-defined dependency interface |
Implements
Methods
clear()
clear(): void;Defined in: container.ts:202
Clear all cached service instances.
After calling this, the next get call for any service will construct a fresh instance. Does not clear deps or config.
Returns
void
get()
get<T>(serviceClass): T;Defined in: container.ts:140
Resolve a service by its class constructor.
On first call, lazily constructs the service with { ...deps, registry: this } and caches the singleton. Subsequent calls return the cached instance.
If the service was decorated with @Service({ trace: true }), all its methods are automatically wrapped with the configured trace function.
Type Parameters
| Type Parameter | Description |
|---|---|
T | The service type |
Parameters
| Parameter | Type | Description |
|---|---|---|
serviceClass | Constructor<T> | The class constructor to resolve |
Returns
T
The singleton instance
Throws
If deps have not been set
Throws
If the service has tracing enabled but no trace function was configured
Implementation of
register()
register<T>(serviceClass, instance): void;Defined in: container.ts:192
Register a pre-built instance for a service class.
The registered instance is returned by get without constructing. Primarily used for injecting test mocks.
Type Parameters
| Type Parameter | Description |
|---|---|
T | The service type |
Parameters
| Parameter | Type | Description |
|---|---|---|
serviceClass | Constructor<T> | The class constructor to associate with the instance |
instance | T | The pre-built instance to register |
Returns
void
Example
const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });
testContainer.register(UserService, mockUserService);
const auth = testContainer.get(AuthService); // uses mockUserService via @InjectsetDeps()
setDeps(deps): void;Defined in: container.ts:121
Set or replace the dependencies after container creation.
Useful for lazy initialization patterns where the container is created before deps are available.
Parameters
| Parameter | Type | Description |
|---|---|---|
deps | TDeps | The user-defined dependencies |
Returns
void
create()
static create<TDeps>(depsOrConfig?): Container<TDeps>;Defined in: container.ts:71
Create a new container instance.
Accepts either a plain deps object or a ContainerConfig with additional options like trace. When called with no arguments, the container defers resolution until setDeps is called.
Type Parameters
| Type Parameter | Description |
|---|---|
TDeps | User-defined dependency interface |
Parameters
| Parameter | Type | Description |
|---|---|---|
depsOrConfig? | TDeps | ContainerConfig<TDeps> | Dependencies or full configuration object |
Returns
Container<TDeps>
A new isolated container instance
Example
// Simple — pass deps directly
const container = Container.create<ContainerDeps>({ db, logger });
// With config — pass options alongside deps
const container = Container.create<ContainerDeps>({
deps: { db, logger },
trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),
});
// Lazy — set deps later
const container = Container.create<ContainerDeps>();
container.setDeps({ db, logger });getGlobalInstance()
static getGlobalInstance<TDeps>(): Container<TDeps>;Defined in: container.ts:95
Get the global singleton container instance.
Creates one on first call. Useful for module-level exports that need a container reference before deps are available.
Type Parameters
| Type Parameter | Description |
|---|---|
TDeps | User-defined dependency interface |
Returns
Container<TDeps>
The global container instance
resetGlobal()
static resetGlobal(): void;Defined in: container.ts:108
Reset the global singleton container.
Clears all cached instances and removes the global reference. Primarily used for test cleanup.
Returns
void