Javascript Dependency Injection library

DI-XXL is a dependency injection library facilitating lazy initialization and loose coupling. It is generic, because it can inject everything into anything in multiple ways. Together with support for namespaces, decorators, factory functions, projections and lazy initialization it is a powerful tool ready for complex situations.

In its most basic form a registration of an entity like a class, object or function is done like this

import {DI} from 'di-xxl';

class Foo {}

const descriptor = {
    name: 'foo',
    ref: Foo
};

DI.set(descriptor)

Foo gets registered here and will be accessible now by the name foo. The descriptor object needs at least a name and a reference. Use get to retrieve an instance of Foo

const foo = DI.get('foo'); // const foo = new Foo();

NOTE (Because I've made this mistake many times:) Don't use DI inside the constructor!!!!

class Bar {
     @Inject('foo') foo;

     constructor() {
         this.foo.do(); // --> Error, this.foo is undefined
     }
}

Dependencies are injected after the Bar instances is created (Below you can find more about @decorators)

Parameters

The example above showed the creation of an instance without parameters, so here is an exmaple where the instance is created using params

const descriptor = {
    name 'foo', 
    ref: Foo,
    params: [10, 20]
}
DI.set(descriptor);

These params will be used when none are given when the instance of Foo is requested

DI.get('foo'); // -> new Foo(10, 20)

But when provided, the default parameters are ignored

DI.get<Foo>('foo', {params: [999]}); // -> Returns new Foo(999)

In the above example, DI.get is typed, telling it what the returned value is, to make consuming the output easier and more obvious.

Injection

In theory you can inject anything into almost everything :) Circular dependencies do not exist, because it is not possible to inject into a constructor. Keep your constructors empty or as small as possible!

So, to inject Foo into Bar

class Bar {}
    
const descriptor = {
    name: 'bar',
    ref: Bar,
    inject: [{property: 'foo', name: 'foo'}]
};
DI.set(descriptor);
    

This will assign an instance of Foo to the foo property of Bar on first usage. Lazy initialization is used here, meaning that Foo will be created when it is used for the first time. To disable this feature set the lazy option to false

 const descriptor = {
    name: 'bar',
    ref: Bar,
    inject: [{property: 'foo', name: 'foo', lazy: false}]
};

ACTIONS

Anything can be registered, like classes, objects, but also normal functions (not constructors). If a function is not a constructor you need to instruct DI-XXL what it should do, return the function or call it first and return the output

const descriptor = {
    name: 'double',
    ref: num => num * 2,
    action: DI.ACTIONS.NONE
};

DI.set(descriptor);

const double = DI.get('double');
double(10); // -> 20

or

const descriptor = {
    name: 'double',
    ref: base => num => base + num * 2,
    action: DI.ACTIONS.INVOKE
}

In the last example DI-XXL will invoke the reference using the provided parameters and return the output

const double = DI.get('double', {params: [10]});
double(2); // -> 14

Singletons

To turn a class into a singleton, add the singleton flag to the descriptor

const descriptor = {
    name: 'foo',
    ref: Foo,
    singleton: true
}

This will also work with Objects. By default (if not specified) on object is a singleton

const descriptor = {
    name: 'app',
    ref: {}
}
DI.set(descriptor);

let app = DI.get('app')
app.count = 1
app = DI.get('app');
console.log(app.count); // -> 1

But if you set that flag to false, DI-XXL returns a new object, internally using Object.create

const descriptor = {
    name: 'app',
    ref: {},
    singleton: false
}
DI.set(descriptor);

let app = DI.get('app')
app.count = 1
app = DI.get('app');
console.log(app.count); // -> undefined

Inherit

In case you have almost identical descriptors for two different entities, one can inherit the other

descriptor = {
    name: 'Bar',
    ref: Bar,
    inherit: 'foo'
}

Factories

When a class produce instances of an other class

 class Bar {
     getFoo(input) {
         return new Foo(input);
     }
 }
 

it can be rewritten with DI-XXL using Factories

class Bar {
    getInstance() {
        return this.creator();
    }        
}
 
