Class Container

The DI container can be used to register and resolve dependencies automatically. It supports constructor injection and property injection of dependencies. There are two built-in lifecycle policies: LifecyclePolicy.singleton and LifecyclePolicy.transient.

The DI framework uses two decorators to mark classes and properties as injectable:

injectable to mark a class as injectable
inject to mark a property or constructor parameter as injectable

When creating a class through the container, constructor parameters will automatically be resolved by type. When creating a class outside of the container, constructor parameters will not be resolved.

Injectable properties are resolved lazily when they are first accessed and are cached for subsequent access on a unique symbol on the instance for which they are resolved. Resolution of injectable properties uses the container that created the instance. If the instance was created outside of a container, the root container is used to try and resolve the dependency.

When the container cannot resolve a dependency it will return undefined for properties and constructor parameters marked with inject decorator.

The DI framework requires the following tsconfig settings to be enabled:

emitDecoratorMetadata: true (required to emit type metadata for decorated classes and properties)
experimentalDecorators: true (required to use decorators at all)
useDefineForClassFields: false (required in order to use inject)

@example:

@injectable()
class Bar {
   constructor(private foo: Foo) {
   }

   public helloFooBar() {
       this.foo.helloBar();
   }

   public hello() {
       console.log('Hello!');
   }
}

@injectable()
class Foo {
   constructor(public bar: Bar) {
   }

   public helloBar() {
       this.bar.hello();
   }
}

container.new(Foo).helloBar(); // prints 'Hello!'
container.new(Foo).bar.helloFooBar(); // prints 'Hello!'

Constructors

constructor

new Container(logger?: Logger, parent?: Container): Container
Parameters
- logger: Logger = ...
- Optionalparent: Container
Returns Container
- Defined in packages/core/src/di/container.ts:181

Properties

`Private` `Readonly`containerGuid

containerGuid: string = ...

`Private` `Readonly`containerPath

containerPath: string

`Private` `Readonly`factories

factories: Map<string, { lifecycle?: LifecyclePolicy; new: TypeFactory }> = ...

`Private` `Readonly`instances

instances: Map<string, any> = ...

`Private` `Readonly`logger

logger: Logger = ...

`Private` `Optional` `Readonly`parent

parent?: Container

`Private` `Readonly`providers

providers: Map<string, (receiver: any) => any> = ...

`Private` `Readonly`resolveStack

resolveStack: string[] = ...

`Private` `Readonly`serviceDependencies

serviceDependencies: Map<string, string[]> = ...

`Private` `Readonly`servicesProvided

servicesProvided: symbol = ...

`Private` `Readonly`serviceTypes

serviceTypes: Map<string, { ctor: TypeConstructor; options?: ServiceOptions }[]> = ...

useInstanceProxies

useInstanceProxies: boolean = false

Wrap all instance created by this container in Proxies. When set to true each service instance created by this container is wrapped in a Proxy. Proxied service instances behave the same way as non-proxied service instances but each call will be routed through the proxy which can impact performance.

For now the recommended setting is false unless you need to dynamically swap service instances without recreated the dependencies that use them.

For circular references proxies will always be used even when useInstanceProxies is set to false

`Static` `Readonly`root

root: Container

Global root container; by default all services are contained in there

Accessors

isRoot

get isRoot(): boolean
Returns true if this container is the root container of the application. The root container is the container that is created by default and contains all services by default.

Returns boolean
- Defined in packages/core/src/di/container.ts:166

`Static`scope

get scope(): Container
Get's the current container instance from which dependencies are resolved. Set during resolution phase allowing child entities to be resolved from the same context as their parent.

Returns Container
- Defined in packages/core/src/di/container.ts:140

Methods

add

add<T extends object, I extends object = T>(
instanceOrType: I | TypeConstructor,
options?: Partial<ServiceOptions & { provides: ObjectType<T>[] }>,
): void
Register a new service instance or type in this container. If the added entity is an instance it will be treated as singleton even if the lifecycle is transient.
Type Parameters
- T extends object
- I extends object = T
Parameters
- instanceOrType: I | TypeConstructor
 the service instance
- Optionaloptions: Partial<ServiceOptions & { provides: ObjectType<T>[] }>
 optional service options
Returns void
- Defined in packages/core/src/di/container.ts:551

`Private`addInstance

addInstance<T extends object, I extends object = T>(
instanceOrType: I,
options?: Partial<ServiceOptions & { provides: ObjectType<T>[] }>,
): void
Type Parameters
- T extends object
- I extends object = T
Parameters
- instanceOrType: I
- Optionaloptions: Partial<ServiceOptions & { provides: ObjectType<T>[] }>
Returns void
- Defined in packages/core/src/di/container.ts:580

