yaioc: Yet Another IOC-Container for Node.js

Goals

• Small
• Unobtrusive, invisible to managed components
• Easy to use
• Pluggable/embeddable by design
• No meta-data or scripting required
• Inspired by PicoContainer

Installation

yaioc is available via npm: npm install yaioc

Usage

// Write components
function Foo() {
}

function Bar(foo, value) {
  this.foo = foo;
  this.value = value;
}


// Assemble in container
var container = yaioc.container();
container.register(Foo);
container.register(Bar);
container.register("value", "static value");


// Instantiate components
var bar = container.get("bar");

assert(bar instanceof Bar);
assert(bar.foo instanceof Foo);
assert(bar.value === "static value");

Of course, you can use more modern constructs like classes and ESModules too.

Naming Conventions

var FooBar = ...; // this refers to a Class/Constructor function named "FooBar"
var fooBar = ...; // this refers to an instance of FooBar
function SomeConstructor(fooBar) { ... } // an instance of FooBar will be passed in

Factories

Components can also be registered as Factories, a function which provides the result of a component lookup:

var container = yaioc.container();
container.register("value", "static value");
container.registerFactory("foo", function (value) {
    return { value: value };
});


var foo = container.get("foo");

assert(foo.value === "static value");

Adaptors

Adaptors work similar to Factories, but are very low level. This is the most basic Interface, an adaptor will have to resolve all dependencies for itself. This is useful if you have to do additional work, or a conditional lookup:

var container = yaioc.container();
container.register("evenValue", "even value");
container.register("oddValue", "odd value");
container.registerAdaptor("foo", function (container) {
    var value = container.get(Date.now() % 2 ? "oddValue" : "evenValue");
    return { value: value };
});


var foo = container.get("foo");

assert(foo.value === "even value" || foo.value === "odd value");

There is also an object-oriented interface for adaptors. This is handy for extracting a more advanced calculation or lookup to a separate class.

function FooAdaptor() {
}

FooAdaptor.prototype.getComponentInstance = function (container) {
    var result;
    // work
    return new Foo(result);
};


var container = yaioc.container();
container.registerAdaptor("foo", new FooAdaptor());


var foo = container.get("foo");

assert(foo instanceof Foo);

Additionally an adaptor will get passed the name of its target component:

var container = yaioc.container();
container.register(function NeedsFoo(foo) {});
container.registerAdaptor("foo", function (container, target) {
    assert(target === "NeedsFoo");
});

var foo = container.get("foo");

Caching

If you want to have a single instance of a component, use caching:

container.cache().registerFactory("foo", function factory() {
    return {};
});

var fooOne = container.get("foo");
var fooTwo = container.get("foo");

assert(fooOne === fooTwo);

This works with factories and constructors:

container.cache().register(Foo);

var fooOne = container.get("foo");
var fooTwo = container.get("foo");

assert(fooOne === fooTwo);

Component Scan

A convenient way to register many components is the component scan facility. Internally this uses the glob module, so many wildcard expressions are allowed. All matched files will be required and registered.

var container = yaioc.container();
var MyController = require("./ctrls/MyController");

container.scanComponents(__dirname + "/**/*Controller.js");

assert(container.get("MyController") === MyController);
assert(container.get("myController") instanceof MyController);

Container hierarchies

A container can get access to components registered in wrapped containers, but not vice-versa. If you want to wrap multiple containers, pass in an array of containers

var wrappedContainer = yaioc.container();
var container = yaioc.container(wrappedContainer);

var foo = {}, bar = {};
wrappedContainer.register("foo", foo);
container.register("bar", bar);

assert(container.get("foo") === foo);
assert(wrappedContainer.get("bar") === undefined);

Dependency Graph

There is a method to give you an overview of all dependencies and transient dependencies of any given component:

function Foo(baz) {}
function Bar(foo, value) {}
function BarDependent(bar) {}

var container = yaioc.container();
container.register(Foo);
container.register(Bar);
container.register(BarDependent);
container.register("baz", "");
container.register("value", "static value");

var graph = container.getDependencyGraph("bar");
console.log(graph.draw());

This will print a tree of dependencies:

bar
├┬ foo
│└─ baz
└─ value

Additionally, there will be an error if either a dependency is not found, or a circular reference is detected.

Dependency Schema

In order to get an overall picture about the regitstered components and their dependecies in the container, you can use the method getDependencySchema:

function Foo(baz) {}
function Bar(foo, value) {}
function BarDependent(bar) {}

var container = yaioc.container();
container.register(Foo);
container.register(Bar);
container.register(BarDependent);
container.register("baz", "");
container.register("value", "static value");

var schema = container.getDependencySchema();
console.log(schema.getDependencyDotFile());

That outputs content of a Dot File.

digraph yaiocDeps {
  foo -> baz;
  bar -> foo;
  bar -> value;
  barDependent -> bar;
}

You can use any cli or online tool to generate the visual output.