agentia-asset-manager

v1.1.0

Published

2 years ago

A lazy dependency injection framework for Node.js

Downloads

0High
0Medium
0Low

johnnyestilles

dependency injection lazy framework node nodejs module factory

A lazy dependency-injection framework for Node.js

Installation

agentia-asset-manager is available on npm.

npm install --save agentia-asset-manager

Usage

var AssetManager = require('agentia-asset-manager');
var container = AssetManger.create();

Concepts

agentia-asset-manager allows you to create an asset container where you can register assets. Some assets (ie. dependency-injectable function or factory) can require/depend on other assets. Since dependencies are lazily resolved, assets can be registered in any order, so long as all required dependencies are registered prior to asset resolution.

Within agentia-asset-manager there are four (4) times assets that can be registered:

Asset Type | Description ---------- | ----------- function | This can be either a dependecy-injectable function (factory) or a simple non-injenctable function. This is determined by the injectable parameter during asset registration. module | Any requirable Node.js module.If the module returns a function, it can also be treated as a factory or a simple function (see function above.)If the module returns anything other than a function, it will be registered as a instance (see below). hash | Any object hash, the properties of which will be treated and registered as individually registered.If the property is a function it be treated as a function asset (see explanation above), otherwise it will be treated as an instance asset (see explanation below). instance | Anything other than what is listed above (ie. string, number, date, array or object). Objects registered as an instance will be registered as a single asset, unlike a hash which will register every property as a distinct asset.

NOTE: Simple (non-injectable) function assets will always resolve to the actual function, where as factory (injectable) function assets will be injected with their required dependencies prior to resolution, will always resolve to their returned value.

Static API

.create()

Create a new AssetManager container instance

AssetManager.create([compatibility])

param | type | description | default ----- | :--: | ----------- | ------- compatibility | boolean | Determines whether compatibility methods will also be added | false

Example

var instanceA = AssetManager.create(); // <-- without compatibility methods
var instanceB = AssetManager.create(true); // <-- with compatiblity methods

.mixin()

Add AssetManager functionality to an existing object

AssetManager.mixin(instance,[compatibility])

param | type | description | default ----- | :--: | ----------- | ------- instance | object | Object instance onto which AssetManager functionality will be added | none compatibility | boolean | Determines whether compatibility methods will also be added | false

Example

var instance = {
  fnA: function() {},
  fnB: function() {},
  key: 'value'
};

AssetManager.mixin(instance); // <-- without compatibility methods

// --- OR ---

AssetManager.mixin(instance, true); // <-- with compatibility methods

.attach()

Attach AssetManager functionality to an existing class

AssetManager.attach(class,[compatibility])

param | type | description | default ----- | :--: | ----------- | ------- class | function | Class onto which AssetManager functionality will be added | none compatibility | boolean | Determines whether compatibility methods will also be added | false

Example

function MyClass() {
  this.__key = 'value';
  return this;
}
MyClass.prototype.fnA = function() {};
MyClass.prototype.fnB = function() {};

AssetManager.attach(MyClass); // <-- without compatibility methods

// --- OR ---

AssetManager.attach(MyClass); // <-- with compatibility methods

Core API

.registerFunction()

Used to register a function asset.

container.registerFunction(id, fn[, injectable]);

param | type | description | default ----- | :--: | ----------- | ------- id | string | Used to identify the registered the asset. | none fn | function | Function to be registered as an asset | none injectable | boolean | When true, the asset will be treated as a factory, otherwise it will be treated as a simple function | false

Example

var fn = function(a, b) {
  return a + b;
};

// register as a dependency injectable factory
container.registerFunction('myFactory', fn, true);

// register as a non-injectable function
container.registerFunction('myFunction', fn, false);

.registerHash()

Used to register a hash asset.

container.registerHash(hash[, injectable]);

param | type | description | default ----- | :--: | ----------- | ------- hash | object | An object hash, the properties of which will all be individually registered as assets. | none injectable(optional) | boolean | When true, the asset will be treated as a factory, otherwise it will be treated as a simple function | false

NOTE: injectable is applicable to object property that return a function. It will be ignored for all other properties.

Example

var hash = {
  assetA: 'string',
  assetB: 12345,
  assetC: {
    key1: 'value1',
    key2: 'value2'
  },
  assetD: function(a, b) {
    return a + b;
  }
};

container.registerHash(hash, true); // <-- with di enabled
// assetA --> registered as `instance` assets
// assetB --> registered as `instance` assets
// assetC --> registered as `instance` assets
// assetD --> registered as a factory `function` asset

