HardWire ⚡
A Compile-time Dependency Injection system for Crystal.
Installation
- Add the dependency to your
shard.yml
:
dependencies:
hardwire:
github: rwnx/hardwire
- Run
shards install
Usage
require "hardwire"
Hardwire is designed to operate inside a container object. Since the resolution is compile-time (Using Macros), normally this will be a module.
Creating a container 📦
# To create a new container, include `HardWire::Container`
# This will add the macros you need to register and resolve wiring
module Container
include HardWire::Container
# use transient/singleton to wire different lifecycles
# singleton dependencies will be memoized
# dependencies for the constructor will be resolved from the constructor automatically
transient Dependency
singleton NeedsDependency
scoped Webservice
# you can also register dependencies with a block instead of inspecting the constructor
# Your block MUST return an instance of the class you are registering
singleton NeedsDependency {
NeedsDependency.new( self.resolve Dependency )
}
end
Hardwire tries to operate with minimal modifications to other classes (unless required). "simple" classes, e.g.
- Have a single constructor
- Have unique dependencies/do not require tags
If your classes match this signature, you can wire up in the container without adding anything to the classes.
For everything else, there's:
Multiple Constructors 🚧
Hardwire needs to know which constuctor function to use.
Annotate your "Injectable" constructor with the Hardwire::Inject annotation.
class MultipleInits
@[HardWire::Inject]
def initialize(input: String)
# register will inspect this method's arguments
# [...]
end
def initialize
# will not be used for injection
# [...]
end
end
Tags 🏷
To differentiate between registrations of the same type, use the HardWire::Tags annotation. Tags allow you to attach additional metadata to the signature. Tags themselves are string-based, simple identifiers (/\w+/) that allow you to resolve a different registration of the same class.
# [...]
# registering a transient dependency with tag "secret"
transient String, "secret" {
"a secret string"
}
# registering a singleton
# When no tags are set, it is considered the "default" registration
singleton DbService
# registering a different singleton with a tag
singleton DbService, "primary"
# Resolving Dependencies
class Resolving
@[Hardwire::Tags(input: "secret", primary_db: "primary")]
def initialize(input : String, primary_db : DbService, default_db : DbService)
end
end
Lifecycles ♽
There are 3 lifecycles available for registrations:
- Singleton: The dependency is instantiated once for the lifetime of the application
- Scoped: the dependency instantiated once for each created scope and destroyed when the scope is garbage-collected
- Transient: the dependency is instatiated each time it is resolved
Scopes 🔭
To managed scoped instances, you should create a scope object with the .scope
macro.
# This example will init a database DatabaseConnection for each http request
# but all the databases will recieve the same instance of config (singleton)
# the ScopedLogging dependency will also be instantiated once for each scope resolution
require "kemal"
class Config; end
class ScopedLogging; end
class DatabaseConnection
def initialize(@config : Config, @logging : ScopedLogging)
end
end
module Container
include HardWire::Container
singleton Config
scoped ScopedLogging
scoped DatabaseConnection
end
get "/" do
# create a unique scope
scope = Container.scope
logger = scope.resolve ScopedLogging
db = scope.resolve DatabaseConnection
db.get_some_data
logger.log("I share a logger with the database in scope!")
end
Kemal.run
Resolving Manually 🔨
You can resolve dependencies manually using the .resolve
macro. This allows you to resolve dependencies manually with the tag string.
module Container
include HardWire::Container
transient SecretService, "primary"
singleton DatabaseThing
end
service = Container.resolve SecretService, "primary"
db = Container.resolve DatabaseThing
Runtime Interrogation 👀
Hardwire can tell you information about the registrations at runtime, but the dependencies are HardWired (See what I did there?), so they can't be changed.
module Container
include HardWire::Container
singleton DbService
end
Container.registered?(DbService) # true
Container.registered?(DbService, "tagged") # false
Container.registered?(String) # false
Contributing
- Fork it (https://github.com/rwnx/hardwire/fork)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Contributors
- rwnx - creator and maintainer