`Private`addType

addType<T extends object, I extends object = T>(
type: TypeConstructor,
options?: Partial<ServiceOptions & { provides: ObjectType[] }>,
): void
Type Parameters
- T extends object
- I extends object = T
Parameters
- type: TypeConstructor
- Optionaloptions: Partial<ServiceOptions & { provides: ObjectType[] }>
Returns void
- Defined in packages/core/src/di/container.ts:608

create

create(options?: { isolated?: boolean }): Container
Create a new container that inherits all configuration form the parent but on top of that can register or overwrite dependencies; by default dependency resolution is first attempted using the providers, factories and registered service instance in the new container; if that fails it resolution is delegated to the parent until the root container which will throw an exception in case it cannot resolve the requested module.
Parameters
- Optionaloptions: { isolated?: boolean }
Returns Container
- Defined in packages/core/src/di/container.ts:191

`Private`createInstance

createInstance<T extends TypeConstructor<any> | DecoratedTypeConstructor<any>>(
ctor: T,
args?: any[],
): InstanceType<T>
Creates a new instance of the specified type resolving dependencies using the current container context. The returned class is not registered in the container as dependency.
Type Parameters
- T extends TypeConstructor<any> | DecoratedTypeConstructor<any>
Parameters
- ctor: T
 Constructor type/prototype class definition
- args: any[] = []
Returns InstanceType<T>
- Defined in packages/core/src/di/container.ts:336

decorateType

decorateType<T extends object>(
ctor: TypeConstructor<T>,
serviceTypes?: ObjectType<object>[],
): DecoratedTypeConstructor<T>
Decorates a class type with additional metadata for dependency injection.
Type Parameters
- T extends object
Parameters
- ctor: TypeConstructor<T>
 Constructor type to decorate
- serviceTypes: ObjectType<object>[] = []
Returns DecoratedTypeConstructor<T>
Decorated constructor type
- Defined in packages/core/src/di/container.ts:360

`Private`decorateWithServiceGuid

decorateWithServiceGuid<T>(instance: T, guid?: string): T
Type Parameters
- T
Parameters
- instance: T
- Optionalguid: string
Returns T
- Defined in packages/core/src/di/container.ts:519

dispose

dispose(): void
Dispose all services; factories and provides in this container.

Returns void
- Defined in packages/core/src/di/container.ts:198

`Private`generateServiceGuid

generateServiceGuid(ctor: any): string
Parameters
- ctor: any
Returns string
- Defined in packages/core/src/di/container.ts:515

get

get<T extends object>(service: ObjectType<T>): T
Safe version of Container.resolve that never returns undefined and throws an Error for services that cannot be resolved.
Type Parameters
- T extends object
Parameters
- service: ObjectType<T>
 Service type for which to resolve the concrete class
Returns T
- Defined in packages/core/src/di/container.ts:295

getInjectablePropertyDescriptor

getInjectablePropertyDescriptor(
    propertyKey: string | symbol,
): {
    "[InjectedPropertyKey]": string | symbol;
    configurable: boolean;
    enumerable: boolean;
    get(): any;
    set(): never;
}
Internal function to get the property descriptor for an injectable property; used by the inject decorator.
Parameters
- propertyKey: string | symbol
  Key of the property to get the descriptor for
Returns {
    "[InjectedPropertyKey]": string | symbol;
    configurable: boolean;
    enumerable: boolean;
    get(): any;
    set(): never;
}
Defined property descriptor
- Defined in packages/core/src/di/container.ts:455

`Private`getInjectType

getInjectType(
 key: string | symbol,
 target: TypeConstructor,
 property?: string | symbol,
): undefined | TypeConstructor<any>
Parameters
- key: string | symbol
- target: TypeConstructor
- Optionalproperty: string | symbol
Returns undefined | TypeConstructor<any>
- Defined in packages/core/src/di/container.ts:503

`Private`getMetadata

getMetadata(
    key: string | symbol,
    target: TypeConstructor,
    property?: string | symbol,
): any
Parameters
- key: string | symbol
- target: TypeConstructor
- Optionalproperty: string | symbol
Returns any
- Defined in packages/core/src/di/container.ts:511

`Private`getPrototypes

getPrototypes(
instance: object | TypeConstructor<any>,
): Generator<any, void, unknown>
Parameters
- instance: object | TypeConstructor<any>
Returns Generator<any, void, unknown>
- Defined in packages/core/src/di/container.ts:642

