March 10, 2016

A powerful IoC container for JavaScript apps powered by TypeScript

I released InversifyJS 1.0 about a year ago. Back then it had some nice features like transient and singleton scope but it was far from what I wanted to achieve.

InversifyJS is an open-source inversion of control (IoC) container for TypeScript applications.

InversifyJS 2.0 (v2.0.0-alpha.3) is finally here and I’m really excited to be able to show you what it is capable of.

InversifyJS 2.0 is lightweight library because one of my main goals is to add a little run-time overhead as possible. The latest build is only 4 KB (gzip) and it has no dependencies.

Another nice thing is that InversifyJS can be used in both web browsers and Node.js. However, in some environments some features may require some ES6 shims (e.g. Providers requires Promises and Proxy requires ES6 Proxies).

Note: This version is a pre-release and is not ready for production use. Some of these APIs are not final and are subject to change.

Basic injection #

Let’s take a look to the basic usage and APIs of InversifyJS:

Step 1: Declare your interfaces #

interface INinja { fight(): string; sneak(): string; } interface IKatana { hit(): string; } interface IShuriken { throw(); }

Step 2: Implement the interfaces and declare dependencies using the @inject decorator #

import { inject } from "inversify"; class Katana implements IKatana { public hit() { return "cut!"; } } class Shuriken implements IShuriken { public throw() { return "hit!"; } } @inject("IKatana", "IShuriken") class Ninja implements INinja { private _katana: IKatana; private _shuriken: IShuriken; public constructor(katana: IKatana, shuriken: IShuriken) { this._katana = katana; this._shuriken = shuriken; } public fight() { return this._katana.hit(); }; public sneak() { return this._shuriken.throw(); }; }

Step 3: Create and configure a Kernel #

We recommend creating a file named inversify.config.ts . This file should be the only place in which there is some coupling in your entire application. In the rest of your application your classes should be free of references to other classes.

import { Kernel } from "inversify"; import { Ninja } from "./entities/ninja"; import { Katana } from "./entities/katana"; import { Shuriken} from "./entities/shuriken"; var kernel = new Kernel(); kernel.bind<INinja>("INinja").to(Ninja); kernel.bind<IKatana>("IKatana").to(Katana); kernel.bind<IShuriken>("IShuriken").to(Shuriken); export default kernel;

Step 4: Resolve dependencies #

You can use the method get<T> from the Kernel class to resolve a dependency.

Note: You should do this only in your composition root to avoid the service locator anti-pattern.

import kernel = from "./inversify.config"; var ninja = kernel.get<INinja>("INinja"); expect(ninja.fight()).eql("cut!"); // true expect(ninja.sneak()).eql("hit!"); // true

As we can see the IKatana and IShuriken were successfully resolved and injected into Ninja .

Declaring kernel modules #

Kernel modules can help you to manage the complexity of your bindings in very large applications.

let someModule: IKernelModule = (kernel: IKernel) => { kernel.bind<INinja>("INinja").to(Ninja); kernel.bind<IKatana>("IKatana").to(Katana); kernel.bind<IShuriken>("IShuriken").to(Shuriken); }; let kernel = new Kernel({ modules: [ someModule ] });

Controlling the scope of the dependencies #

InversifyJS uses transient scope by default but you can also use singleton scope:

kernel.bind<IShuriken>("IShuriken").to(Shuriken).inTransientScope(); kernel.bind<IShuriken>("IShuriken").to(Shuriken).inSingletonScope();

Injecting a value #

We can bind an abstraction to a constant value.

kernel.bind<IKatana>("IKatana").toValue(new Katana());

Injecting a class constructor #

We can bind an abstraction to a class constructor.

@inject("IKatana", "IShuriken") class Ninja implements INinja { private _katana: IKatana; private _shuriken: IShuriken; public constructor(Katana: INewable<IKatana>, shuriken: IShuriken) { this._katana = new Katana(); this._shuriken = shuriken; } public fight() { return this._katana.hit(); }; public sneak() { return this._shuriken.throw(); }; }

kernel.bind<INewable<IKatana>>("INewable<IKatana>").toConstructor<IKatana>(Katana);

Injecting a Factory #

We can bind an abstraction to a user defined Factory.

@inject("IKatana", "IShuriken") class Ninja implements INinja { private _katana: IKatana; private _shuriken: IShuriken; public constructor(katanaFactory: IFactory<IKatana>, shuriken: IShuriken) { this._katana = katanaFactory(); this._shuriken = shuriken; } public fight() { return this._katana.hit(); }; public sneak() { return this._shuriken.throw(); }; }