descriptor = {
    name: 'bar',
    ref: Bar,
    inject: [{property: 'creator', factory: 'foo'}] // Each entity has a factory!
}

The factory function, which produces instances of Foo, is injected into the creator property of bar

const bar = DI.get('bar');
const foo = bar.creator({params: [1,2]}); // new Foo(1,2)

Everything registered in DI-XXL has by default a factory. For example

class Bar { /* ... */ }
DI.set({name: 'xyz', ref: Bar});
const factory = DI.getFactory('xyz', { params: [1,2]});
let bar = factory()            // -> new Bar(1,2)
bar = factory({params: [3,4]}) // -> new Bar(3,4)

Projections

Projections let you map an entity name to an other

DI.setProjection({'foo': 'bar'}); // Is the same: 

const something = DI.get('foo'); 

results in something instanceof Bar. Projections can be used, for example, to change the behaviour of you application dynamically, based on user action.

Namespaces

Namespaces help to structure your entities in a descriptive way. A namespace is a prefix of the entity name

user.overview.profile

with user.overview being the namespace. Try to keep your entity names unique within the whole namespace. For example

user.profile
user.overview.profile

profile is not unique!! As long as you know what your are doing this isn't a problem. The reason behind this is how namespaces are implemented, for example

class User { ... }

DI.set({ 
    name: 'user.overview.profile', 
    ref: User,
    inject: [
        {property: 'list', name: 'user.widgets.list'},
        {property: 'source', name: 'user.data.source'}]});
    
DI.get('user.overview.profile');

The list and source entities, although exactly specified, will be searched for within the namespace from the root up. It means that DI-XXL will look for list using the following entity names

list               --> no
user.list          --> no
user.widgets.list  --> yes

This allows you to redefine entities without replacing the original

DI.set({ name: 'user.list', ....});

This time the search for list looks like

list       --> no
user.list  --> yes

It will not find user.widgets.list. This is the default lookup direction (DI.DIRECTIONS.PARENT_TO_CHILD), but you can reverse the lookup

DI.get('user.overview.profile', {lookup: DI.DIRECTIONS.CHILD_TO_PARENT});

So far we have only talked about the entities from the inject list, but this search pattern is also applied on the entity request, with one exception, the first attempt is always the exact name provided

// DI.DIRECTIONS.CHILD_TO_PARENT
   user.overview.profile
   user.profile
   profile
   
// DI.DIRECTIONS.PARENT_TO_CHIDL
   user.overview.profile
   profile
   user.profile

Roles

Each entity can have a role and a reject and accept list of roles

 const descriptor = {
    name: 'service.user',
    ...
    role: 'service'
    accept: ['service'],
    reject: ['component']
 }

If you specify accept all injected entities need to have a role present in the list. But if you define reject everything can be injected except for the roles defined in the reject list.

@Decorators

As of this writing you have to use a couple of babel plugins to get @decorators up and running, or if you're using typescript make sure to set the experimentalDecorators option to true in tsconfig.json. With Decorators you can define all dependency related configuration inside the class itself

import {Injectable, Inject} from 'di-xxl';

@Injectable({name: 'foo'})
class Foo {
    sum(a, b) { return a + b }
}

@Injectable({name: 'Bar'})
class Bar {
    @Inject('foo')
    addService
    
    constructor(base = 0) {
        this.total = base;
    }
     
    add(val) {
        return this.addService(this.base, val);
    }
}

Which is equivalent to

import {ID} from 'di-xxl';

DI.set({
    name: 'foo',
    ref: Foo
});

DI.set({
    name: 'bar',
    ref: Bar,
    inject: [{property: 'addService', name: 'foo'}]
});

The @Inject also accepts an object instead of just the name/string

@Inject({ name: 'foo', lazy: false }) addService;

Please note that this might not work out of the box when you're using Typescript. Read about di executable to the rescue below to work around this issue!

The @Injectable statements are directly executed, meaning that they are immediately available

import {ID} from 'di-xxl';

let bar = DI.get('bar', {params: [100]});
bar.add(1); // -> 101

Checkout the unit tests fixtures file for more advanced use cases

