white-horse

Simple, light-weight dependency injection for NodeJS that supports modules which load asynchronously.

Usage

npm install white-horse

var WhiteHorse = require('white-horse');

var container = new WhiteHorse(require, {
  /* options (optional) */
});

Examples

WhiteHorse(require)
  .register('oneModule', function () {
    return "l";
  })
  .register('anotherModule', function (oneModule, yetAnotherModule) {
    return "He" + oneModule + yetAnotherModule;
  })
  .register('yetAnotherModule', function (oneModule, $done) {
    $done(null, oneModule + "o");
  })
  .inject(function (anotherModule) {
    console.log(anotherModule); // prints "Hello"
  }, function (err) {
    console.error(err);
  });

WhiteHorse(require)
  .use(require('./package.json'))
  .scan('modules', function (main) {
    main.run();
  }, function (error) {
    console.log("Aww snap:", error);
  });

API

register(name, module)

Registers a module with the given name.

The dependencies of that factory function are its named arguments or the dependencies you name explicitly using $dependencies = [ ... ].

A module can be anything:

container.register('pi', Math.pi)
container.get('pi', function (err, module) {
  console.log(module); // 3.141592653589793
});

If it is a function it is taken to be the factory for a singleton.

Note how module does have the same value when retrieving the module twice:

function f() {
  return 7 + Math.random();
}
container.register('seven', f);
container.get('seven', function (err, module) {
  console.log(module); // 7.9937735903076828
});
container.get('seven', function (err, module) {
  console.log(module); // 7.9937735903076828
});

If you want to use the literal function, set $factory = false on it.

Note how module() is a function invocation in the following example:

function g() {
  return Math.random();
}
g.$factory = false;
container.register('func', g);
container.get('func', function (err, module) {
  console.log(module()); // 0.44126248732209206
  console.log(module()); // 0.18552138609811664
});

If you do not want it to be a factory for a singleton, set $singleton = false on it.

Node how the module has a different value each time it is retrieved:

function h() {
  return Math.random();
}
h.$singleton = false;
container.register('singleton', h);
container.get('singleton', function (err, module) {
  console.log(module); // 0.5290916324593127
});
container.get('singleton', function (err, module) {
  console.log(module); // 0.6509554286021739
});

If a function fails to initialize a module, the callback will report that exception:

function e() {
  throw "damn it";
}
container.register('exceptional', e);
container.get('exceptional', function (err, module) {
  console.log(err); // "damn it" (would be `null` on success)
});

get(name, callback)

Retrieves an instance of the module named name.

Example:

container.get('module', function (err, instance) {
  if (err) {
    // report `err`
  } else {
    // do something with `instance`
  }
});

use(npmModule)

Uses the given npmModule.

Example:

container.use('nodash');
container.inject(function (nodash) {
  // `nodash` is the same as `require('nodash')`
  // but this way it is injected.
});

useAs(npmModule, alias)

Uses the given npmModule but registers it with the given alias.

Example:

container.useAs('nodash', 'theDash');
container.inject(function (theDash) {
  // ...
});

scan(directory, onSuccess, onError)

Scans the given directory and injects the onSuccess function. On any error while scanning or injecting onError is called. If onError is not a valid callback it will emit the unhandled_error event.

inject(function, callback)

Injects the given function in this containers context.

container.register('a', 1);
container.regsiter('b', 2);
container.inject(function (a, b) {
  console.log(a + b); // 3
});

injectWith(function, dependencies, callback)

Injects the given function with the given array of dependencies.

container.register('a', 1);
container.register('b', 2);
function f() {
  console.log(arguments[0]);
  console.log(arguments[1]);
}
container.injectWith(f, [ 'a', 'b' ]); // 1 \n 2 \n

Options

usePackageJson (boolean, default: true)

Whether dependencies from your package.json should automatically be picked up or not.

With this option, if your package.json contains nodash as a dependency, you can inject nodash without registering it by the means of container.use('nodash').

It is enabled by default.

autoRegister (array of strings)

An array of modules which should automatically be registered. By default this is a list of all the modules which are built-in to node (like path, fs, etc.). If you do not want any modules to be registered automatically just set this to [] (the empty array).

By default you can inject the modules that ship with node without explicitly registering them, i.e.

container.inject(function (fs, path) {
  // ...
});

will work without the need of explicitly doing container.use('fs') or container.use('path') first.

If you want to disable or change this behavior, you can set this option to a custom array, for example:

new WhiteHorse(require, {
  autoRegister: []
});

npmPrefix (string)

npmPostfix (string)

npmNormalize (boolean)

When true will normalize all npm module names loaded from package.json so that a module like hello-world-123 could be loaded by the name helloWorld123. This is primarily useful when auto registering modules and using their names in function declarations directly (otherwise modules like these would have to be mentioned in a $dependencies declaration).

By default false.

npmNameTransformer (function: string -> string)

Magic Modules

$root

The path to your project root, determined from the require method which you passed into the WhiteHorse constructor.

$module

The name of the module this instance is going to be injected into.

A factory which has $module as one of its dependencies is automatically regarded as $singleton = false, i.e. it will be invoked everytime the module it is registered as is injected somewhere.

container.register('magic', function ($module) {
  return $module;
});
container.register('a', function (magic) {
  console.log(magic); // "a"
});
container.register('b', function (magic) {
  console.log(magic); // "b"
});

$module is useful when building plugins. As an example: white-horse-config is using this mechanism to inject per-module configuration.

$done

A callback to finish loading of the module. If your module depends on this it is regarded as an asynchronous module (i.e. you must call $done or the module will never finish loading).

Example:

module.exports = function ($done) {
  $done(null, "finished loading");
};

container.register('f', function ($done) {
  $done(null, "success");
});
container.inject(function (f) {
  console.log(f); // prints "success"
});

Module annotations

$singleton (boolean, default: true)

$factory (boolean, default: true)

$dependencies (array of strings)

Events

initialized

retrieved

unhandled_error

warning

Plugin Development

$modules

If your module exports a $modules object, the modules are registered in the container when you use() this package.

module.exports.$modules = {
  f: function (fs, path, $done) {
    fs.readFile('someFile.txt', $done);
  },
  g: function (f) {
    return 'The text in someFile.txt is: ' + f;
  }
};

$loaders

$$..

License (MIT)

Copyright (c) 2015 Julian Alexander Fleischer

Permission is hereby granted, free of charge, to any
person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the
Software without restriction, including without
limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software
is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice
shall be included in all copies or substantial portions
of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.