kernel.bind<IFactory<IKatana>>("IFactory<IKatana>").toFactory<IKatana>((context) => { return () => { return context.kernel.get<IKatana>("IKatana"); }; });

Auto factory #

We can bind an abstraction to an auto-generated Factory.

@inject("IKatana", "IShuriken") class Ninja implements INinja { private _katana: IKatana; private _shuriken: IShuriken; public constructor(katanaFactory: IFactory<IKatana>, shuriken: IShuriken) { this._katana = katanaFactory(); this._shuriken = shuriken; } public fight() { return this._katana.hit(); }; public sneak() { return this._shuriken.throw(); }; }

kernel.bind<IFactory<IKatana>>("IFactory<IKatana>").toAutoFactory<IKatana>();

Injecting a Provider (asynchronous Factory) #

We can bind an abstraction to a Provider. A provider is an asynchronous Factory, this is useful when dealing with asynchronous I/O operations.

@inject("IKatana", "IShuriken") class Ninja implements INinja { public katana: IKatana; public shuriken: IShuriken; public katanaProvider: IProvider<IKatana>; public constructor(katanaProvider: IProvider<IKatana>, shuriken: IShuriken) { this.katanaProvider = katanaProvider; this.katana= null; this.shuriken = shuriken; } public fight() { return this._katana.hit(); }; public sneak() { return this._shuriken.throw(); }; } var ninja = kernel.get<INinja>("INinja"); ninja.katanaProvider() .then((katana) => { ninja.katana = katana; }) .catch((e) => { console.log(e); });

kernel.bind<IProvider<IKatana>>("IProvider<IKatana>").toProvider<IKatana>((context) => { return () => { return new Promise<IKatana>((resolve) => { let katana = context.kernel.get<IKatana>("IKatana"); resolve(katana); }); }; });

Injecting a proxy #

It is possible to create a proxy of a dependency just before it is injected. This is useful to keep our dependencies agnostic of the implementation of crosscutting concerns like caching or logging.

interface IKatana { use: () => void; } class Katana implements IKatana { public use() { console.log("Used Katana!"); } } interface INinja { katana: IKatana; } @inject("IKatana") class Ninja implements INinja { public katana: IKatana; public constructor(katana: IKatana) { this.katana = katana; } }

kernel.bind<INinja>("INinja").to(Ninja); kernel.bind<IKatana>("IKatana").to(Katana).proxy((katana) => { let handler = { apply: function(target, thisArgument, argumentsList) { console.log(`Starting: ${new Date().getTime()}`); let result = target.apply(thisArgument, argumentsList); console.log(`Finished: ${new Date().getTime()}`); return result; } }; katana.use = new Proxy(katana.use, handler); return katana; });

let ninja = kernelget<INinja>(); ninja.katana.use(); > Starting: 1457895135761 > Used Katana! > Finished: 1457895135762

We can use multi-injection When two or more concretions have been bound to the an abstraction. Notice how an array of IWeapon is injected into the Ninja class via its constructor:

interface IWeapon { name: string; } class Katana implements IWeapon { public name = "Katana"; } class Shuriken implements IWeapon { public name = "Shuriken"; } interface INinja { katana: IWeapon; shuriken: IWeapon; } @inject("IWeapon[]") class Ninja implements INinja { public katana: IWeapon; public shuriken: IWeapon; public constructor(weapons: IWeapon[]) { this.katana = weapons[0]; this.shuriken = weapons[1]; } }

We are binding Katana and Shuriken to IWeapon :

kernel.bind<INinja>("INinja").to(Ninja); kernel.bind<IWeapon>("IWeapon").to(Katana); kernel.bind<IWeapon>("IWeapon").to(Shuriken);

Tagged bindings #

We can use tagged bindings to fix AMBIGUOUS_MATCH errors when two or more concretions have been bound to the an abstraction. Notice how the constructor arguments of the Ninja class have been annotated using the @tagged decorator.

Note: an AMBIGUOUS_MATCH error takes place when there are two or more potential concretions for a given abstraction and the IoC container doesn’t have enough information to know which of the concretions should be injected.

interface IWeapon {} class Katana implements IWeapon { } class Shuriken implements IWeapon {} interface INinja { katana: IWeapon; shuriken: IWeapon; } @inject("IWeapon", "IWeapon") class Ninja implements INinja { public katana: IWeapon; public shuriken: IWeapon; public constructor( @tagged("canThrow", false) katana: IWeapon, @tagged("canThrow", true) shuriken: IWeapon ) { this.katana = katana; this.shuriken = shuriken; } }

