Class: Container

Defined in: src/wirestate-core/container/container.ts:119

Dependency injection container for one Wirestate scope.

Remarks

A container owns its local bindings and the instances created from them. It also owns provider lifecycle state and the plugin bindings installed on that container. Child containers inherit parent bindings while keeping their own local registrations and lifecycle state.

Throws

WirestateError If the config is invalid or activate names a token missing from bindings.

Example

import { Container, Injectable } from "@wirestate/core";

@Injectable()
class LoggerService {}

@Injectable()
class CounterService {}

const container: Container = new Container({
  bindings: [CounterService, LoggerService],
});

const loggerService: LoggerService = container.get(LoggerService);

Extends

• ContainerKernel

Constructors

Constructor

new Container(config?: ContainerConfig): Container;

Defined in: src/wirestate-core/container/container.ts:132

Creates a Wirestate container.

Parameters

Parameter	Type	Description
config	ContainerConfig	Container setup config.

Returns

Container

Throws

WirestateError If the config is invalid.

Overrides

ContainerKernel.constructor

Methods

assertBindable()

protected assertBindable<T>(descriptor: BindingDescriptor<T>): void;

Defined in: src/wirestate-core/container/container.ts:331

Enforces the ownership rules of the Wirestate lifecycle layer on a binding.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
descriptor	BindingDescriptor<T>	Descriptor about to be registered.

Returns

void

Remarks

Runs after structural validation, so a malformed descriptor reports its own error instead of a lifecycle one. An instance binding has its lifecycle declarations read here, which rejects a class hierarchy declaring two methods for one hook before the class can activate. A transient instance binding and a value or factory binding are rejected when their class declares handlers the container could never run for them. Finally, a handler-bearing binding cannot join a container that is already provisioned.

Throws

WirestateError If the binding kind cannot run the handlers its class declares, the class declares conflicting lifecycle hooks, or the container is provisioned.

Overrides

ContainerKernel.assertBindable

---

assertUsable()

protected assertUsable(): void;

Defined in: src/wirestate-core/container/container-kernel.ts:409

Throws when the container was destroyed.

Returns

void

Remarks

A destroyed container is a precondition failure rather than a structural miss, so this throws for { optional: true } lookups too - the same rule inject() applies outside an injection context. Without it a destroyed child would silently resolve its parent's bindings, handing callers the wrong scope.

Throws

WirestateError If the container was destroyed.

Inherited from

ContainerKernel.assertUsable

---

bind()

bind<T>(binding: 
  | Newable<object>
  | BindingDescriptor<T>): this;

Defined in: src/wirestate-core/container/container-kernel.ts:80

Binds a service class or a binding descriptor to this container, replacing any binding previously registered for the same token.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
binding	| Newable<object> | BindingDescriptor<T>	Service class or binding descriptor to register.

Returns

this

The same container for chaining.

Remarks

A bare class is its own token and binds as a singleton instance binding: container.bind(MyService) is equivalent to container.bind({ token: MyService, type: "Instance", value: MyService }).

The descriptor is validated structurally, then handed to the protected assertBindable hook so a composition root can add the ownership rules of its lifecycle layer.

Throws

WirestateError If the binding is invalid, the token's existing binding already constructed values, or a composition root rejects the binding kind.

Inherited from

ContainerKernel.bind

---

deprovision()

deprovision(): this;

Defined in: src/wirestate-core/container/container.ts:233

Deprovisions this container for a framework provider.

Returns

this

The same container for chaining.

Remarks

Runs @OnDeprovision in the exact reverse of provision order, so the first instance provisioned is the last one deprovisioned and a dependent tears down before the dependencies it injected. Idempotent: deprovisioning a container that is not currently provisioned is a no-op. Teardown methods called on this container from @OnDeprovision are also no-ops because the active transaction owns cleanup until every hook and disposer has finished.

---

destroy()

destroy(): this;

Defined in: src/wirestate-core/container/container.ts:305

Tears the container down for good: deprovisions it, then deactivates every instance it created, its own infrastructure included.

Returns

this

The same container for chaining.

Remarks

Terminal, unlike unbindAll: a destroyed container throws on any later bind, unbind, unbindAll, provision, or get, { optional: true } included. Inspection still works - has, hasOwn, getOwnBindings, and getActiveInstances do not throw. Call it when a provider unmounts or a test ends and the container will never be used again. Idempotent, and it deprovisions first, so teardown paths can call it on its own.

Example

const container: Container = new Container({ bindings: [CounterService] });

container.provision();
container.destroy();

Overrides

ContainerKernel.destroy

---

get()

Call Signature

get<T>(token: ServiceToken<T>): T;

Defined in: src/wirestate-core/container/container-kernel.ts:211

Retrieves a service from this container.

