Sandal is a javascript inversion of control container
$ npm install sandal
// For use in browsers, including sandal.js will create a global Sandal constructor
var Sandal = require('sandal');
var sandal = new Sandal();
sandal
.registerService('service1', function (service2, factory1, object1) {})
.registerService('service2', function (done) {
setTimeout(function() { done(); }, 500);
})
.register('object1', 'any object')
.registerFactory('factory1', function(object1) {
return 'another object';
}, true) // Setting transient lifecycle
.resolve(function(error, service1) {
// Resolves service1 and all dependencies
})
There are three ways you can register:
sandal.register(name, implementation);
sandal.registerService(name, constructor, transient);
sandal.registerFactory(name, factory, transient);
A module registered with register
will always have a singleton lifecycle. Resolving will always return the same instance.
A module registered with registerFactory
must be a function. The return value of the function will be the resolved value. The default lifecycle is singleton meaning that the function is only evaluated once. By setting transient
to true
the function will be evaluated every time.
A module registered with registerService
must be a function. The function will be called as a constructor with the new keyword. The default lifecycle is singleton meaning that the constructor is only evaluated once. By setting transient
to true
the constructor will be evaluated every time.
Note that the service or factory is evaluated when resolved and not when registered.
There are two reserved words that can not be used as names:
sandal
will inject the ioc containerdone
will inject a done callback
Resolving can be done in the following ways:
sandal.resolve(callback);
sandal.resolve(name, callback);
sandal.resolve([names], callback);
The first argument of the callback will be any error from resolving.
Resolving with only a callback will user the argument names of the callback function.
Resolving with a name will resolve based on the provided name and inject into the callback.
Resolving with an array of names will resolve based on the provided names and inject into the callback in the same order.
Registering with a name that is already registered will throw an error. To replace an implementation you first need to clear the current one. It is possible to clear all, one or a set of modules:
sandal.clear(); // Clear all modules
sandal.clear(name);
sandal.clear([names]);
If a service or factory has some asynchronous tasks that needs to be done before the instance can be used, it should take an argument named done
.
That will inject a done
callback to the constructor. Calling the done callback with an error will pass the error to the resolve callback.
Resolving a module with dependencies to an asynchronous service or factory will wait for all dependencies to be done before calling the constructor or function.