We are binding Katana and Shuriken to IWeapon but a whenTargetTagged constraint is added to avoid AMBIGUOUS_MATCH errors:

kernel.bind<INinja>("INinja").to(Ninja); kernel.bind<IWeapon>("IWeapon").to(Katana).whenTargetTagged("canThrow", false); kernel.bind<IWeapon>("IWeapon").to(Shuriken).whenTargetTagged("canThrow", true);

Create your own tag decorators #

Creating your own decorators is really simple:

let throwable = tagged("canThrow", true); let notThrowable = tagged("canThrow", false); @inject("IWeapon", "IWeapon") class Ninja implements INinja { public katana: IWeapon; public shuriken: IWeapon; public constructor( @notThrowable katana: IWeapon, @throwable shuriken: IWeapon ) { this.katana = katana; this.shuriken = shuriken; } }

Named bindings #

We can use named bindings to fix AMBIGUOUS_MATCH errors when two or more concretions have been bound to the an abstraction. Notice how the constructor arguments of the Ninja class have been annotated using the @named decorator:

interface IWeapon {} class Katana implements IWeapon { } class Shuriken implements IWeapon {} interface INinja { katana: IWeapon; shuriken: IWeapon; } @inject("IWeapon", "IWeapon") class Ninja implements INinja { public katana: IWeapon; public shuriken: IWeapon; public constructor( @named("strong")katana: IWeapon, @named("weak") shuriken: IWeapon ) { this.katana = katana; this.shuriken = shuriken; } }

We are binding Katana and Shuriken to IWeapon but a whenTargetNamed constraint is added to avoid AMBIGUOUS_MATCH errors:

kernel.bind<INinja>("INinja").to(Ninja); kernel.bind<IWeapon>("IWeapon").to(Katana).whenTargetNamed("strong"); kernel.bind<IWeapon>("IWeapon").to(Shuriken).whenTargetNamed("weak");

Contextual bindings & @paramNames #

The @paramNames decorator is used to access the names of the constructor arguments from a contextual constraint even when the code is compressed. The constructor(katana, shuriken) { ... becomes constructor(a, b) { ... after compression but thanks to @paramNames we can still refer to the design-time names katana and shuriken .

interface IWeapon {} class Katana implements IWeapon { } class Shuriken implements IWeapon {} interface INinja { katana: IWeapon; shuriken: IWeapon; } @inject("IWeapon", "IWeapon") @paramNames("katana","shuriken") class Ninja implements INinja { public katana: IWeapon; public shuriken: IWeapon; public constructor( katana: IWeapon, shuriken: IWeapon ) { this.katana = katana; this.shuriken = shuriken; } }

We are binding Katana and Shuriken to IWeapon but a custom when constraint is added to avoid AMBIGUOUS_MATCH errors:

kernel.bind<INinja>("INinja").to(Ninja); kernel.bind<IWeapon>("IWeapon").to(Katana).when((request: IRequest) => { return request.target.name.equals("katana"); }); kernel.bind<IWeapon>("IWeapon").to(Shuriken).when((request: IRequest) => { return request.target.name.equals("shuriken"); });

The target fields implement the IQueryableString interface to help you to create your custom constraints:

interface IQueryableString { startsWith(searchString: string): boolean; endsWith(searchString: string): boolean; contains(searchString: string): boolean; equals(compareString: string): boolean; value(): string; }

Circular dependencies #

InversifyJS is able to identify circular dependencies and will throw an exception to help you to identify the location of the problem if a circular dependency is detected:

Error: Circular dependency found between services: IKatana and INinja

Live demo #

You can try InversifyJS online at tonicdev.com.

I want to say thanks the contributors. It’s been a long journey but it has been amazing to work on InversifyJS for the last year. I have many plans for its future and I can’t wait to see what you will create with it.

Please try InversifyJS and let us know what do you think. We want to define a road map based on the real needs of the end users and the only way we can do that is if you let us know what you need and what you don’t like.

Remember that you can visit http://inversify.io/ or the GitHub repo to learn more about InversifyJS.

Please feel free to let us know your thoughts about this article with us via @OweR_ReLoaDeD and @WolkSoftwareLtd.

Don’t forget to subscribe if you don’t want to miss it out future articles!

205 Kudos