Resolution options can make a lookup optional or lazy. Optional lookups resolve undefined instead of throwing. Lazy lookups return a thunk that resolves on first call.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
token	ServiceToken<T>	Token to resolve.

Returns

T

The resolved value, thunk, or undefined for optional misses.

Throws

WirestateError If the token is not bound and not optional, or if a circular dependency is detected while constructing the value. Errors thrown by a binding's constructor or factory propagate unchanged.

Inherited from

ContainerKernel.get

Call Signature

get<T>(token: ServiceToken<T>, options: {
  optional: true;
}): Optional<T>;

Defined in: src/wirestate-core/container/container-kernel.ts:212

Retrieves a service from this container.

Resolution options can make a lookup optional or lazy. Optional lookups resolve undefined instead of throwing. Lazy lookups return a thunk that resolves on first call.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
token	ServiceToken<T>	Token to resolve.
options	{ optional: true; }	-
options.optional	true	-

Returns

Optional<T>

The resolved value, thunk, or undefined for optional misses.

Throws

WirestateError If the token is not bound and not optional, or if a circular dependency is detected while constructing the value. Errors thrown by a binding's constructor or factory propagate unchanged.

Inherited from

ContainerKernel.get

Call Signature

get<T>(token: ServiceToken<T>, options: {
  lazy: true;
}): () => T;

Defined in: src/wirestate-core/container/container-kernel.ts:213

Retrieves a service from this container.

Resolution options can make a lookup optional or lazy. Optional lookups resolve undefined instead of throwing. Lazy lookups return a thunk that resolves on first call.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
token	ServiceToken<T>	Token to resolve.
options	{ lazy: true; }	-
options.lazy	true	-

Returns

The resolved value, thunk, or undefined for optional misses.

() => T

Throws

WirestateError If the token is not bound and not optional, or if a circular dependency is detected while constructing the value. Errors thrown by a binding's constructor or factory propagate unchanged.

Inherited from

ContainerKernel.get

Call Signature

get<T>(token: ServiceToken<T>, options: {
  lazy: true;
  optional: true;
}): () => Optional<T>;

Defined in: src/wirestate-core/container/container-kernel.ts:214

Retrieves a service from this container.

Resolution options can make a lookup optional or lazy. Optional lookups resolve undefined instead of throwing. Lazy lookups return a thunk that resolves on first call.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
token	ServiceToken<T>	Token to resolve.
options	{ lazy: true; optional: true; }	-
options.lazy	true	-
options.optional	true	-

Returns

The resolved value, thunk, or undefined for optional misses.

() => Optional<T>

Throws

WirestateError If the token is not bound and not optional, or if a circular dependency is detected while constructing the value. Errors thrown by a binding's constructor or factory propagate unchanged.

Inherited from

ContainerKernel.get

Call Signature

get<T>(token: ServiceToken<T>, options?: {
  lazy?: false;
  optional?: boolean;
}): Optional<T>;

Defined in: src/wirestate-core/container/container-kernel.ts:215

Retrieves a service from this container.

Resolution options can make a lookup optional or lazy. Optional lookups resolve undefined instead of throwing. Lazy lookups return a thunk that resolves on first call.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
token	ServiceToken<T>	Token to resolve.
options?	{ lazy?: false; optional?: boolean; }	-
options.lazy?	false	-
options.optional?	boolean	-

Returns

Optional<T>

The resolved value, thunk, or undefined for optional misses.

Throws

WirestateError If the token is not bound and not optional, or if a circular dependency is detected while constructing the value. Errors thrown by a binding's constructor or factory propagate unchanged.

Inherited from

ContainerKernel.get

Call Signature

get<T>(token: ServiceToken<T>, options?: {
  lazy?: boolean;
  optional?: boolean;
}): Optional<T> | (() => Optional<T>);

Defined in: src/wirestate-core/container/container-kernel.ts:216

Retrieves a service from this container.

Resolution options can make a lookup optional or lazy. Optional lookups resolve undefined instead of throwing. Lazy lookups return a thunk that resolves on first call.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
token	ServiceToken<T>	Token to resolve.
options?	{ lazy?: boolean; optional?: boolean; }	-
options.lazy?	boolean	-
options.optional?	boolean	-

Returns

Optional<T> | (() => Optional<T>)

The resolved value, thunk, or undefined for optional misses.

Throws

WirestateError If the token is not bound and not optional, or if a circular dependency is detected while constructing the value. Errors thrown by a binding's constructor or factory propagate unchanged.

Inherited from

ContainerKernel.get

---

getActiveInstances()

getActiveInstances(): readonly object[];

Defined in: src/wirestate-core/container/container-kernel.ts:306

