Container

The InversifyJS container is where dependencies are first configured through binding and, possibly later, reconfigured and removed. The container can be worked on directly in this regard or container modules can be utilized. You can query the configuration and resolve configured dependencies with the get methods. You can react to resolutions with container activation handlers and unbinding with container deactivation handlers. You can create container hierarchies where container ascendants can supply the dependencies for descendants. For testing, state can be saved as a snapshot on a stack and later restored.

Container Options

Container options can be passed to the Container constructor, and defaults will be provided if you do not or if you do but omit an option. Options can be changed after construction and will be shared by child containers created from the Container if you do not provide options for them.

autoBind

autoBind?: true;

Option to automatically bind unbound class services to themselves. Whenever an instance is resolve, the container attempts to add a binding if no binding is found for the requested service.

parent

parent?: Container | undefined;

The parent container, if any. Refer to the container hierarchy docs for more information.

defaultScope

defaultScope?: BindingScope | undefined;

The default scope for bindings.

bind

bind<T>(serviceIdentifier: ServiceIdentifier<T>): BindingToSyntax<T>

Sets a new binding.

get

get<T>(serviceIdentifier: ServiceIdentifier<T>, options: OptionalGetOptions): T | undefined;
get<T>(serviceIdentifier: ServiceIdentifier<T>, options?: GetOptions): T;

Resolves a dependency by its runtime identifier. The runtime identifier must be associated with only one binding and the binding must be synchronously resolved, otherwise an error is thrown.

const container: Container = new Container();
container.bind<Weapon>('Weapon').to(Katana);

const katana: Weapon = container.get<Weapon>('Weapon');

getAsync

getAsync<T>(serviceIdentifier: ServiceIdentifier<T>, options: OptionalGetOptions): Promise<T | undefined>;
getAsync<T>(serviceIdentifier: ServiceIdentifier<T>, options?: GetOptions): Promise<T>;

Resolves a dependency by its runtime identifier. The runtime identifier must be associated with only one binding, otherwise an error is thrown.

async function buildLevel1(): Promise<Level1> {
  return new Level1();
}

const container: Container = new Container();
container
  .bind('Level1')
  .toDynamicValue(async (): Promise<Level1> => buildLevel1());

const level1: Promise<Level1> = container.getAsync<Level1>('Level1');

getAll

getAll<T>(serviceIdentifier: ServiceIdentifier<T>, options?: GetAllOptions): T[];

Get all available bindings for a given identifier. All the bindings must be synchronously resolved, otherwise an error is thrown:

const container: Container = new Container();
container.bind<Weapon>('Weapon').to(Katana);
container.bind<Weapon>('Weapon').to(Shuriken);

const weapons: Weapon[] = container.getAll<Weapon>('Weapon');

getAllAsync

getAllAsync<T>(serviceIdentifier: ServiceIdentifier<T>, options?: GetAllOptions): Promise<T[]>

Get all available bindings for a given identifier:

const container: Container = new Container();
container.bind<Weapon>('Weapon').toDynamicValue(async () => new Katana());
container.bind<Weapon>('Weapon').to(Shuriken);

const weapons: Promise<Weapon[]> = container.getAllAsync<Weapon>('Weapon');

isBound

isBound(serviceIdentifier: ServiceIdentifier<unknown>, options?: IsBoundOptions): boolean;

You can use the isBound method to check if there are registered bindings for a given service identifier.

interface Warrior {
  kind: string;
}

const katanaSymbol: symbol = Symbol.for('Katana');
const warriorSymbol: symbol = Symbol.for('Warrior');

@injectable()
class Ninja implements Warrior {
  public readonly kind: string = 'ninja';
}

@injectable()
class Katana {}

const container: Container = new Container();
container.bind<Warrior>(Ninja).to(Ninja);
container.bind<Warrior>(warriorSymbol).to(Ninja);

// returns true
const isNinjaBound: boolean = container.isBound(Ninja);
// returns true
const isWarriorSymbolBound: boolean = container.isBound(warriorSymbol);
// returns false
const isKatanaBound: boolean = container.isBound(Katana);
// returns false
const isKatanaSymbolBound: boolean = container.isBound(katanaSymbol);

isCurrentBound

