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.
Table of Contents
- Let's start with an example
- Create an Injector
- .map( mappingObject )
- .as( newName )
- .getInstanceOf( mappingName )
- .getClassOf( mappingName )
- .unmap( mappingName )
- Fluent API
- Class Injection Points
- Instance initialisation
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.
You can install the latest version through npm:
npm install coffee-sweetener
# define a class: ->consolelog "YEAH!"# get the InjectorCoffeeSweetener = require "coffee-sweetener"Injector =# map MyClass in the InjectorInjectormapklass: MyClass# ask the Injector to give you a new instance of MyClassinstance = InjectorgetInstanceOf "MyClass"# use the instanceinstancesayYeah # this print "YEAH!" to the console
CoffeeSweetener = require "coffee-sweetener"Injector =
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 =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.
module.exports = YourModule
Here the name of the mapping will be inferred from the name of the class exported in the module.
Here the name of the mapping will be automatically set to the name of the class.
user = "vizio"Injectormapvalue: username: "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.
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:
Injectormapklass: MyClassname: "NewName"
By calling the
Injectormapklass: MyClassas "NewName"
Once you've created your mappings you can ask the Injector for them:
Injectormapklass: MyClassmyInstance = InjectorgetInstanceOf "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:
Injectormapklass: MyClass# getting MyClass definition objectmyClass = InjectorgetClassOf "MyClass"# manually creating a new instance of MyClassmyInstance =
Unmaps a mapping.
Injectormapklass: MyClassInjectorunmap "MyClass"InjectorgetInstanceOf "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 mappingInjectormapmodulePath: "yourModulePath"asSingletonas"MySingleton"
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 Injectorinject:wheels: "Wheels"engine: "Engine"Injectormapklass: CarmyCar = InjectorgetInstanceOf "Car"consolelog myCarwheels # will print out an instance of the Wheels classconsolelog myCarengine # will print out an instance of the Engine class
This means that there is no need to require
Engine in the module file where Car is defined.
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.
The API is inspired by SwiftSuspenders which I used while developing Flashy things.