Returns the service instances this container constructed for singleton instance bindings, in creation order. Values constructed for value and factory bindings are not service instances and are not included. Transient instances are excluded too. They are construct-and-forget and never owned or tracked by the container.

Returns

readonly object[]

Snapshot of this container's active service instances.

Inherited from

ContainerKernel.getActiveInstances

---

getHotBinding()

protected getHotBinding<T>(binding: 
  | Newable<object>
  | BindingDescriptor<T>): 
  | Newable<object>
| BindingDescriptor<T>;

Defined in: src/wirestate-core/container/container-kernel.ts:390

Rewrites a binding to the newest generations of the classes it references.

Type Parameters

Type Parameter	Description
T	Bound value type.

Parameters

Parameter	Type	Description
binding	| Newable<object> | BindingDescriptor<T>	Binding supplied by the caller.

Returns

| Newable<object> | BindingDescriptor<T>

Binding to register.

Remarks

The registration counterpart of ContainerKernel.getHotToken, keeping registration keys consistent with lookups no matter which code path constructed the container. In production the guard folds away and this returns its argument.

Inherited from

ContainerKernel.getHotBinding

---

getHotToken()

protected getHotToken<T>(token: ServiceToken<T>): ServiceToken<T>;

Defined in: src/wirestate-core/container/container-kernel.ts:367

Rewrites a token to the newest generation of a hot-replaced class.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
token	ServiceToken<T>	Token supplied by the caller.

Returns

ServiceToken<T>

Token to look the binding up by.

Remarks

Development-only, and the single place that decision is made: every public API taking a token routes through it, so hot-reload support cannot drift between them. Modules that were not part of a hot update keep referencing an older generation of a replaced class, and this keeps those references answerable after a container hot swap.

The newest generation is used only when it is actually bound in this chain. Containers bound before the update, such as external containers no provider owns, keep the original token.

In production the guard folds away and this returns its argument.

Inherited from

ContainerKernel.getHotToken

---

getOwnBindings()

getOwnBindings(): readonly BindingDescriptor<unknown>[];

Defined in: src/wirestate-core/container/container-kernel.ts:294

Returns the binding descriptors registered on this container in registration order, ignoring parent containers.

Returns

readonly BindingDescriptor<unknown>[]

Snapshot of this container's own binding descriptors.

Inherited from

ContainerKernel.getOwnBindings

---

has()

has<T>(token: ServiceToken<T>): boolean;

Defined in: src/wirestate-core/container/container-kernel.ts:273

Returns whether this container or one of its parents has a binding for this token.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
token	ServiceToken<T>	Token to check.

Returns

boolean

Whether the token can be resolved from this container.

Inherited from

ContainerKernel.has

---

hasOwn()

hasOwn<T>(token: ServiceToken<T>): boolean;

Defined in: src/wirestate-core/container/container-kernel.ts:284

Returns whether this container itself has a binding for this token, ignoring parent containers.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
token	ServiceToken<T>	Token to check.

Returns

boolean

Whether this container owns a binding for the token.

Inherited from

ContainerKernel.hasOwn

---

provision()

provision(): this;

Defined in: src/wirestate-core/container/container.ts:211

Provisions this container for a framework provider.

Returns

this

The same container for chaining.

Remarks

Resolves provider lifecycle participants and runs @OnProvision once for this provision cycle, in creation order: a dependency provisions before the dependent that injected it. Participants unrelated by injection keep the order their bindings were registered in. A container is provisioned by at most one provider at a time. Provisioning an already provisioned container throws. Deprovision it first.

Throws

WirestateError If the container is already provisioned.

---

unbind()

unbind<T>(token: ServiceToken<T>): this;

Defined in: src/wirestate-core/container/container.ts:249

Unbinds a local token and deactivates values created from it.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
token	ServiceToken<T>	Token to unbind.

Returns

this

The same container for chaining.

Remarks

If the binding owns a provisioned provider lifecycle instance, @OnDeprovision runs before @OnDeactivation.

Overrides

ContainerKernel.unbind

---

unbindAll()

unbindAll(): this;

Defined in: src/wirestate-core/container/container.ts:274

Resets the container: unbinds every binding registered by the caller and deactivates the instances they created.

Returns

this

The same container for chaining.

Remarks

The container survives and can be re-populated and re-provisioned. Its own infrastructure stays bound - the Container self-binding and every binding a plugin's install contributed - so inject(Container) and the message buses keep resolving. Provider lifecycle instances are deprovisioned before they deactivate. Parent bindings and parent instances are not changed.

Use destroy to tear the container down for good.

Throws

WirestateError If the container was destroyed.

Overrides

ContainerKernel.unbindAll

Properties

parent?

readonly optional parent?: Container;

Defined in: src/wirestate-core/container/container.ts:123

Parent container when this container was created as a child container.

Overrides

ContainerKernel.parent