myrlund / dipper

An simple and unobrusive DI library for Node.js.

Dipper.js

An lightweight promise-driven dependency injection library for Node.js. Heavily inspired by, and mostly compatible with, Cloud9's Architect.

Usage

A dipper-driven application is comprised of packages, each providing and consuming services.

Putting together an application consists of three simple steps:

1. Application configuration. Divide logical modules into packages, each living in a separate directory, and list them in an application config file.
2. Package configuration. Specify the services imported and exported from each package in tiny package config files. An entry point for each package is invoked with its imports, and a callback.
3. Bootstrap the application. Give dipper.createApplication your application config.

In a bit more detail...

1. Application configuration

Packages are passed to dipper.createApplication, or set up in a JSON or Javascript configuration file – by default ./config.json – in the following manner:

{
  "packages": [
    "./some-package",
    {"path": "./another-package", "someParameter": "itsValue"}
  ]
}

The location of the config file can be set using the configFile option. The config can also be passed directly with the config option.

2. Package configuration

Each package requires a package.json in its root directory:

{
  "name": "Service 1", // optional (defaults to last part of package path)
  "main": "entry.js",  // the package's entry point (defaults to: name || 'index')
  "consumes": ["service2"], // package imports. must be provided by another package.
  "provides": ["service1"]  // package exports. can be consumed by other packages.
}

The package setup function

The entry point of each package must export a setup function, through which it is injected options, its dependencies, and a callback for registering its own provided services:

// A package entry point.
module.exports = function (options, imports, register) {
    var someServer = require('./someServer').setup(imports.service2);
    
    register(null, {
        service1: someServer
    });
};

Note that the register callback has a node-style error parameter as its first argument. Pass a falsy value to indicate success.

3. Bootstrap the application

Bring it all together. Finally, in your main application module:

var dipper = require('dipper');

dipper.createApplication(yourConfig).then(function (app) {
    app.services.service1.start();
})
.done();

API

@TODO.

dipper's Issues

Implement tear-down routines for packages

Collect tear-down functions from package exports to run when application halts.

Add examples of how to test dipper applications

Describe the complete API