A tiny inversion of control container for JavaScript.

Using didi you follow the dependency injection / inversion of control pattern, decoupling component declaration from instantiation. Once declared, didi instantiates components as needed, transitively resolves their dependencies, and caches instances for re-use.

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 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 components
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 or diagram-js, two libraries that heavily use dependency injection at their core. You can also check out the tests to learn about all supported use cases.

Learn how to declare, inject and initialize your components.

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

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

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

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

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

Register a static value:

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

The injector looks up dependencies based on explicit annotations, comments, or function 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'
}

You can use comments to encode names:

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

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' ];

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

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

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 : {}}]
};

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

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

import { Injector } from 'didi';

import coreModule from './core';
import HttpBackend from './test/mocks';

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

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

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

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>

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.

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

MIT