Enumeration: BindingScope

Scope for binding values

Members
Name Default Value Flags Description
CONTEXT "Context" exported

The binding provides a value as a singleton within each local context. The value is calculated only once per context and cached for subsequenicial uses. Child contexts have their own value and do not share with their ancestors.

For example, with the following context hierarchy:

  • app (with a binding 'b1' that produces sequential values 0, 1, ...)
    • req1
    • req2

// 0 is the singleton for app afterward app.get('b1') ==> 0

// 'b1' is found in app but not in req1, a new value 1 is calculated. // 1 is the singleton for req1 afterward req1.get('b1') ==> 1

// 'b1' is found in app but not in req2, a new value 2 is calculated. // 2 is the singleton for req2 afterward req2.get('b1') ==> 2
SINGLETON "Singleton" exported

The binding provides a value as a singleton within the context hierarchy (the owning context and its descendants). The value is calculated only once for the owning context and cached for subsequenicial uses. Child contexts share the same value as their ancestors.

For example, with the following context hierarchy:

  • app (with a binding 'b1' that produces sequential values 0, 1, ...)
    • req1
    • req2

// 0 is the singleton for app afterward app.get('b1') ==> 0

// 'b1' is found in app, reuse it req1.get('b1') ==> 0

// 'b1' is found in app, reuse it req2.get('b1') ==> 0
TRANSIENT "Transient" exported

The binding provides a value that is calculated each time. This will be the default scope if not set.

For example, with the following context hierarchy:

  • app (with a binding 'b1' that produces sequential values 0, 1, ...)
    • req1
    • req2

// get('b1') produces a new value each time for app and its descendants app.get('b1') ==> 0 req1.get('b1') ==> 1 req2.get('b1') ==> 2 req2.get('b1') ==> 3 app.get('b1') ==> 4

Enumeration: BindingType

Type of the binding source

Members
Name Default Value Flags Description
CLASS "Class" exported

A class to be instantiated as the value
CONSTANT "Constant" exported

A fixed value
DYNAMIC_VALUE "DynamicValue" exported

A function to get the value
PROVIDER "Provider" exported

A provider class with value() function to get the value

Class: binding = new Binding()

Binding represents an entry in the Context. Each binding has a key and a corresponding value getter.

Properties
Name Type Default Value Flags Description
isLocked boolean constructorProperty exported public

Binding represents an entry in the Context. Each binding has a key and a corresponding value getter.
key string exported public

Key of the binding
scope BindingScope BindingScope.TRANSIENT exported public

Scope of the binding to control how the value is cached/shared
tagMap TagMap exported public

Map for tag name/value pairs
type BindingType exported public

Type of the binding value getter
valueConstructor Constructor<T> exported public

For bindings bound via toClass, this property contains the constructor function

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

Parameters
Name Type Default Value Flags Description
key string

Binding represents an entry in the Context. Each binding has a key and a corresponding value getter.
isLocked boolean false

Binding represents an entry in the Context. Each binding has a key and a corresponding value getter.

tagNames() : string[]

Get an array of tag names

getValue(ctx: Context, session: ResolutionSession) : ValueOrPromise<T>

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);
}

Parameters
Name Type Default Value Flags Description
ctx Context

Context for the resolution
session ResolutionSession optional

Optional session for binding and dependency resolution

inScope(scope: BindingScope) : this

Parameters
Name Type Default Value Flags Description
scope BindingScope

Binding represents an entry in the Context. Each binding has a key and a corresponding value getter.

lock() : this

tag(tags: (string | anonymous)[]) : this

Tag the binding with names or name/value objects. A tag has a name and an optional value. If not supplied, the tag name is used as the value.

Parameters
Name Type Default Value Flags Description
tags (string | anonymous)[] rest

A list of names or name/value objects. Each parameter can be in one of the following forms:

  • string: A tag name without value
  • string[]: An array of tag names
  • TagMap: A map of tag name/value pairs

to(value: T) : 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.

Parameters
Name Type Default Value Flags Description
value T

The bound value.

toClass(ctor: Constructor<T>) : this

Bind the key to an instance of the given class.

Parameters
Name Type Default Value Flags Description
ctor Constructor<T>

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<T>) : this

Bind the key to a computed (dynamic) value.

Parameters
Name Type Default Value Flags Description
factoryFn anonymous

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

toJSON() : Object

toProvider(providerClass: Constructor<Provider<T>>) : 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);
  }
}

Parameters
Name Type Default Value Flags Description
providerClass Constructor<Provider<T>>