`Private`getServicesFromInstance

getServicesFromInstance(instance: object): ObjectType<object>[]
Parameters
- instance: object
Returns ObjectType<object>[]
- Defined in packages/core/src/di/container.ts:628

`Private`getServicesFromType

getServicesFromType(type: TypeConstructor): ObjectType<object>[]
Parameters
- type: TypeConstructor
Returns ObjectType<object>[]
- Defined in packages/core/src/di/container.ts:632

`Private`getTypeName

getTypeName(service: unknown): string
Parameters
- service: unknown
Returns string
- Defined in packages/core/src/di/container.ts:744

new

new<T extends TypeConstructor<any>>(
ctor: T,
...params: PartialArray<ConstructorParameters<T>>,
): InstanceType<T>
Create a new instance of a type resolving constructor parameters as dependencies using the container. The returned class is not added in the container even when the lifecycle policy is singleton.
Type Parameters
- T extends TypeConstructor<any>
Parameters
- ctor: T
 Constructor/Type to instantiate
- ...params: PartialArray<ConstructorParameters<T>>
 Constructor params provided
Returns InstanceType<T>
New instance of an object who's dependencies are resolved by the container
- Defined in packages/core/src/di/container.ts:310

newDeferred

newDeferred<T extends TypeConstructor<any>>(
ctor: T,
...params: PartialArray<ConstructorParameters<T>>,
): InstanceType<T>
Create a new instance of the given type, with construction wrapped in a deferred initializer.

The type and any provided partial constructor arguments are forwarded to the container's createInstance method. The actual construction is wrapped with lazy(...) so the creation logic is executed by the lazy initializer; this method invokes that initializer and returns the created instance.
Type Parameters
- T extends TypeConstructor<any>
 The constructor type to instantiate.
Parameters
- ctor: T
 The constructor (class or function) to instantiate.
- ...params: PartialArray<ConstructorParameters<T>>
 A partial array of constructor arguments that will be forwarded to createInstance.
Returns InstanceType<T>
The constructed instance of the specified constructor type.
- Defined in packages/core/src/di/container.ts:327

registerFactory

registerFactory<T extends object, I extends object = T>(
 services: ObjectType<T> | ObjectType<T>[],
 factory: TypeFactory,
 lifecycle?: LifecyclePolicy,
): void
Register a factory that can provide an instance of the specified factory
Type Parameters
- T extends object
- I extends object = T
Parameters
- services: ObjectType<T> | ObjectType<T>[]
 list of services to register
- factory: TypeFactory
 factory that produces the an instance
- lifecycle: LifecyclePolicy = LifecyclePolicy.transient
Returns void
- Defined in packages/core/src/di/container.ts:707

registerProvider

registerProvider<T extends object, I extends object = T>(
service: ObjectType<T>,
provider: (receiver: any) => undefined | I | Promise,
): void
Type Parameters
- T extends object
- I extends object = T
Parameters
- service: ObjectType<T>
- provider: (receiver: any) => undefined | I | Promise
Returns void
- Defined in packages/core/src/di/container.ts:739

registerProxyService

registerProxyService<T extends object>(
type: { name: string; prototype: T },
): ProxyTarget<T>
Register a service proxy that can be manually set with a concrete instance later on. Any instance that request a service of type T will receive the proxy instance.

The proxy is not registered as a factory type.

The proxy instance can be set using the setInstance method on the ProxyTarget returned by this method.
Type Parameters
- T extends object
Parameters
- type: { name: string; prototype: T }
 Service type to register
Returns ProxyTarget<T>
ProxyTarget instance that can be used to set the concrete instance
- Defined in packages/core/src/di/container.ts:725

removeInstance

removeInstance(instance: unknown): void
Drops an active singleton service instance from the container causing subsequent resolutions to create a new instances instead of reusing the existing one.
Parameters
- instance: unknown
  the instance to remove
Returns void
- Defined in packages/core/src/di/container.ts:656

resolve

resolve<T extends object>(
 type: ObjectType<T> | LazyObjectType<T>,
 receiver?: new (...args: any[]) => object,
 resolver?: Container,
): undefined | T
Resolve requested type to a concrete implementation.
Type Parameters
- T extends object
Parameters
- type: ObjectType<T> | LazyObjectType<T>
 Service type for which to resolve a concrete class
- Optionalreceiver: new (...args: any[]) => object
 Class ctor for which we are resolving this
- resolver: Container = ...
Returns undefined | T
- Defined in packages/core/src/di/container.ts:219

resolveParameters

