nodep

Nodep

A simple dependency injection framework for Node.js inspired by Angular.js.

Inject directly into your exports functions!

module.exports = function(myDep) {
    // do something awesome with myDep
};

Installation

$ npm install --save nodep

Usage

Load dependencies into nodep

Dependencies can be loaded as follows:

• an array of strings of local dependency paths and npm module names
• a single string of a local dependency path or npm module name
• an object with the keys being the dependency names

Notes

• Local dependencies of type function will be executed and will have arguments injected into them
• Local dependencies of other types, e.g. Strings or Objects, will be injected as-is
• Local dependencies are changed to camel-case names without paths

Example

index.js

var $p = require('nodep')();

$p.init({
    myVar: localVariable
}).init([
    'anNpmPackage',
    './a/nested/local.dependency',
    './a.local.dependency'
]);

Use your dependencies like this:

a.local.dependency.js

module.exports = function(localDependency, myVar, anNpmPackage) {
    localDependency.doStuff();
    myVar.doStuff();
    anNpmPackage();
};

• ./a/nested/local.dependency becomes localDependency is executed and injectable
• anNpmPackage is loaded from node_modules
• myVar is injectable
• ./a.local.dependency becomes aLocalDependency is executed and injectable

Glob pattern matching for directories

$p.init also supports glob syntax for loading multiple files from a directory or directory tree

• Any file without a .js extension will be ignored
• glob docs and patterns

Example

index.js

var $p = require('nodep')();

$p.init('src/*').init([
    'anNpmPackage',
    './a/nested/local.dependency',
    'glob/patterns/*'
]);

Existing providers

Register other instances of nodep into your project.

Providers can be loaded as follows:

• an array of paths, npm module names, or local variables
• a single instance of any of the above

Example

index.js

var $p = require('nodep')();

$p.provider([
    'anNpmPackage',
    './a.local.provider',
    aLocalVariable
]).provider('anotherNpmPackage');

• Now all dependencies from anNpmPackage, aLocalVariable, and anotherNpmPackage are available for injection.

Inject dependencies at runtime

a.module.loaded.into.nodep.js

// $p is already available for injection
module.exports = function($p) {
    var myDependency = $p.inject('myDependency');
};

Override existing dependencies

// You can inject the old instance of this dependency
$p.decorator('aDependencyToOverride', function(aDependencyToOverride) {
    var oldDep = aDependencyToOverride;
});

Contributing

Requirements

• Gulp

$ npm install -g gulp

Running the test suite

Single Run:

$ gulp

Continuous testing when files are changed:

$ gulp autotest

Generating README.md

$ gulp docs

Generating CHANGELOG.md

$ gulp changelog

Notes

• jshint is part of the test suite and should be kept clean
• Pull requests should have high test coverage
• Docs should be kept up to date
• Additions should come with documentation
• commit messages should follow conventional format

API Reference

nodep : function

nodep~$p : Object

The dependency injection provider

Kind: inner property of nodep
Example

var $p = require('nodep')();

• ~$p : Object
  • .dependencies : Object
  • .nodep : Object
  • .module : Object
  • .dependencies.$p : Object
  • .CAMEL_CASE_REGEXP : RegExp
  • .CAMEL_CASE_CLEANUP : RegExp
  • .PATH_REPLACE_REGEXP : RegExp
  • .PATH_REPLACE_RESULT : String
  • .REMOVE_COMMENTS_REGEXP : RegExp
  • .REGISTER_TYPE_ERROR_MESSAGE : String
  • .CIRCULAR_DEPENDENCY_ERROR_MESSAGE : String
  • .PROVIDER_TYPE_ERROR_MESSAGE : String
  • .camelCase(match, $1, offset) ⇒ String
  • .name(path) ⇒ String
  • .args(fn)
  • .applyArgs(name, args, overwrite)
  • .decorator(name, dependency, [skipInject]) ⇒ Object
  • .easyRegister(path) ⇒ Boolean
  • .register(paths)
  • .resolveFiles(paths) ⇒ Array.<String>
  • .init(paths) ⇒ Object
  • .provider(instances) ⇒ Object
  • .inject(name) ⇒ ?

$p.dependencies : Object

The dependency reference storage object

Kind: static property of $p

$p.nodep : Object

The package of this library

Kind: static property of $p

$p.module : Object

The module of $p

Kind: static property of $p

$p.dependencies.$p : Object

An injectable reference to this module

Kind: static property of $p

$p.CAMEL_CASE_REGEXP : RegExp

Expression used to parse dependency names and format them to camel case

Kind: static constant of $p

$p.CAMEL_CASE_CLEANUP : RegExp

