Magnum DI

A super simple Scoped Dependency Injection framework for NodeJS

1npm install --save magnum-di

1//Load it up./
2var injector = require('magnum-di')()
3
4//Register some dependencies.
5injector.service('MyService', {name: 'Bob', sayName: function(){console.log(this.name)}})
6
7//inject them into your function
8injector.inject(function(MyService){
9    MyService.sayName() // -> Bob
10})

Why Dependency Injection?

• Managing complex applications with many files. Maintaining module dependencies in one location reduces errors and makes an application easier to reason about.
• Procedurally loading files with dependencies becomes much easier.
• Ease of testing in isolation, mocking module dependencies becomes trivial. No need to use a module to fiddle with the internals of require to get a mocked object into your module. With DI just register a different module with the correct methods and you are done mocking.

Examples

Express route definitions.

Here we register a dependency in our main application file, and use the injector to call the function returned by the require('./UserModel) call.

Run this with npm run example-server

1
2//userRoutes.js
3
4module.exports = function(Router, User) {
5
6  //Here Router and User will be injected.
7  Router.get('/', function(req, res, next){
8    User.userDetails('Bob', function(err, data){
9      res.json({user: data})
10    })
11  });
12
13  return {path: '/user', router: Router}
14};
15
16
17//app.js
18
19var injector = require('magnum-di')();
20var express = require('express');
21var Database = require('./Database');
22var app = express()
23var http = require('http');
24
25//Register some dependencies.
26injector.factory('Router', express.Router);
27injector.service('Database', Database);
28
29//Here we are letting the injector provide the database to our UserModel
30//This will make it simple to mock in our unit tests.
31var User = injector.inject(require('./UserModel'));
32injector.service('User', User);
33
34var userRoute = injector.inject(require('./UserRoutes'));
35
36app.use(userRoute.path, userRoute.router);
37
38http.createServer(app).listen(8080);

Mocking database for testing

Following our above example, we use magnum-di to mock out our Database object for testing.

Run this with npm run example-test

1
2var injector = require('magnum-di');
3var should = require('should');
4
5//Our mock database object
6injector.service('Database', {
7  User: {
8    users: {George: {name: 'George', age: 30}, Mike: {name: 'Mike', age: 20}},
9    find: function(username, cb) {
10     var user = (this.users[username]) ? this.users[username] : null
11     cb(null, user);
12    }
13  }
14});
15
16//We now have a user model that is using our mock database.
17var User = injector.inject(require('./UserModel'));
18
19describe('Model being tested with a mock Database object', function() {
20
21  it('should not have real data', function(done) {
22    User.userDetails('Bob', function(err, data){
23      should(data).be.null
24      done()
25    })
26  });
27
28  it('should have mock data', function(done) {
29    User.userDetails('George', function(err, data){
30      data.age.should.equal(30)
31      done()
32    })
33  });
34
35});
36

API

MagnumDI

Kind: global class

• MagnumDI
  • new MagnumDI()
  • .createChild() ⇒ MagnumDI
  • .service(name, item) ⇒ *
  • .instance(name, fn) ⇒ function
  • .factory(name, fn) ⇒ function
  • .merge(name, merge) ⇒ *
  • .get(name) ⇒ * | null
  • .replace(name, replacement) ⇒ Object
  • .unregister(name) ⇒ boolean
  • .inject(fnOrstr, thisArg) ⇒ *

new MagnumDI()

Provides an instance of the Magnum DI injector.

magnumDI.createChild() ⇒ MagnumDI

Creates a Child instance of the current injector. Calls to .get or .inject will first search this injector, if a parameter is found it will return it if not it will continue up the tree until a value is found or the topmost instance is reached.

Kind: instance method of MagnumDI

magnumDI.service(name, item) ⇒ *

Registers an object, string, number or function.

Kind: instance method of MagnumDI Returns: * - Returns provided dependency

Param	Type	Description
name	string	Name to be used in the injected function
item	object | array | number | string | function	Item to be injected.

magnumDI.instance(name, fn) ⇒ function

When injected, calls as a constructor with new.

Kind: instance method of MagnumDI Returns: function - Returns provided function

Param	Type	Description
name	string	Name to be used in the injected function.
fn	function	Function to be called with new.

magnumDI.factory(name, fn) ⇒ function

When injected, calls the passed function. Returns the result of that call.

Kind: instance method of MagnumDI Returns: function - Retuens provided function.

Param	Type	Description
name	string	Name to be used in the injected function
fn	function	Function to be called by injector.

magnumDI.merge(name, merge) ⇒ *

Merges supplied object into the object registered for , if doesn't exist it will be created.

Kind: instance method of MagnumDI Returns: * - Returns provided dependency

Param	Type	Description
name	String	Dependency object to modify
merge	Object	Object to merge with existing dependency

magnumDI.get(name) ⇒ * | null

Returns the specified dependency.

Kind: instance method of MagnumDI Returns: * | null - The named dependency item, or null.

Param	Type	Description
name	string	Dependency to retrieve.

magnumDI.replace(name, replacement) ⇒ Object

Modifies a registered service object.

Kind: instance method of MagnumDI Returns: Object - Replaced dependency

Param	Type	Description
name	String	Dependency object to modify.
replacement	Object	Object to replace current registered object.

magnumDI.unregister(name) ⇒ boolean

Removes the specified dependency.

Kind: instance method of MagnumDI Returns: boolean - The result of the operation.

Param	Type	Description
name	string	Registered dependency to remove.

magnumDI.inject(fnOrstr, thisArg) ⇒ *

Runs the given function with args injected and with an optional context object.

Kind: instance method of MagnumDI Returns: * - Returns the result of the called function.

Param	Type	Description
fnOrstr	function | string	function - inject args and run, string - Return the named dependency.
thisArg	object	Calling context.

Contributing

Check out, add, document, test.

Run tests with npm test. Regenerate this Readme with npm run readme

licence

MIT