Binding represents an entry in the Context. Each binding has a key and a corresponding value getter.

unlock() : this

Type alias: TagMap = MapObject

Class: bindingkey = new BindingKey()

Properties
Name Type Default Value Flags Description
PROPERTY_SEPARATOR "#" static exported

deepProperty(propertyPath: string) : BindingKey<PropertyValueType>

Get a binding address for retrieving a deep property of the object bound to the current binding key.

Parameters
Name Type Default Value Flags Description
propertyPath string

A dot-separated path to a (deep) property, e.g. "server.port".

toString() : string

create(key: string, propertyPath: undefined | string) : BindingKey<ValueType>

Create a new key for a binding bound to a value of type ValueType.

Example

BindingKey.create<string>('application.name');
BindingKey.create<number>('config', 'rest.port);
BindingKey.create<number>('config#rest.port');

Parameters
Name Type Default Value Flags Description
key string

The binding key. When propertyPath is not provided, the key is allowed to contain propertyPath as encoded via BindingKey#toString()
propertyPath undefined | string optional

Optional path to a deep property of the bound value.

parseKeyWithPath(keyWithPath: BindingAddress<T>) : BindingKey<T>

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

Parameters
Name Type Default Value Flags Description
keyWithPath BindingAddress<T>

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

validate(key: BindingAddress<T>) : string

Validate the binding key format. Please note that # is reserved. Returns a string representation of the binding key.

Parameters
Name Type Default Value Flags Description
key BindingAddress<T>

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

Class: context = new Context()

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

Properties
Name Type Default Value Flags Description
name string exported

Name of the context

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

Create a new context

Parameters
Name Type Default Value Flags Description
_parent Context | string optional

The optional parent context
name undefined | string optional

Create a new context

bind(key: BindingAddress<ValueType>) : Binding<ValueType>

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.

Parameters
Name Type Default Value Flags Description
key BindingAddress<ValueType>

Binding key

contains(key: BindingAddress<ValueType>) : boolean

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

Parameters
Name Type Default Value Flags Description
key BindingAddress<ValueType>

Binding key

find(pattern: string | RegExp) : Readonly<Binding<ValueType>>[]

Find bindings using the key pattern

Parameters
Name Type Default Value Flags Description
pattern string | RegExp optional

A regexp or wildcard pattern with optional * and ?. If it matches the binding key, the binding is included. For a wildcard:

  • * matches zero or more characters except . and :
  • ? matches exactly one character except . and :

find(filter: (binding: Readonly<Binding<ValueType>>) => boolean) : Readonly<Binding<ValueType>>[]

Find bindings using a filter function

Parameters
Name Type Default Value Flags Description
filter anonymous

A function to test on the binding. It returns `true` to include the binding or `false` to exclude the binding.

findByTag(tagFilter: string | RegExp | TagMap) : Readonly<Binding<ValueType>>[]

Find bindings using the tag filter. If the filter matches one of the binding tags, the binding is included.

Parameters
Name Type Default Value Flags Description
tagFilter string | RegExp | TagMap

A filter for tags. It can be in one of the following forms:

  • A regular expression, such as /controller/
  • A wildcard pattern string with optional and ?, such as 'con' For a wildcard:
    • * matches zero or more characters except . and :
    • ? matches exactly one character except . and :
  • An object containing tag name/value pairs, such as {name: 'my-controller'}

get(keyWithPath: BindingAddress<ValueType>) : Promise<ValueType>

Get the value bound to the given key, throw an error when no value was bound for the given key.

Returns:

A promise of the bound value.

Parameters
Name Type Default Value Flags Description
keyWithPath BindingAddress<ValueType>

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

get(keyWithPath: BindingAddress<ValueType>, optionsOrSession: ResolutionOptions | ResolutionSession) : Promise<ValueType | undefined>

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

Returns:

A promise of the bound value, or a promise of undefined when the optional binding was not found.

Parameters
Name Type Default Value Flags Description
keyWithPath BindingAddress<ValueType>

The binding key, optionally suffixed with a path to the (deeply) nested property to retrieve.
optionsOrSession ResolutionOptions | ResolutionSession optional

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

getBinding(key: BindingAddress<ValueType>) : Binding<ValueType>

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

Parameters
Name Type Default Value Flags Description
key BindingAddress<ValueType>

Binding key

getBinding(key: BindingAddress<ValueType>, options: undefined | anonymous) : Binding<ValueType> | undefined

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

Parameters
Name Type Default Value Flags Description
key BindingAddress<ValueType>

Binding key
options undefined | anonymous optional

Options to control if the binding is optional. If `options.optional` is set to true, the method will return `undefined` instead of throwing an error if the binding key is not found.

getOwnerContext(key: BindingAddress<ValueType>) : Context | undefined

Get the owning context for a binding key

Parameters
Name Type Default Value Flags Description
key BindingAddress<ValueType>

Binding key

getSync(keyWithPath: BindingAddress<ValueType>) : ValueType

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.

Parameters
Name Type Default Value Flags Description
keyWithPath BindingAddress<ValueType>

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.

getSync(keyWithPath: BindingAddress<ValueType>, optionsOrSession: ResolutionOptions | ResolutionSession) : ValueType | undefined

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:

The bound value, or undefined when an optional binding was not found.

Parameters
Name Type Default Value Flags Description
keyWithPath BindingAddress<ValueType>

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 ResolutionOptions | ResolutionSession optional

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

getValueOrPromise(keyWithPath: BindingAddress<ValueType>, optionsOrSession: ResolutionOptions | ResolutionSession) : ValueOrPromise<ValueType | undefined>

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.

Parameters
Name Type Default Value Flags Description
keyWithPath BindingAddress<ValueType>

The binding key, optionally suffixed with a path to the (deeply) nested property to retrieve.
optionsOrSession ResolutionOptions | ResolutionSession optional

Options for resolution or a session

isBound(key: BindingAddress<ValueType>) : boolean

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

Parameters
Name Type Default Value Flags Description
key BindingAddress<ValueType>

Binding key

toJSON() : Object

Create a plain JSON object for the context

unbind(key: BindingAddress<ValueType>) : 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

Parameters
Name Type Default Value Flags Description
key BindingAddress<ValueType>

Binding key

Namespace: inject

Function: inject.context

inject.context() : markParameterOrPropertyAsInjected

Inject the context object.

Function: inject.getter

inject.getter(bindingKey: BindingAddress<BoundValue>, metadata: InjectionMetadata) : markParameterOrPropertyAsInjected

Inject a function for getting the actual bound value.

This is useful when implementing Actions, where the action is instantiated for Sequence constructor, but some of action's dependencies become bound only after other actions have been executed by the sequence.

See also Getter<T>.

Parameters
Name Type Default Value Flags Description
bindingKey BindingAddress<BoundValue>

The key of the value we want to eventually get.
metadata InjectionMetadata optional

Optional metadata to help the injection

Function: inject.setter

inject.setter(bindingKey: BindingAddress<BoundValue>, metadata: InjectionMetadata) : markParameterOrPropertyAsInjected

Inject a function for setting (binding) the given key to a given value. (Only static/constant values are supported, it's not possible to bind a key to a class or a provider.)

This is useful e.g. when implementing Actions that are contributing new Elements.

See also Setter<T>.

Parameters
Name Type Default Value Flags Description
bindingKey BindingAddress<BoundValue>

The key of the value we want to set.
metadata InjectionMetadata optional

Optional metadata to help the injection

Function: inject.tag

inject.tag(bindingTag: string | RegExp, metadata: InjectionMetadata) : markParameterOrPropertyAsInjected

Inject an array of values by a tag pattern string or regexp

Parameters
Name Type Default Value Flags Description
bindingTag string | RegExp

Tag name or regex
metadata InjectionMetadata optional

Optional metadata to help the injection

Interface: Injection

Descriptor for an injection point

Properties
Name Type Default Value Flags Description
bindingKey BindingAddress<ValueType> exported

Descriptor for an injection point
member string | symbol exported optional

Descriptor for an injection point
metadata InjectionMetadata exported optional

Descriptor for an injection point
methodDescriptorOrParameterIndex TypedPropertyDescriptor<ValueType> | number exported optional

Descriptor for an injection point
resolve ResolverFunction exported optional

Descriptor for an injection point
target Object exported

Descriptor for an injection point

Interface: InjectionMetadata

An object to provide metadata for @inject

Properties
Name Type Default Value Flags Description
decorator undefined | string exported optional

Name of the decorator function, such as @inject or @inject.setter</a>. It's usually set by the decorator implementation.
optional undefined | true | false exported optional

Control if the dependency is optional, default to false

Interface: ResolverFunction

A function to provide resolution of injected values

Type alias: Getter(): Promise<T>

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

Type alias: Setter(value: T): void

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

Arguments
Name Type Description
value T

Function: describeInjectedArguments

describeInjectedArguments(target: Object, method: string | symbol) : Readonly<Injection>[]

Return an array of injection objects for parameters

Parameters
Name Type Default Value Flags Description
target Object

The target class for constructor or static methods, or the prototype for instance methods
method string | symbol optional

Method name, undefined for constructor

Function: describeInjectedProperties

describeInjectedProperties(target: Object) : MetadataMap<Readonly<Injection>>

Return a map of injection objects for properties

Parameters
Name Type Default Value Flags 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<T>

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 Default Value Flags Description
stack ResolutionElement[] [] exported

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

bindingStack() : Readonly<Binding>[]

Getter for bindings on the stack

currentBinding() : Readonly<Binding> | undefined

Getter for the current binding

currentInjection() : Readonly<Injection> | undefined

Getter for the current injection

injectionStack() : Readonly<Injection>[]

Getter for injections on the stack

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() : Readonly<Binding>

Exit the resolution of a binding

popInjection() : anonymous

Pop the last injection

pushBinding(binding: Readonly<Binding>) : void

Enter the resolution of the given binding. If

Parameters
Name Type Default Value Flags Description
binding Readonly<Binding>

Binding

pushInjection(injection: Readonly<Injection>) : void

Push the injection onto the session

Parameters
Name Type Default Value Flags Description
injection Readonly<Injection>

Injection The current injection

describeInjection(injection: Readonly<Injection>) : undefined | anonymous

Describe the injection for debugging purpose

Parameters
Name Type Default Value Flags Description
injection Readonly<Injection> optional

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

Parameters
Name Type Default Value Flags Description
session ResolutionSession optional

The current session

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

Run the given action with the given binding and session

Parameters
Name Type Default Value Flags Description
action ResolutionAction

A function to do some work with the resolution session
binding Readonly<Binding>

The current binding
session ResolutionSession optional

The current resolution session

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

Run the given action with the given injection and session

Parameters
Name Type Default Value Flags Description
action ResolutionAction

A function to do some work with the resolution session
injection Readonly<Injection>

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

The current resolution session

Interface: BindingElement

Wrapper for bindings tracked by resolution sessions

Properties
Name Type Default Value Flags Description
type exported

Wrapper for bindings tracked by resolution sessions
value Readonly<Binding> exported

Wrapper for bindings tracked by resolution sessions

Interface: InjectionElement

Wrapper for injections tracked by resolution sessions

Properties
Name Type Default Value Flags Description
type exported

Wrapper for injections tracked by resolution sessions
value Readonly<Injection> exported

Wrapper for injections tracked by resolution sessions

Interface: ResolutionOptions

Options for binding/dependency resolution

Properties
Name Type Default Value Flags Description
optional undefined | true | false exported 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 exported optional

A session to track bindings and injections

Type alias: ResolutionAction(session: ResolutionSession): ValueOrPromise

A function to be executed with the resolution session

Arguments
Name Type Description
session ResolutionSession

Function: instantiateClass

instantiateClass(ctor: Constructor<T>, ctx: Context, session: ResolutionSession, nonInjectedArgs: any[]) : ValueOrPromise<T>

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.

Parameters
Name Type Default Value Flags Description
ctor Constructor<T>

The class constructor to call.
ctx Context

The context containing values for @inject resolution
session ResolutionSession optional

Optional session for binding and dependency resolution
nonInjectedArgs any[] optional

Optional array of args for non-injected parameters

Function: invokeMethod

invokeMethod(target: Object, method: string, ctx: Context, nonInjectedArgs: any[]) : ValueOrPromise<BoundValue>

Invoke an instance method with dependency injection

Parameters
Name Type Default Value Flags 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 any[] optional

Optional array of args for non-injected parameters

Function: resolveInjectedArguments

resolveInjectedArguments(target: Object, method: string, ctx: Context, session: ResolutionSession, nonInjectedArgs: any[]) : ValueOrPromise<BoundValue[]>

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.

Parameters
Name Type Default Value Flags 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

Optional session for binding and dependency resolution
nonInjectedArgs any[] optional

Optional array of args for non-injected parameters

Function: resolveInjectedProperties

resolveInjectedProperties(constructor: Function, ctx: Context, session: ResolutionSession) : ValueOrPromise<MapObject<BoundValue>>

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.

Parameters
Name Type Default Value Flags Description
constructor Function

The class for which properties should be resolved.
ctx Context

The context containing values for @inject resolution
session ResolutionSession optional

Optional session for binding and dependency resolution