isCurrentBound(serviceIdentifier: ServiceIdentifier<unknown>, options?: IsBoundOptions): boolean;

You can use the isCurrentBound method to check if there are registered bindings for a given service identifier only in the current container.

interface Warrior {
  kind: string;
}

const katanaSymbol: symbol = Symbol.for('Katana');
const warriorSymbol: symbol = Symbol.for('Warrior');

@injectable()
class Ninja implements Warrior {
  public readonly kind: string = 'ninja';
}

@injectable()
class Katana {}

const container: Container = new Container();
container.bind<Warrior>(Ninja).to(Ninja);
container.bind<Warrior>(warriorSymbol).to(Ninja);

const containerChild: Container = new Container({ parent: container });

containerChild.bind<Katana>(Katana).to(Katana);
containerChild.bind<Katana>(katanaSymbol).to(Katana);

// returns false
const isNinjaBound: boolean = containerChild.isCurrentBound(Ninja);
// returns false
const isWarriorSymbolBound: boolean =
  containerChild.isCurrentBound(warriorSymbol);
// returns true
const isKatanaBound: boolean = containerChild.isCurrentBound(Katana);
// returns true
const isKatanaSymbolBound: boolean =
  containerChild.isCurrentBound(katanaSymbol);

load

load(...modules: ContainerModule[]): Promise<void>;

Calls the registration method of each module. See ContainerModule API docs.

onActivation

onActivation<T>(serviceIdentifier: ServiceIdentifier<T>, onActivation: BindingActivation<T>): void;

Adds an activation handler for all services associated to the service identifier.

interface Weapon {
  damage: number;
}

export class Katana implements Weapon {
  #damage: number = 10;

  public get damage(): number {
    return this.#damage;
  }

  public improve(): void {
    this.#damage += 2;
  }
}

const container: Container = new Container();
container.bind<Weapon>('Weapon').to(Katana);
container.onActivation(
  'Weapon',
  (_context: ResolutionContext, katana: Katana): Katana | Promise<Katana> => {
    katana.improve();

    return katana;
  },
);

// Katana.damage is 12
const katana: Weapon = container.get<Weapon>('Weapon');

onDeactivation

onDeactivation<T>(serviceIdentifier: ServiceIdentifier<T>, onDeactivation: BindingDeactivation<T>): void;

Adds a deactivation handler for a service identifier.

interface Weapon {
  damage: number;
}

class Katana implements Weapon {
  readonly #damage: number = 10;

  public get damage(): number {
    return this.#damage;
  }
}

const container: Container = new Container();

container.bind<Weapon>('Weapon').to(Katana).inSingletonScope();

container.get('Weapon');

container.onDeactivation('Weapon', (weapon: Weapon): void | Promise<void> => {
  console.log(`Deactivating weapon with damage ${weapon.damage.toString()}`);
});

await container.unbind('Weapon');

restore

restore(): void;

Restore container state to last snapshot. Refer to the docs for more information.

snapshot

snapshot(): void;

Save the state of the container to be later restored with the restore method. Refer to the docs for more information.

unbind

unbind(serviceIdentifier: ServiceIdentifier): Promise<void>;

Remove all bindings binded in this container to the service identifier. This will result in the deactivation process.

unbindAll

unbindAll(): Promise<void>;

Remove all bindings binded in this container. This will result in the deactivation process.

unload

unload(...modules: ContainerModule[]): Promise<void>;

Removes bindings and handlers added by the modules. This will result in the deactivation process. See ContainerModule API docs.

GetOptions

Options that can be passed to the get, getAll, getAsync, and getAllAsync methods.

interface GetOptions {
  autobind?: boolean;
  name?: MetadataName;
  optional?: boolean;
  tag?: GetOptionsTagConstraint;
}

• autobind (boolean): Option to automatically bind unbound class services to themselves.
• name (MetadataName): The name metadata to match bindings.
• optional (boolean): If true, the method will return undefined or empty array if no binding is found.
• tag (GetOptionsTagConstraint): The tag metadata to match bindings.

OptionalGetOptions

Options that can be passed to the get and getAsync methods when the result is optional.

interface OptionalGetOptions extends GetOptions {
  optional: true;
}

• optional (true): Indicates that the result is optional and the method will return undefined if no binding is found.