container.registerHash(fn, false); // <-- with di disabled
// assetA --> registered as `instance` assets
// assetB --> registered as `instance` assets
// assetC --> registered as `instance` assets
// assetD --> registered as a simple `function` asset

.registerModule()

Registers any Node.js requirable module as an asset. If it can be required using require() it can be registered using .registerModule().

container.registerModule([id,] module[, injectable]);

param | type | description | default ----- | :--: | ----------- | ------- id(optional) | string | Used to identify the registered the asset. When not specified, the module name (or its basename if it is path to a file), will be converted to camel case and used as the id | none module | string | Path to module to be registered | none injectable(optional) | boolean | When true, the asset will be treated as a factory, otherwise it will be treated as a simple function. | false

NOTE: injectable is applicable when the registered module returns a function. It will otherwise be ignored.

Example

// register as a dependency injectable module
var pathToModuleA = require.resole('./path/to/my/module');
container.registerModule('moduleA', pathToModuleA, true);

// register as a non-injectable function
container.registerModule('moduleB', 'npm-module', false);

var pathToModuleC = require.resolve('./path/to/my/my-fancy-module');
container.registerModule(pathToModuleC); // <-- will use myFancyModule as the asset id

// register as a non-injectable function
container.registerModule('npm-module'); // <-- will use npmModule as the asset id

NOTE: You should typically (if not always) turn off dependency injection, when registering an NPM module.

.registerInstance()

container.registerInstance(id, instance);

param | type | description | default ----- | :--: | ----------- | ------- id | string | Used to identify the registered the asset. | none instance | any | Asset to be registered. Can be a string, number, date, array, or object. | none

Example

container.registerInstance('a', 'string');
container.registerInstance('b', 12345678);
container.registerInstance('c', new Date());
container.registerInstance('d', { key: 'value' });
container.registerInstance('e', ['value1', 'value2']);

.registerFiles()

Searches for any .js files in a folder and registers each as a module .

container.registerFiles(pattern[, injectable);

param | type | description | default ----- | :--: | ----------- | ------- pattern | string | A glob pattern string specifying files to register | none injectable(optional) | boolean | When true, the asset will be treated as a factory, otherwise it will be treated as a simple function. | false

Example

var pathToFolder = path.join(__dirname, './path/to/folder')
container.registerFiles(pathToFolder, true); // <-- will treat exported functions as factories

.inject()

Inejcts a function with dependencies and returns its value. F

container.inject(ifn[, overrides][, context]);

param | type | description | default ----- | :--: | ----------- | ------- fn | function | Function to inject with dependencies and resolve. | none overrides (optional) | object | Optional object hash providing values with which to override dependencies | none context (optional) | object | Optional object that will be used as a context when resolving the asset, when the asset is a factory | none

var fn1 = function(a, b) {
  return a + b;
};

var fn2 = function(a, b) {
  return a + b + this.c;
};

// register assets
container.registerInstance('a', 5);             // <-- instance asset
container.registerInstance('b', 10);            // <-- instance asset
var

// resolve assets
var result = container.inject(fn1); // <-- resolved to 15
var withOverride = container.inject(fn1, { a: 1, b: 2}); // <-- resolves to 3
var withContext = container.inject(fn2, { a: 1, b: 2}, { c: 3 }); // <-- resolves to 6

.resolve()

Resolve a registered asset. For dependency-injectable factories (functions and modules), it resolves all it's dependencies before calling the factory function, resolving to it's return value. All other assets are returned "as-is".

container.resolve(id[, overrides][, context]);

param | type | description | default ----- | :--: | ----------- | ------- id | string | Used to identify the registered the asset. | none overrides (optional) | object | Optional object hash providing values with which to override dependencies | none context (optional) | object | Optional object that will be used as a context when resolving the asset, when the asset is a factory | none

var fn1 = function(a, b) {
  return a + b;
};

var fn2 = function(a, b, sum) {
  return a * b + sum;
};

// register assets
container.registerFunction('sum', fn, true);    // <-- factory asset
container.registerInstance('a', 5);             // <-- instance asset
container.registerInstance('b', 10);            // <-- instance asset
container.registerFunction('fn1', fn1, false);  // <-- simple function asset

// resolve assets
var resultA = container.resolve('a');     // <-- resolves to 5
var resultB = container.resolve('b');     // <-- resolves to 10
var resultSum = container.resolve('sum'); // <-- resolved to 15
var resultFn1 = container.resolve('fn1'); // <-- resolve to function "fn"
var resultFn2 = container.resolve(fn2);   // <-- resolves to 65
var override = container.resolve(fn1, { a: 1, b: 2}); // <-- resolves to 3