resolveParameters<T extends new (...args: any[]) => any>(
 ctor: T,
 args?: any[],
 instanceGuid?: string,
): any[]
Resolve injectable parameters for a service using this container.
Type Parameters
- T extends new (...args: any[]) => any
Parameters
- ctor: T
 Constructor function
- args: any[] = []
 arguments
- OptionalinstanceGuid: string
 instance guid
Returns any[]
- Defined in packages/core/src/di/container.ts:394

resolveProperties

resolveProperties<T extends object>(instance: T): T
Resolve injectable properties for a service using this container.
Type Parameters
- T extends object
Parameters
- instance: T
 Instance object
Returns T
instance
- Defined in packages/core/src/di/container.ts:436

resolveProperty

resolveProperty(
    instance: object,
    property: string | symbol,
    options?: { trackAsDependency?: boolean },
): any
Resolve a single property on an instance
Parameters
- instance: object
  The instance containing the property
- property: string | symbol
  The name of the property to resolve
- Optionaloptions: { trackAsDependency?: boolean }
Returns any
The resolved property value
- Defined in packages/core/src/di/container.ts:479

`Private`trackServiceDependencies

trackServiceDependencies(serviceGuid: string, dependsOn: object): void
Register a new dependency between two services
Parameters
- serviceGuid: string
  the instance guid of the object that owns the dependency
- dependsOn: object
  instance of the dependency
Returns void
- Defined in packages/core/src/di/container.ts:531

use

use(instance: object, types?: ObjectType<object> | ObjectType<object>[]): void
Use the specified instance to provided the specified service types. If an existing service is already registered for a type, it will be replaced with the new instance.
Parameters
- instance: object
 the service instance
- Optionaltypes: ObjectType<object> | ObjectType<object>[]
 the service types to provide
Returns void
- Defined in packages/core/src/di/container.ts:570

`Static`get

get(instance: object): undefined | Container
Get's the container that owns or created the specified instance.
Parameters
- instance: object
Returns undefined | Container
- Defined in packages/core/src/di/container.ts:383

Class Container

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns Container

Properties

Private ReadonlycontainerGuid

Private ReadonlycontainerPath

Private Readonlyfactories

Private Readonlyinstances

Private Readonlylogger

Private Optional Readonlyparent

Private Readonlyproviders

Private ReadonlyresolveStack

Private ReadonlyserviceDependencies

Private ReadonlyservicesProvided

Private ReadonlyserviceTypes

useInstanceProxies

Static Readonlyroot

Accessors

isRoot

Returns boolean

Staticscope

Returns Container

Methods

add

Type Parameters

Parameters

Returns void

PrivateaddInstance

Type Parameters

Parameters

Returns void

PrivateaddType

Type Parameters

Parameters

Returns void

create

Parameters

Returns Container

PrivatecreateInstance

Type Parameters

Parameters

Returns InstanceType<T>

decorateType

Type Parameters

Parameters

Returns DecoratedTypeConstructor<T>

PrivatedecorateWithServiceGuid

Type Parameters

Parameters

Returns T

dispose

Returns void

PrivategenerateServiceGuid

Parameters

Returns string

get

Type Parameters

Parameters

Returns T

getInjectablePropertyDescriptor

Parameters

Returns { "[InjectedPropertyKey]": string | symbol; configurable: boolean; enumerable: boolean; get(): any; set(): never;}

PrivategetInjectType

Parameters

Returns undefined | TypeConstructor<any>

PrivategetMetadata

Parameters

Returns any

PrivategetPrototypes

Parameters

Returns Generator<any, void, unknown>

PrivategetServicesFromInstance

Parameters

`Private` `Readonly`containerGuid

`Private` `Readonly`containerPath

`Private` `Readonly`factories

`Private` `Readonly`instances

`Private` `Readonly`logger

`Private` `Optional` `Readonly`parent

`Private` `Readonly`providers

`Private` `Readonly`resolveStack

`Private` `Readonly`serviceDependencies

`Private` `Readonly`servicesProvided

`Private` `Readonly`serviceTypes

`Static` `Readonly`root

`Static`scope

`Private`addInstance

`Private`addType

`Private`createInstance

`Private`decorateWithServiceGuid

`Private`generateServiceGuid

Returns {
"[InjectedPropertyKey]": string | symbol;
configurable: boolean;
enumerable: boolean;
get(): any;
set(): never;
}

`Private`getInjectType

`Private`getMetadata

`Private`getPrototypes

`Private`getServicesFromInstance

`Private`getServicesFromType

`Private`getTypeName

`Private`trackServiceDependencies

`Static`get