Expression used to clean up trailing characters in a path

Kind: static constant of $p

$p.PATH_REPLACE_REGEXP : RegExp

Expression to remove path and .js extension when calculating the dependency name

Kind: static constant of $p

$p.PATH_REPLACE_RESULT : String

Replace string when evaluating PATH_REPLACE_REGEXP

Kind: static constant of $p

$p.REMOVE_COMMENTS_REGEXP : RegExp

Expression to remove comments when parsing arguments for a dependency

Kind: static constant of $p

$p.REGISTER_TYPE_ERROR_MESSAGE : String

Error message to send when trying to register a non-string type

Kind: static constant of $p

$p.CIRCULAR_DEPENDENCY_ERROR_MESSAGE : String

Error message to send when a circular reference is detected in the dependency tree

Kind: static constant of $p

$p.PROVIDER_TYPE_ERROR_MESSAGE : String

Error message to send when trying to register a provider without dependencies

Kind: static constant of $p

$p.camelCase(match, $1, offset) ⇒ String

Used to format text into camel case

Kind: static method of $p
Returns: String - a camel case formatted result

Param	Type	Description
match	String	the matched text from a replace
$1	String	the first capture group
offset	String	the current index of the match group

$p.name(path) ⇒ String

Used to format dependency names from filenames

Kind: static method of $p
Returns: String - a formatted dependency name

Param	Type	Description
path	String	the file path to turn into a dependency name

$p.args(fn)

Will extract the order and name of injectable arguments in a given function

Kind: static method of $p

Param	Type	Description
fn	function	the function to extract injection arguments from

$p.applyArgs(name, args, overwrite)

Function to apply args to a new dependency and register it

Kind: static method of $p

Param	Type	Description
name	String	the name of the new dependency to register
args	Array.<String>	the names of args to apply to the new dependeency
overwrite	Boolean	overwrite the current dependency

$p.decorator(name, dependency, [skipInject]) ⇒ Object

Main dependency injection function

Dependency Handling:

• Dependencies with names, generated or otherwise, will not be overwritten by $p.register
• Local Dependencies
  • Dependencies with a path-like filename, e.g. ./my/project/example.js
  • Loaded relative to the parent module (the module that reqired nodep)
  • Resulting dependency will have a normalized filename produced by $p.name
  • Default naming scheme is lower-camel-case
  • Will be initialized if are of type {function}
  • Initialized functions will have dependencies injected according to that function's param names
• Global Dependencies
  • npm dependencies e.g. example
  • Loaded relative to the parent module (the module that reqired nodep)
  • Name remains unchanged for resulting dependency
  • Will not be initialized in the same manner as local dependencies

Kind: static method of $p
Returns: Object - a reference to this provider

Param	Type	Description
name	String	the name of a dependency to register to the provider
dependency	?	a value to assign to this dependency
[skipInject]	Boolean	inject into a provided dependency of type function unless true

$p.easyRegister(path) ⇒ Boolean

Easy dependency test, will register simple dependencies

Kind: static method of $p
Returns: Boolean - true if register was successful

Param	Type	Description
path	String	the name or filepath of a dependency to register to the provider

$p.register(paths)

Default registration function in front of $p.decorator

Kind: static method of $p

Param	Type	Description
paths	String | Array.<String>	the name or filepath of a dependency to register to the provider or an array of the former

$p.resolveFiles(paths) ⇒ Array.<String>

Function to normalize glob type paths into file paths omitting any non-js files

Kind: static method of $p
Returns: Array.<String> - an array with globbed paths normalized and merged with regular paths

Param	Type	Description
paths	Array.<String>	file paths and globbed paths

$p.init(paths) ⇒ Object

Load one or more dependencies into the provider Loading Mechanism:

• All strings in an array loaded into $p will be initialized according to $p.register
• Objects will have their members placed directly into $p.dependencies with keys of the same names
• Strings are treated as a single call to $p.register

Kind: static method of $p
Returns: Object - a reference to this provider

Param	Type	Description
paths	Array.<String> | Object | String	a list, key/value store, or single dependency

$p.provider(instances) ⇒ Object

Load an existing instance of nodep into this provider

Kind: static method of $p
Returns: Object - a reference to this provider

Param	Type	Description
instances	Array.<Object> | Object | String	an array of existing provider or single instance

$p.inject(name) ⇒ ?

Used to programmatically obtain a reference to a dependency

Kind: static method of $p
Returns: ? - a reference to the dependency with (name)

Param	Type	Description
name	String	The name of the dependency to inject

License

The MIT License (MIT)

Copyright (c) 2015 Brian Jesse

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.