Gerenuk attempts to work around various problems that arise when working with asynchronous code. Its main goal is to facilitate easy application set up and independence of various parts of your code, in accordance with Demeter's law.
Gerenuk is a Dependency Injection Container (DIC) that can hold various "services". You can retrieve a service from Gerenuk through the
get method. Every service has a unique identifier, which is passed to
get. Services can have dependencies on other services, which get injected into their constructor or passed to a function you specify.
# Sample config config = # Simple service ("foo") with two params, and a child within a child ("foo.bar.baz") foo: require: 'fooPackage' params: param1: 'param one' param2: 'param two' inject ['foo.param1', 'foo.param2'] # Children of foo children: bar: children: baz: 'bazPackage' # Create an instance of barPackage's Bar and pass the foo service to the constructor # This is like new (require 'barPackage').Bar foo bar: require: 'barPackage' instantiate: 'Bar' inject: ['foo'] # Instead of creating an instance the `bazFunction` will be called on bazPackage # `foo` and `bar`'s resolved services are passed as params baz: require: 'bazPackage' inject: ['foo', 'bar'] call: 'bazFunction'
You can pass this configuration to Gerenuk's Container:
# DI Container Container = (require 'gerenuk').Container # Container dic = new Container config
Using the container you can resolve services:
dic.get 'foo', (service) -> ... your code ...
When setting up your application, it is often useful to put your DI config into a configuration file (or files). Gerenuk supports this through the
loadConfig() method. The config loaded through
loadConfig() will be added to any existing configuration. It does not do a deep merge, however, and will throw an exception if you try to overwrite an existing config key.
dic = new Container dic.loadConfig 'yourConfigFile'
The contents of
yourConfigFile.coffee would be like:
module.exports = foo: 'fooPackage' bar: require 'barPackage' instantiate: 'bar' ...etc...
You can also use
loadConfig inside of a config item, replacing its contents with the loaded config. This has the disadvantage that the items loaded through this do not explicitly know the name of the node they are in, making it hard(er) to set up references.
dic = new Container foo: loadConfig: 'yourConfigFile'
One of the more challenging aspects of working with node is asynchronous instantiation of resources. You may, for example, need to connect to a database before you can perform other operations. Gerenuk attempts to aid you with this by supporting asynchronously resolvable services.
In the example of the database connection, you might do the following
config = connection: require: 'dbPackage' # Callback on the instance of dbPackage callback: (db, callback) -> db.connect (error, connection) -> throw "Error!" if error callback connection
Gerenuk keeps track of services it's currently waiting on. This means that when asking for a service twice, before it's ready, will still give you the same object, once for both injections.
Sometimes you don't want to instantiate a service, but get a set of services injected into a callback. If you need to combine some services, and asynchronously - either through events or a callback - get a new service, you can inject directly into a callback. This gives you complete control of the instantiation of a service.
config = # Foo package foo: require: 'fooPackage' params: param1: 'bar' param2: 'baz' inject: ['foo.param1', 'foo.param2'] # Bar has no require, but just gets `foo` injected into a callback bar: params: param1: 'foo' injectCallback: ['foo', 'bar.param1'] # The callback gets all injected services in order as the first parameters # As the last param it gets a callback you call with the resolved service callback: (foo, param, callback) -> foo.someAsyncFuncThatCreatesBar (bar) -> callback bar
Another frequently encountered pattern is that the resource you're working with emits an event when it's ready for duty. When you have to wait for such an event to happen you can listen to it in the callback. Note that in this case "foo" will be instantiated, by the container. The callback waits for it to emit "connected", then passes the instance of "foo" back. Any services that are injected with foo can then assume it's connected.
config = foo: require: 'fooPackage' # Set up host/port config for foo params: host: 'hostname' port: 12345 inject: ['foo.host', 'foo.port'] # callback gets passed an instance of fooPackage callback: (foo, callback) -> foo.on 'connected', () -> callback foo do foo.connect
When config is a string, the DIC will act like nothing more than wrapper around require(), the resulting object will be seen as the actual service.
config = foo: 'fooPackage'
Same as before, but more explicit
config = foo: require: 'fooPackage'
instantiate: true the container will attempt to create a new object directly from whatever
require gave back, which is handy when you have a package directly exporting a single class:
module.exports = SomeClass.
config = fooInstance: require: 'fooPackage' instantiate: true
When you only want to instantiate a part of the
module.exports hash, you can name it in instantiate, in this case
# In fooPackage module.exports = foo: FooClass bar: BarClass # In DIC config config = bar: require: 'fooPackage' instantiate: 'bar'
The container will become really useful as soon as you start to inject services into other services. You can use
inject to set up an array of services passed to the constructor. When
inject is set, the DIC assumes that you want to instantiate.
config = bar: require: 'barPackage' instantiate: true foo: require: 'fooPackage' inject: ['bar']
You can set parameters, which you can reference by their name, just like a service. You can mix and match params and services in the
inject array, but params get preference over (child) services if they have the same name.
config = foo: require: 'fooPackage' params: param1: 'foo' param2: 'bar' inject: ['foo.param1', 'foo.param2']
Services can have children, in this case the id of the child is
config = foo: children: bar: # `foo.bar` works as a regular service, as well as parent for `foo.bar.baz` require: 'barPackage' instantiate: true children: baz: require: 'bazPackage' instantiate: true
It is possible to spread your DI config over multiple files. You can specify a package and use as a config for a service. When using
loadConfig the entire node of the configuration you specify it for will be overwritten by the contents of the exports from the loaded file.
config = foo: loadConfig: 'fooConfig'
Children can load configs just like their parents can:
config = foo: children: bar: loadConfig: 'barConfig'
When you don't want to instantiate, but rather call a method from a required package, you can use
call. The function named in
call is assumed to return the service directly (synchronously).
config = bar: require: 'barPackage' call: 'barFunction'
Call can also use injection, so the following would work like
(require 'fooPackage').someFunction bar, baz, where foo and baz are resolved services, which can themselves have dependencies, etc.:
config = ... snip ... foo: require: 'fooPackage' inject: ['bar', 'baz'] call: 'fooFunction'
When going even further down the road towards asynchrony, you can set up a
callback, which gets called on an instance of an object. The callback gets passed both the object and a function you are required to call with the service once you're done setting it up.
config = foo: require: 'fooPackage' # callback gets passed an instance of fooPackage callback: (foo, callback) -> foo.doSomethingWithACallback (somethingUseful) -> callback somethingUseful
You can also hook into EventEmitters with this:
config = foo: require: 'fooPackage' instantiate: true # callback gets passed an instance of fooPackage callback: (foo, callback) -> foo.on 'connect', () -> callback foo do foo.connect