https://github.com/cmtt/dijs
JavaScript dependency injection for Node and browser environments.
https://github.com/cmtt/dijs
dependency-injection javascript javascript-dependency-injection
Last synced: 8 months ago
JSON representation
JavaScript dependency injection for Node and browser environments.
- Host: GitHub
- URL: https://github.com/cmtt/dijs
- Owner: cmtt
- License: mit
- Archived: true
- Created: 2014-04-05T11:11:51.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2016-07-03T13:25:10.000Z (over 9 years ago)
- Last Synced: 2024-04-26T18:04:27.102Z (almost 2 years ago)
- Topics: dependency-injection, javascript, javascript-dependency-injection
- Language: JavaScript
- Size: 95.7 KB
- Stars: 50
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# dijs
dijs is a dependency injection framework for Node.js and browser environments.
It is inspired by [AngularJS](http://www.angularjs.org/) 1.x and allows to
choose between synchronous and asynchronous (using callbacks and promises)
resolution patterns in an non-opinionated way.
Featured on [DailyJS](http://dailyjs.com/2014/05/25/angular-roundup/).
# Example
````js
const Di = require('dijs');
class TestClass {
constructor (PI, RAD_TO_DEG) {
this.PI = PI;
this.RAD_TO_DEG = RAD_TO_DEG;
}
deg (value) {
return value * this.RAD_TO_DEG;
}
}
// Initialize a new dijs instance. By default, this will use "CallbackMethod",
// thus the first argument is "null" (instead providing another method).
// The $provide and $resolve method expect callback functions.
let instance = new Di(null)
// Provides a constant
.$provideValue('PI', Math.PI)
// Providing a constant using dependencies
.$provide('RAD_TO_DEG', (PI, callback) => callback(null, (180 / PI)))
.$resolve((err) => {
if (err) {
throw err;
}
let AnnotatedTestClass = instance.$annotate(TestClass);
let a = new AnnotatedTestClass();
// logs 180
console.log(a.deg(Math.PI));
});
````
# Options
## assign
By default, all provided values are being set on the dijs instance. This
behavior can be turned off:
````js
const Di = require('dijs');
let d = new Di(null, 'Math', { assign : false });
d.$provide('PI', function (callback) {
callback(null, Math.PI);
});
d.$resolve(function (err) {
if (err) {
throw err;
}
console.log(`d.PI is undefined`, d.PI === undefined);
console.log(`d.$get("PI") equals Math.PI`, d.$get('PI') === Math.PI);
});
});
````
# Usage
## new Di(Method, name, options)
Returns a new dijs instance with the given method (CallbackMethod is the
default one).
## Instance methods
### $annotate(classFn)
Returns a class which will be initialized with the dependencies stated in
classFn's constructor. When classFn is a function, its parameters are being
resolved to matching dependencies.
This method must called after $resolve().
### $get(id)
Returns the (previously provided) sub-module specified by a dot-delimited id.
### $inject(arg)
Calls a function with (already-provided) dependencies. It is required to call
$resolve beforehand.
Dependant on the current resolution method, this function is synchronous or
asynchronous
### $provide(key, object, passthrough)
Provides a module in the namespace with the given key.
If passthrough is set, the object will be just passed through, no dependencies
are looked up this way.
### $provideValue(key, object)
Provides a value in the namespace with the given key (shortcut for $provide
using passthrough).
### $resolve()
Resolves the dependency graph.
This method might take a callback function (in case of the default
CallbackMethod) or return a promise with PromiseMethod.
### $set(id, value)
Sets a value in the namespace, specified by a dot-delimited path.
# Resolution methods
By default, dijs uses the asynchronous CallbackMethod in order to resolve
dependencies. Require them as follwing:
````js
const Di = require('dijs');
const SyncMethod = require('dijs/methods/sync');
const PromiseMethod = require('dijs/methods/promise');
````
## CallbackMethod
Asynchronous providing and resolving dependencies using Node.js-style callback
functions.
It is expected that the last parameter of your callback functions is called
"callback", "cb" or "next".
This function takes an error (or a falsy value like null) as first argument. The
second argument should be the provided value.
````js
let d = new Di();
d.$provide('PI', (callback) => { // alternative names: cb or next
callback(null, Math.PI);
});
d.$resolve((err) => {
if (err) {
return done(err);
}
assert.equal(d.PI, Math.PI);
done();
});
````
## PromiseMethod
Provides and resolves dependencies using the ES2015 Promise API.
````js
let d = new Di();
d.$provide('PI', Promise.resolve(Math.PI));
d.$provide('2PI', (PI) => Promise.resolve(2 * Math.PI));
d.$resolve().then(() => {
assert.equal(d['2PI'], 2 * Math.PI);
done();
}, (err) => {
done(err);
});
````
## SyncMethod
Synchronous way to provide and resolve depdencies.
````js
let d = new Di(SyncMethod);
d.$provide('PI', Math.PI);
d.$provide('2PI', (PI) => 2 * Math.PI);
d.$resolve();
assert.equal(d['2PI'], 2 * Math.PI);
````
# Reference
## Notation
If you don't pass a value through, you can choose between the function and the
array notation to describe the module's dependencies. In any case, you will need
to pass a function whose return value gets stored in the namespace. Its
parameters describe its dependencies.
### function notation
To describe a dependency, you can pass a function whose parameters declare the
other modules on which it should depend.
Note: You cannot inject dot-delimited dependencies with this notation.
````js
var mod = new Di();
mod.$provide('Pi',Math.PI, true);
mod.$provide('2Pi', function (Pi, callback) { callback(null, return 2*Pi); });
// ...
````
### array notation (minification-safe)
When your code is going to be minified or if you are about to make use of nested
namespaces, the array notation is safer to use. All dependencies are listed as
strings in the first part of the array, the last argument must be the actual
module function.
````js
var mod = new Di();
mod.$provide('Math.Pi',Math.PI, true);
mod.$provide('2Pi', ['Math.Pi', function (Pi, callback) {
callback(null, 2*Pi);
}]);
// ...
````
#### notation with "$inject" (minification-safe)
An alternative way is to provide a "$inject" property when using $annotate or
$provide. This requires minification tools being in use not to mangle this key:
````js
class TestClass {
constructor (pi) {
this.RAD_TO_DEG = (180 / pi);
}
deg (value) {
return value * this.RAD_TO_DEG;
}
}
TestClass['$inject'] = ['PI'];
var mod = new Di();
mod.$provideValue('PI', Math.PI);
mod.$resolve((err) => {
if (err) { throw err; }
let WrappedTestClass = mod.$annotate(TestClass);
let instance = new WrappedTestClass();
console.log(instance.deg(Math.PI * 2)); // 360
});
````
# Namespacing
Each dijs instance has a new namespace instance at its core. Namespaces provide
getter/setter methods for sub-paths:
````js
var Namespace = require('dijs/lib/namespace');
var namespace = new Namespace('home');
namespace.floor = { chair : true };
assert.deepEqual(namespace.$get('home.floor'), { chair : true})
namespace.$set('home.floor.chairColor', 'blue');
assert.deepEqual(namespace.floor, { chair: true, chairColor: 'blue' });
````
Please note that dijs assigns all namespace values to instances. You can disable
this behavior using the "assign" option (see above).
# Usage in the browser
Bundled versions are available in the dist/ folder.
You can create a minified build with Google's Closure compiler by running
````make```` in the project directory.
# License
MIT (see LICENSE)