Class: binding = new Binding()

Properties
Name Type Description
isLocked boolean
key string
scope BindingScope
tags Set
type BindingType
valueConstructor Constructor
PROPERTY_SEPARATOR string

constructor(key: string, isLocked: boolean) : Binding

Arguments
Name Type Description
key string
isLocked boolean

getValue(ctx: Context, session: ResolutionSession) : ValueOrPromise

This is an internal function optimized for performance. Users should use @inject(key) or ctx.get(key) instead.

Get the value bound to this key. Depending on isSync, this function returns either:

  • the bound value
  • a promise of the bound value

Consumers wishing to consume sync values directly should use isPromise to check the type of the returned value to decide how to handle it.

const result = binding.getValue(ctx);
if (isPromise(result)) {
  result.then(doSomething)
} else {
  doSomething(result);
}

Arguments
Name Type Description
ctx Context

Context for the resolution

session ResolutionSession

Optional session for binding and dependency resolution

inScope(scope: BindingScope) : this

Arguments
Name Type Description
scope BindingScope

lock() : this

tag(tagName: undefined) : this

Arguments
Name Type Description
tagName

to(value: BoundValue) : this

Bind the key to a constant value. The value must be already available at binding time, it is not allowed to pass a Promise instance.

Arguments
Name Type Description
value BoundValue

The bound value.

toClass(ctor: Constructor) : this

Bind the key to an instance of the given class.

Arguments
Name Type Description
ctor Constructor

The class constructor to call. Any constructor arguments must be annotated with @inject so that we can resolve them from the context.

toDynamicValue(factoryFn: () => ValueOrPromise) : this

Bind the key to a computed (dynamic) value.

Arguments
Name Type Description
factoryFn Function

The factory function creating the value. Both sync and async functions are supported.

toJSON() : Object

toProvider(providerClass: Constructor) : this

Bind the key to a value computed by a Provider.

  • @example

export class DateProvider implements Provider<Date> {
  constructor(@inject('stringDate') private param: String){}
  value(): Date {
    return new Date(param);
  }
}

Arguments
Name Type Description
providerClass Constructor

unlock() : this

buildKeyWithPath(key: string, path: string) : string

Build a binding key from a key and a path

Arguments
Name Type Description
key string

The key

path string

The path

parseKeyWithPath(keyWithPath: string) : undefined | undefined

Parse a string containing both the binding key and the path to the deeply nested property to retrieve.

Arguments
Name Type Description
keyWithPath string

The key with an optional path, e.g. "application.instance" or "config#rest.port".

validateKey(key: string) : string

Validate the binding key format. Please note that # is reserved.

Arguments
Name Type Description
key string

