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 = ;var container = AssetManger;
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
param | type | description | default |
---|---|---|---|
compatibility | boolean |
Determines whether compatibility methods will also be added | false |
Example
var instanceA = AssetManager; // <-- without compatibility methodsvar instanceB = AssetManager; // <-- with compatiblity methods
.mixin()
Add AssetManager functionality to an existing object
AssetManager
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 = {} {} key: 'value'; AssetManager; // <-- without compatibility methods // --- OR --- AssetManager; // <-- with compatibility methods
.attach()
Attach AssetManager functionality to an existing class
AssetManager
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
{ this__key = 'value'; return this;}MyClassprototype {};MyClassprototype {}; AssetManager; // <-- without compatibility methods // --- OR --- AssetManager; // <-- with compatibility methods
Core API
.registerFunction()
Used to register a function
asset.
container;
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 { return a + b;}; // register as a dependency injectable factorycontainer; // register as a non-injectable functioncontainer;
.registerHash()
Used to register a hash
asset.
container;
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' { return a + b; }; container; // <-- 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; // <-- 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;
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 modulevar pathToModuleA = require;container; // register as a non-injectable functioncontainer; var pathToModuleC = require;container; // <-- will use myFancyModule as the asset id // register as a non-injectable functioncontainer; // <-- will use npmModule as the asset id
NOTE: You should typically (if not always) turn off dependency injection, when registering an NPM module.
.registerInstance()
Register any string
, number
, date
, array
, or object
as an instance
asset.
container;
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;container;container;container;container;
.registerFiles()
Searches for any .js
files in a folder and registers each as a module .
container;
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 = pathcontainer; // <-- will treat exported functions as factories
.inject()
Inejcts a function with dependencies and returns its value. F
container;
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 { return a + b;}; var { return a + b + thisc;}; // register assetscontainer; // <-- instance assetcontainer; // <-- instance assetvar // resolve assetsvar result = container; // <-- resolved to 15var withOverride = container; // <-- resolves to 3var withContext = container; // <-- 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;
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 { return a + b;}; var { return a * b + sum;}; // register assetscontainer; // <-- factory assetcontainer; // <-- instance assetcontainer; // <-- instance assetcontainer; // <-- simple function asset // resolve assetsvar resultA = container; // <-- resolves to 5var resultB = container; // <-- resolves to 10var resultSum = container; // <-- resolved to 15var resultFn1 = container; // <-- resolve to function "fn"var resultFn2 = container; // <-- resolves to 65var override = container; // <-- resolves to 3
Helpers
.isRegistered()
Determines if an asset is registered.
container;
param | type | description | default |
---|---|---|---|
id | string |
Used to identify the registered the asset. | none |
Example
container;if container ;
.isInjectable()
Determines if an asset is a dependency-injectable factory.
container;
param | type | description | default |
---|---|---|---|
id | string |
Used to identify the registered the asset. | none |
Example
var { returns a + b;};container;if container ;
.isInstance()
Determines if an asset is an instance
.
container;
param | type | description | default |
---|---|---|---|
id | string |
Used to identify the registered the asset. | none |
Example
container;if container ;
.isFunction()
Determines if an asset is a function. It returns true
for both factories and non-injectable functions.
container;
param | type | description | default |
---|---|---|---|
id | string |
Used to identify the registered the asset. | none |
Example
var { returns a + b;};container;if container ;
.isModule()
Determines if an asset is module.
container;
param | type | description | default |
---|---|---|---|
id | string |
Used to identify the registered the asset. | none |
Example
container;if container ;
Compatibility API
The following API was include solely to maintain compatibility with dependable
. These methods may be deprecated in future versions.
WARNING: I DO NOT guarantee that these methods are IDENTICAL to their
dependable
counterparts. They are only provided to ease the transition fromdependable
toagentia-asset-manager
. If you're adependable
consumer, I suggest you transition to our core API as soon as possible.
.register()
Register assets. This is functionally equivalent to the .register()
method in dependable
.
Note: .register() as dependency-injection enabled by default, to mimic it behavior in
dependable
container;container;container;
When called with | Functionally equivalent to |
---|---|
.register(id, fn) |
container.registerFunction(id, fn, true) . |
.register(id, value) |
container.registerInstance(id, instance) |
.register(hash) |
container.registerHash(hash, true) |
.get()
Returns a resolve asset by id.
container;
This method is functionally equivalent to container.resolve(id[, overrides]);
.
.load()
Registers a file, or all the files in a folder.
Note: .load() as dependency-injection enabled by default, to mimic it behavior in
dependable
container;
When called with | Functionally equivalent to |
---|---|
.load(file) |
container.registerModule('file', 'file', true) . |
.load(folder) |
container.registerFiles(path.join(folder, '*.js'), true)) |
Attributions
agentia-asset-manager is loosely based, and greatly inspired by dependable.
dependable
Copyright (c) 2013 [i.TV LLC][idottv-url]
https://github.com/idottv/dependable
Since the dependable project appears to be abandoned, I've decided to make the initial version of agentia-asset-manager backwards compatible (as much as possible) with the last version of dependable. This way existing dependable consumers can easily transition to agentia-asset-manager.
License
agentia-asset-manager is free and open source under the MIT License.
Copyright (c) 2015 Johnny Estilles, http://www.agentia.asia
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.
[idottv-url]: https://github.com/idottv)