coffee-sweetener

Small utility component that you can use in your applications to ease the management of dependencies between objects. The idea is simple, you have a factory object (we'll call this the injector) where you define some mappings. Each mapping has a unique id that you define. From different modules you can query the injector to give you a new instance of a specific mapping. Within classes you can define depenecies which will be satisfied on creation of a new instance of that class.

Dependency Injection in CoffeeScript

Table of Contents

coffee-sweetener

This is a small utility component that you can use in your applications to ease the management of dependencies between objects. The idea is simple, you have a factory object (we'll call this the injector) where you define some mappings. Each mapping has a unique id that you define. From different modules you can query the injector to give you a new instance of a specific mapping. Within classes you can define depenecies which will be satisfied on creation of a new instance of that class.

Installation

You can install the latest version through npm: npm install coffee-sweetener

API

# define a class 
class MyClass
    sayYeah: ->
        console.log "YEAH!"
# get the Injector 
CoffeeSweetener = require "coffee-sweetener"
Injector = new CoffeeSweetener()
 
# map MyClass in the Injector 
Injector.map
    klass: MyClass
# ask the Injector to give you a new instance of MyClass 
instance = Injector.getInstanceOf "MyClass"
# use the instance 
instance.sayYeah() # this print "YEAH!" to the console 
CoffeeSweetener = require "coffee-sweetener"
Injector = new CoffeeSweetener()

Every Injector will automatically create a mapping to itself as a Singleton called "Injector". This is useful if you want to get hold of the injector from within a class, by just specifying it in the list of the injection points.

CoffeeSweetener = require "coffee-sweetener"
Injector = new CoffeeSweetener()
 
class MyClass
    inject:
        injector: "Injector"

Every new instance of MyClass ( created through Injector.getInstanceOf) will have a property called injector which holds the reference to the Injector that created the class.

Just map the module by specifing the path. Be aware that this works only for modules which exports one class.

Injector.map
    modulePath: 'src/yourModule'

where yourModule is:

class YourModule
 
module.exports = YourModule

Here the name of the mapping will be inferred from the name of the class exported in the module.

class MyClass
    
Injector.map
    klass: MyClass

Here the name of the mapping will be automatically set to the name of the class.

user = "vizio"
Injector.map
    value: user
    name: "user"

A value can be anything, it can also be a function. When mapping a value you should always provide a name for the mapping.

class MyClass
    
Injector.map
    klass: MyClass
.asSingleton()

Everytime you then ask the injector for an instance of the class, you'll get back always the same instance.

This applies for all mapping types.

By passing the name to the mapping:

class MyClass
    
Injector.map
    klass: MyClass
    name: "NewName"

By calling the as() method:

class MyClass
    
Injector.map
    klass: MyClass
.as "NewName"

Once you've created your mappings you can ask the Injector for them:

class MyClass
    
Injector.map
    klass: MyClass
 
myInstance = Injector.getInstanceOf "MyClass"

For values the injector will always return that same value, it will not return a copy or a new instance of the value.

For mapped classes you can ask the Injector to get you the class definition object:

class MyClass
    
Injector.map
    klass: MyClass
# getting MyClass definition object 
myClass = Injector.getClassOf "MyClass"
# manually creating a new instance of MyClass 
myInstance = new myClass

Unmaps a mapping.

class MyClass
 
Injector.map
    klass: MyClass
 
Injector.unmap "MyClass"
Injector.getInstanceOf "MyClass" # this will throw an exception! 

Destroys all the mappings.

You can chain the calls to the different APIs when creating a mapping.

# mapping a class as a Singleton and specifying a new name for the mapping 
Injector.map
    modulePath: "yourModulePath"
.asSingleton().as("MySingleton")

Class Injection Points

It is possible, from within a class, to specify a list of dependencies which the Injector will try to satisfy when creating new instances of the class.

# assuming Wheels and Engine have already been mapped in the Injector 
class Car
    inject:
        wheels: "Wheels"
        engine: "Engine"
        
Injector.map
    klass: Car
 
myCar = Injector.getInstanceOf "Car"
console.log myCar.wheels # will print out an instance of the Wheels class 
console.log myCar.engine # will print out an instance of the Engine class 

This means that there is no need to require Wheels and Engine in the module file where Car is defined.

Instance initialisation

Everytime the Injector creates new instances, it will call the initInstance on the new instance if that method is defined. This is the place you want to put all your initialisation logic, because you can be sure that at that point all the dependencies have been resolved.

References

The API is inspired by SwiftSuspenders which I used while developing Flashy things.