didi

A tiny inversion of control container for JavaScript.

About

Using didi, you follow the dependency injection / inversion of control pattern. This means that you decouple component (service) declaration from instantiation.

Components in didi are declared by name. Each component is a singleton. didi takes care of instantiating components and their dependencies as needed, caching them for future re-use.

Example

import { Injector } from 'didi';

function Car(engine) {
  this.start = function() {
    engine.start();
  };
}

function createPetrolEngine(power) {
  return {
    start: function() {
      console.log('Starting engine with ' + power + 'hp');
    }
  };
}

// define a (didi) module - it declares available
// components by name and specifies how these are provided
const carModule = {

  // asked for 'car', the injector will call new Car(...) to produce it
  'car': [ 'type', Car ],

  // asked for 'engine', the injector will call createPetrolEngine(...) to produce it
  'engine': [ 'factory', createPetrolEngine ],

  // asked for 'power', the injector will give it the number 1184
  'power': [ 'value', 1184 ] // probably Bugatti Veyron
};

// instantiate an injector with a set of (didi) modules
const injector = new Injector([
  carModule
]);

// use the injector API to retrieve a component
injector.get('car').start();

// alternatively invoke a function, injecting the arguments
injector.invoke(function(car) {
  console.log('started', car);
});

// if you work with a TypeScript code base, retrieve
// a typed instance of a component
const car: Car = injector.get<Car>('car');

car.start();

For real-world examples, check out Karma, diagram-js, or Wuffle—libraries that heavily use dependency injection at their core. You can also check out the tests to learn about all supported use cases.

Usage

Learn how to define modules that declare, inject and initialize your components.

Defining modules

You declare your components by name as part of a didi module:

const engineModule = {
  'engine': [ 'type', DieselEngine ]
};

const carModule = {
  'car': [ 'factory', function createCar(engine) { ... } ]
};

You pass a set of modules to instantiate the didi container:

import { Injector } from 'didi';

const injector = new Injector([
  engineModule,
  carModule
]);

A module can depend on other modules through the __depends__ tag. As a result, didi will load it transitively, too:

const mainModule = {
  __depends__: [ carModule, engineModule ]
};

const injector = new Injector([ mainModule ]);

Upon instantiation, the Injector resolves modules in definition order, collecting named components and their dependencies. For the purpose of testing or customization a module loaded later can re-declare a named component.

Declaring components

By declaring a component as part of a didi module, you make it available to other components.

type(token, Constructor)

Constructor will be called with the new operator to produce the instance:

const module = {
  'engine': [ 'type', DieselEngine ]
};

factory(token, factoryFn)

The injector produces the instance by calling factoryFn without any context. It uses the factory's return value:

const module = {
  'engine': [ 'factory', createDieselEngine ]
};

value(token, value)

Register a static value:

const module = {
  'power': [ 'value', 1184 ]
};

Injecting components

The injector looks up dependencies based on explicit annotations, comments, or function argument names.

Argument names

If no further details are provided, the injector parses dependency names from function arguments:

function Car(engine, license) {
  // will inject components bound to 'engine' and 'license'
}

Function comments

You can use comments to encode names:

function Car(/* engine */ e, /* x._weird */ x) {
  // will inject components bound to 'engine' and 'x._weird'
}

$inject annotation

You can use a static $inject annotation to declare dependencies in a minification-safe manner:

function Car(e, license) {
  // will inject components bound to 'engine' and 'license'
}

Car.$inject = [ 'engine', 'license' ];

Array notation

You can also use the minification save array notation known from AngularJS:

const Car = [ 'engine', 'trunk', function(e, t) {
  // will inject components bound to 'engine' and 'trunk'
}];

Partial injection

Sometimes it is helpful to inject only a specific property of some object:

function Engine(/* config.engine.power */ power) {
  // will inject 1184 (config.engine.power),
  // assuming there is no direct binding for 'config.engine.power' token
}

const engineModule = {
  'config': [ 'value', { engine: { power: 1184 }, other : {} } ]
};

Component instantiation

In didi components are singletons, instantiated lazily, as needed, and cached for later re-use:

// instantiates the <car> on first access
const car = injector.get('car');

injector.invoke(function(car) {
  // re-uses <car> as instantiated earlier
});

You may define module init hooks to mark components that should be eagerly loaded.

Important

didi only supports synchronous component instantiation. If you look for async instantiation, give async-didi a try.

Initializing components

Modules can use an __init__ hook to declare components that shall eagerly load or functions to be invoked, i.e., trigger side-effects during initialization:

import { Injector } from 'didi';

function HifiComponent(events) {
  events.on('toggleHifi', this.toggle.bind(this));

  this.toggle = function(mode) {
    console.log(`Toggled Hifi ${mode ? 'ON' : 'OFF'}`);
  };
}

const injector = new Injector([
  {
    __init__: [ 'hifiComponent' ],
    hifiComponent: [ 'type', HifiComponent ]
  },
  ...
]);

// initializes all modules as defined
injector.init();

Overriding components

You can override components by name. That can be beneficial for testing, but also for customizing:

import { Injector } from 'didi';

import coreModule from './core.js';
import { HttpBackend } from './test/mocks.js';

const injector = new Injector([
  coreModule,
  {
    // overrides already declared `httpBackend`
    httpBackend: [ 'type', HttpBackend ]
  }
]);

Type-safety

didi ships type declarations that allow you to use it in a type-safe manner.

Explicit typing

Pass a type attribute to Injector#get to retrieve a service as a known type:

const hifiComponent = injector.get<HifiComponent>('hifiComponent');

// typed as <HifiComponent>
hifiComponent.toggle();

Implicit typing

Configure the Injector through a service map and automatically cast services to known types:

type ServiceMap = {
  'hifiComponent': HifiComponent
};

const injector = new Injector<ServiceMap>(...);

const hifiComponent = injector.get('hifiComponent');
// typed as <HifiComponent>

Credits

This library builds on top of the (now unmaintained) node-di library. didi is a maintained fork that adds support for ES6, the minification safe array notation, and other features.

Differences to node-di

• supports array notation
• supports ES2015
• bundles type definitions
• module initialization + module dependencies

License

MIT