Binding key, such as `a, a.b, a:b, a/b

Class: context = new Context()

Context provides an implementation of Inversion of Control (IoC) container

Properties
Name Type Description
name string

Name of the context

constructor(_parent: undefined, name: undefined) : Context

Create a new context

Arguments
Name Type Description
_parent

The optional parent context

name

Create a new context

bind(key: string) : Binding

Create a binding with the given key in the context. If a locked binding already exists with the same key, an error will be thrown.

Arguments
Name Type Description
key string

Binding key

contains(key: string) : boolean

Check if a binding exists with the given key in the local context without delegating to the parent context

Arguments
Name Type Description
key string

Binding key

find(pattern: undefined) :

Find bindings using the key pattern

Arguments
Name Type Description
pattern

Key regexp or pattern with optional * wildcards

findByTag(pattern: undefined) :

Find bindings using the tag pattern

Arguments
Name Type Description
pattern

Tag name regexp or pattern with optional * wildcards

get(keyWithPath: string, optionsOrSession: undefined) : Promise

Get the value bound to the given key, optionally return a (deep) property of the bound value.

Returns:

A promise of the bound value.

Arguments
Name Type Description
keyWithPath string

The binding key, optionally suffixed with a path to the (deeply) nested property to retrieve.

optionsOrSession

Options or session for resolution. An instance of ResolutionSession is accepted for backward compatibility.

getBinding(key: string) : Binding

Look up a binding by key in the context and its ancestors. If no matching binding is found, an error will be thrown.

Arguments
Name Type Description
key string

Binding key

getOwnerContext(key: string) : Context | undefined

Get the owning context for a binding key

Arguments
Name Type Description
key string

Binding key

getSync(keyWithPath: string, optionsOrSession: undefined) : BoundValue

Get the synchronous value bound to the given key, optionally return a (deep) property of the bound value.

This method throws an error if the bound value requires async computation (returns a promise). You should never rely on sync bindings in production code.

Returns:

A promise of the bound value.

Arguments
Name Type Description
keyWithPath string

The binding key, optionally suffixed with a path to the (deeply) nested property to retrieve.

  • @param optionsOrSession Options or session for resolution. An instance of ResolutionSession is accepted for backward compatibility.

optionsOrSession

Context provides an implementation of Inversion of Control (IoC) container

getValueOrPromise(keyWithPath: string, optionsOrSession: undefined) : ValueOrPromise

Get the value bound to the given key.

This is an internal version that preserves the dual sync/async result of Binding#getValue(). Users should use get() or getSync() instead.

Returns:

The bound value or a promise of the bound value, depending on how the binding was configured.

Arguments
Name Type Description
keyWithPath string

The binding key, optionally suffixed with a path to the (deeply) nested property to retrieve.

optionsOrSession

Options for resolution or a session

isBound(key: string) : boolean

Check if a key is bound in the context or its ancestors

Arguments
Name Type Description
key string

Binding key

toJSON() : Object

Create a plain JSON object for the context

unbind(key: string) : boolean

Unbind a binding from the context. No parent contexts will be checked. If you need to unbind a binding owned by a parent context, use the code below:

const ownerCtx = ctx.getOwnerContext(key);
return ownerCtx != null && ownerCtx.unbind(key);

Returns:

true if the binding key is found and removed from this context

Arguments
Name Type Description
key string

Binding key

Interface: Injection

Descriptor for an injection point

Properties
Name Type Description
bindingKey string

Descriptor for an injection point

member

Descriptor for an injection point

metadata InjectionMetadata

Descriptor for an injection point

methodDescriptorOrParameterIndex

Descriptor for an injection point

resolve ResolverFunction

Descriptor for an injection point

target Object

Descriptor for an injection point

Interface: InjectionMetadata

An object to provide metadata for @inject

Properties
Name Type Description
decorator

Name of the decorator function, such as @inject or @inject.setter. It's usually set by the decorator implementation.

optional

Control if the dependency is optional, default to false

Interface: ResolverFunction

A function to provide resolution of injected values

Getter(): Promise<T>

The function injected by @inject.getter(key).

Setter(value: T): void

The function injected by @inject.setter(key).

Arguments
Name Type Description
value T

describeInjectedArguments(target: Object, method: undefined) :

Return an array of injection objects for parameters

Arguments
Name Type Description
target Object

The target class for constructor or static methods, or the prototype for instance methods

method

Method name, undefined for constructor

describeInjectedProperties(target: Object) : MetadataMap

Return a map of injection objects for properties

Arguments
Name Type Description
target Object

The target class for static properties or prototype for instance properties.

Interface: Provider

Providers allow developers to compute injected values dynamically, with any dependencies required by the value getter injected automatically from the Context.

value() : ValueOrPromise

Returns:

The value to inject to dependents. This method can return a promise too, in which case the IoC framework will resolve this promise to obtain the value to inject.

Class: resolutionsession = new ResolutionSession()

Object to keep states for a session to resolve bindings and their dependencies within a context

Properties
Name Type Description
stack

A stack of bindings for the current resolution session. It's used to track the path of dependency resolution and detect circular dependencies.

getBindingPath() : string

Get the binding path as bindingA --> bindingB --> bindingC.

getInjectionPath() : string

Get the injection path as injectionA --> injectionB --> injectionC.

getResolutionPath() : string

Get the resolution path including bindings and injections, for example: bindingA --> @ClassA[0] --> bindingB --> @ClassB.prototype.prop1 --> bindingC.

popBinding() : Binding

Exit the resolution of a binding

popInjection() : Injection

Pop the last injection

pushBinding(binding: Binding) : void

Enter the resolution of the given binding. If

Arguments
Name Type Description
binding Binding

Binding

pushInjection(injection: Injection) : void

Push the injection onto the session

Arguments
Name Type Description
injection Injection

Injection The current injection

describeInjection(injection: Injection) : undefined | undefined

Describe the injection for debugging purpose

Arguments
Name Type Description
injection Injection

Injection object

fork(session: ResolutionSession) : ResolutionSession | undefined

Fork the current session so that a new one with the same stack can be used in parallel or future resolutions, such as multiple method arguments, multiple properties, or a getter function

Arguments
Name Type Description
session ResolutionSession

The current session

runWithBinding(action: ResolutionAction, binding: Binding, session: ResolutionSession) : any

Run the given action with the given binding and session

Arguments
Name Type Description
action ResolutionAction

A function to do some work with the resolution session

binding Binding

The current binding

session ResolutionSession

The current resolution session

runWithInjection(action: ResolutionAction, injection: Injection, session: ResolutionSession) : any

Run the given action with the given injection and session

Arguments
Name Type Description
action ResolutionAction

A function to do some work with the resolution session

injection Injection

Object to keep states for a session to resolve bindings and their dependencies within a context

session ResolutionSession

The current resolution session

Interface: BindingElement

Wrapper for bindings tracked by resolution sessions

Properties
Name Type Description
type

Wrapper for bindings tracked by resolution sessions

value Binding

Wrapper for bindings tracked by resolution sessions

Interface: InjectionElement

Wrapper for injections tracked by resolution sessions

Properties
Name Type Description
type

Wrapper for injections tracked by resolution sessions

value Injection

Wrapper for injections tracked by resolution sessions

Interface: ResolutionOptions

Options for binding/dependency resolution

Properties
Name Type Description
optional

A boolean flag to indicate if the dependency is optional. If it's set to true and the binding is not bound in a context, the resolution will return undefined instead of throwing an error.

session ResolutionSession

A session to track bindings and injections

ResolutionAction(session: ResolutionSession): ValueOrPromise

A function to be executed with the resolution session

Arguments
Name Type Description
session ResolutionSession

instantiateClass(ctor: Constructor, ctx: Context, session: ResolutionSession, nonInjectedArgs: undefined) : ValueOrPromise

Create an instance of a class which constructor has arguments decorated with @inject.

The function returns a class when all dependencies were resolved synchronously, or a Promise otherwise.

Arguments
Name Type Description
ctor Constructor

The class constructor to call.

ctx Context

The context containing values for @inject resolution

session ResolutionSession

Optional session for binding and dependency resolution

nonInjectedArgs

Optional array of args for non-injected parameters

invokeMethod(target: Object, method: string, ctx: Context, nonInjectedArgs: undefined) : ValueOrPromise

Invoke an instance method with dependency injection

Arguments
Name Type Description
target Object

Target of the method, it will be the class for a static method, and instance or class prototype for a prototype method

method string

Name of the method

ctx Context

Context

nonInjectedArgs

Optional array of args for non-injected parameters

resolveInjectedArguments(target: Object, method: string, ctx: Context, session: ResolutionSession, nonInjectedArgs: undefined) : ValueOrPromise

Given a function with arguments decorated with @inject, return the list of arguments resolved using the values bound in ctx.

The function returns an argument array when all dependencies were resolved synchronously, or a Promise otherwise.

Arguments
Name Type Description
target Object

The class for constructor injection or prototype for method injection

method string

The method name. If set to '', the constructor will be used.

ctx Context

The context containing values for @inject resolution

session ResolutionSession

Optional session for binding and dependency resolution

nonInjectedArgs

Optional array of args for non-injected parameters

resolveInjectedProperties(constructor: Function, ctx: Context, session: ResolutionSession) : ValueOrPromise

Given a class with properties decorated with @inject, return the map of properties resolved using the values bound in ctx.

The function returns an argument array when all dependencies were resolved synchronously, or a Promise otherwise.

Arguments
Name Type Description
constructor Function

The class for which properties should be resolved.

ctx Context

The context containing values for @inject resolution

session ResolutionSession

Optional session for binding and dependency resolution