Inject into a constructor

Ok, if you really really really have to do this you can of course do it ... yourself :)

const params = [DI.get('foo'), 10];
const bar = DI.get('bar', {params});

di executable to the rescue

Unfortunately you cannot use the @decorators in combination with Typescript out of the box. Typescript ignores files which are not used directly, for example

file: foo.ts

@Injectable({name: 'foo'})
class Foo {
    sum(a, b) { return a + b }
}

file index.ts

import { DI } from 'di-xxl';

const foo = DI.get('foo'); // -> foo === undefined

Now, when Typescript compiles index.ts it has no notion of Foo, so it ignores that file, meaning the @Injectable is never executed. This can be fixed by using Foo inside index.ts

import { DI } from 'di-xxl';
import { Foo } from './foo';
Foo;

const foo = DI.get('foo'); // -> foo === Foo instance

This is exactly what ./node_modules/.bin/di does

  $> di ./src/index.ts

What this does, it creates a file called ./src/index-id.ts with all the files using @Injectable injected

import { DI } from 'di-xxl';
import { Foo } from './foo';Foo;

const foo = DI.get('foo'); // -> foo === Foo instance

But it will also behave like ts-node, because after it has created index-id.ts it will run

ts-node ./src/index-di.ts

But if only compiling is what you need and not running the code with ts-node you can

$> di -c tsc ./src/index.ts

And if you need, for example, to specifiy a custom configfile for tsc do

$> di -c tsc ./src/index.ts -- -p my-special-tsconfig.json

Everything after the -- will be used as arguments for the command you specifiy with -c. Below is a listing of options to further tune the behavior of this tool:

Options:
  --help         Show help                                                                                               [boolean]
  --version      Show version number                                                                                     [boolean]
  --command, -c  After injecting dependencies, it runs the command. Default argument is is `ts-node`
  --base, -b     Base path to the root of the source files                                                                [string]
  --debug, -d    Enable debug messages                                                                                    [boolean]
  --entry, -e    Entry filename                                                                                           [string]
  --include, -i  List of paths/files to include                                                                           [string]
  --pattern, -p  Glob patterns specifying filenames with wildcard characters, defaults to **/*.ts                         [string]
  --output, -o   Output file relative to `base. Defaults to `<entryfile>`-di.ts`                                          [string]

Examples:
  $> di ./src/main.ts                                   -- Run main.ts using ts-node
  $> di -c ./src/main.ts                                -- This runs the code using `ts-node`
  $> di -b ./src -e index.ts -p '**/*.ts' -o out.ts     -- Run the code 
  $> di -b ./src index.ts -- --thread 10                -- Run `ts-node ./src/index-di.ts --thread 10` 
  $> di -c -b ./src -e index.ts -p '**/*.ts' -o out.ts  -- Compiles all code with `tsc`
  $> di -c 'yarn build' -b ./src -e index.ts -o out.ts  -- Injects and runs `yarn build`
  $> di -c yarn -b ./src -e index.ts -o out.ts -- build  -- Same as above

Here is a more complex example

  $> di -d -c tsc -b ./src -i 'frontend,shared' -e 'Foo,Bar' frontend/main.ts -- -p tsconfig-frontend.json

It might be useful to add the file created by di to your .gitignore file!

More information

A lot more advanced use-cases are available inside the unit test files.

Installation

Install this library with yarn or npm

$> yarn add di-xxl

or

$> npm install di-xxl

Commands

Convert DI--XXL into an UMD and ES5 library + a minified version in ./dist

$> yarn build

Unit testing

$> yarn test

Linting

$> yarn lint

Generate documentation (jsdoc)

$> yarn doc

Run benchmarks on different aspects of DI-XXL

$> yarn bench 

Run in the browser

There are a couple of ways to run this library in the browser. If you're project doesn't support import or require use browserify. For es2015 use babelify

$> ./node_modules/.bin/browserify index.js -o bundle.js -t [ babelify --presets [ env ] ]

and for es5 you only need to do

$> ./node_modules/.bin/browserify index.js -o bundle.js

DEMO