:toc: macro :toclevels: 5 :figure-caption!:

:dependency_injection_containers_link: link:https://alchemists.io/articles/dependency_injection_containers[Dependency Injection Containers] :infusible_link: link:https://alchemists.io/projects/infusible[Infusible] :rspec_link: link:https://rspec.info[RSpec] :test_doubles_link: link:https://alchemists.io/articles/rspec_test_doubles[Test Doubles]

= Containable

This gem provides a thread-safe container for defining dependencies for reuse within your application. Coupled with the {infusible_link} gem, this powerful combination makes {dependency_injection_containers_link} simple to implement, test, and maintain.

toc::[]

== Features

• Provides a thread-safe dependency injection container.
• Encourages composition over inheritance.
• Includes test suite support so you can swap in {test_doubles_link} if desired.
• Compatible with {infusible_link}.

== Requirements

. link:https://www.ruby-lang.org[Ruby]. . A strong understanding of {dependency_injection_containers_link}.

== Setup

To install with security, run:

[source,bash]

💡 Skip this line if you already have the public certificate installed.

gem cert –add <(curl –compressed –location https://alchemists.io/gems.pem) gem install containable –trust-policy HighSecurity

To install without security, run:

[source,bash]

gem install containable

You can also add the gem directly to your project:

[source,bash]

bundle add containable

Once the gem is installed, you only need to require it:

[source,ruby]

require “containable”

== Usage

You can immediately use this gem by creating a container, extending the container with functionality from this gem, and register any/all dependencies as desired. Example:

[source,ruby]

require “containable”

module Container extend Containable

register :literal, 1 register(:echo) { |text| text } end

puts Container[:literal] # 1 puts Container[:echo].call “test” # “test”

The rest of this section will expand upon what is shown above.

=== Modules

Containers must be modules. For example, attempting to turn a class into a container is not allowed:

[source,ruby]

require “containable”

class Container extend Containable end

Only a module can be a container. (TypeError)

This is important since containers are only meant to hold your dependencies and nothing else. Modules are perfect for this.

=== Registration

The best way to register dependencies is when you define your container. The most basic is via a key/value pair:

[source,ruby]

require “containable”

module Container extend Containable

register :demo, 1 end

With the above, 1 (literal) will be associated with the :demo key. This is perfect for registering literals, constants, or any objects you immediately want evaluated or have a reference to. To lazily register a dependency, use a block with parameters:

[source,ruby]

require “containable”

module Container extend Containable

register(:demo) { Object.new } end

In this case the :demo key is associated with an instance of an object but the instance will only be initialized when resolved. Until the :demo key is resolved, the object is not instantiated and remains a closure (see xref:_resolution[Resolution]). You can also register procs, lambdas, and functions in the same manner:

[source,ruby]

require “containable”

function = proc { 3 }

module Container extend Containable

register :one, proc { 1 } register :two, -> { 2 } register(:three, &function) end

If you want closures to be cached or be fresh when resolved, use the as keyword. Example:

[source,ruby]

module Container extend Containable

register :one, as: :cache, proc { Object.new } register :two, as: :fresh, proc { Object.new } end

Use :cache and :fresh to direct how your closures will be resolved. Here’s what each does:

• +:cache+: Ensures the same object is answered each time the key is resolved. In the above example, this means the one dependency will always answer the same instance of an Object when resolved. This is default behavior so you don’t need to define this key and is only shown for explicit illustration purposes.
• +:fresh+: Ensures a new object is answered each time the key is resolved. In the above example, this means that the two dependency will always answer a different instance of an Object. You want to use this when you want to lazily resolve a dependency while still wanting a new instance each time.

💡 The as key is only applied when using a closure with no parameters and is ignored otherwise. This means you don’t need to supply this key when using literals.

As you can see, registration is quite flexible. That said, you only need to register a value or closure but not both. For example, if you register both a value and a closure you’ll get a warning (as printed as standard error output):

[source,ruby]

require “containable”

module Container extend Containable

register(:demo, “bogus”) { 1 } end

Registration of value is ignored since block takes precedence.

While providing the value isn’t harmful, it is unnecessary and wasteful. Instead, supply a value or a closure but not both.

You can also register dependencies after the fact since the container is open, by default. Example:

[source,ruby]

require “containable”

module Container extend Containable

register :one, 1 end

Container.register :two, 2 Container[:three] = 3

With the above, a combination of .register and .[]= (setter) messages are used. While the latter is handy, the former should be preferred for improved readability.

⚠️ Due to registration being so flexible, avoid nesting closures. Example:

[source,ruby]

No

register(:sanitizer) { -> content { Sanitize.fragment content, Sanitize::Config::BASIC } }

Yes

register :sanitizer, -> content { Sanitize.fragment content, Sanitize::Config::BASIC }

While the former will work, there is no benefit to nesting like this. The latter is more performant because you don’t have to unwrap the nested closure to achieve the same functionality since there is nothing to achieve from the lazy resolution of the sanitize functionality.

=== Resolution

There are two ways to resolve a dependency. Example:

[source,ruby]

Container[:demo] Container.resolve(:demo)

Both messages are acceptable but using .[] (getter) is recommended due to being succinct, requires less typing, and allows the container to feel like a Hash. Internally, when resolving a dependency, all keys are stored as strings which means you can use symbols or strings interchangeably except when using namespaces (more on this shortly). Example:

[source,ruby]

Container[:demo] # “example” Container[“demo”] # “example”

When discussing registration earlier, we saw you can register values and closures. A value can also be a closure but if a block is registered – in addition to the value – the block takes precedence.

What hasn’t been discussed is the kind of closure used when registering a value or block. If a closure has no parameters, then the closure will be resolved immediately when resolving the key for the first time. Any closure that takes one more more parameters will never be resolved which means you can call the closure directly when needed. To illustrate, consider the following:

[source,ruby]

require “containable”

module Container extend Containable

register :one, proc { 1 } register(:two) { |text| text.upcase } register :three, -> text { text.reverse } end

Container[:one] # 1 Container[:two] # #<Proc:0x000000012e9f8718 /demo:23> Container[:three] # #<Proc:0x000000012e9f8628 /demo:24 (lambda)>

With the above, you can see :one was immediately resolved to the value of 1 even though it was wrapped in a closure to begin with. This happened because the closure had no parameters so was safe to resolve. Again, this allows you to lazily resolve a dependency until you need it.

For keys :two and :three, we have a closure that has at least one parameter so remains a closure. This allows you to supply required arguments later. Here’s a closer look of using the :two and :three dependencies:

[source,ruby]

Container[:two].call “demo” # “DEMO” Container[:three].call “demo” # “omed”

In all of these situations, we have closures supplied as values or blocks but only closures with out parameters are resolved (i.e. unwrapped).

When using the as key, you can control if you get a cached or fresh instance. Example:

[source,ruby]

require “containable”

module Container extend Containable

register(:one) { Object.new } register(:two, as: :fresh) { Object.new } end

Container[:one] # #Object:0x000000012d135b90 Container[:one] # #Object:0x000000012d135b90 Container[:two] # #Object:0x000000012d237728 Container[:two] # #Object:0x000000012d2de550

Notice one always answers the same instance of an Object while two always answers a new instance of Object. By using :fresh, this allows you to lazily evaluate your closure while disabling default caching support.

=== Namespaces

As hinted at earlier, you can namespace your dependencies for improved organization. Example:

[source,ruby]

require “containable”

module Container extend Containable

namespace :one do register :blue, “blue” end

namespace :two do register :green, “green” end

namespace “three” do register :grey, “grey” register :silver, “silver” end end

There is no limit on the number of namespaces used or how deep they are nested. That said, this functionality should not be abused by sticking to either one or two levels of hierarchy. Anything more than that and you should reflect if your implementation is overly complex in order to refactor accordingly.

As with registration, you can use symbols, strings, or both for your namespaces since they are stored internally as strings. Namespaces are delimited by periods (.) so you must use a string for your key to resolve them. Example:

[source,ruby]

Container[“one.blue”] # “blue” Container[“two.green”] # “green” Container[“three.silver”] # “silver”

=== Enumeration

Enumeration is possible but limited. Given the following:

[source,ruby]

require “containable”

module Container extend Containable

register :one, 1 register :two, 2 end

…this means you can use all of the following messages:

[source,ruby]

Container.each { |key, value| puts “#{key}=#{value}” }

one=1

two=2

Container.each_key { |key| puts “Key: #{key}” }

Key: one

Key: two

Container.key? :one # false Container.key? “one” # true

Container.keys # [“one”, “two”]

=== Freezing

You can freeze your container and immediately check if it is frozen. Example:

[source,ruby]

require “containable”

module Container extend Containable

register :demo, “An example.” freeze end

Container.frozen? # true

You can also freeze your container after the fact by messaging .freeze directly on the container: Container.freeze. Once a container if frozen, registration of additional dependencies will result in an error:

[source,]

Container.register :another, “One more.” # Can’t modify frozen container. (FrozenError)

Once frozen, the container can’t be unfrozen unless you duplicate it (see below).

=== Duplicates

You can duplicate a container via the following (which will unfreeze the container if previously frozen):

[source,ruby]

container = Container.dup container.name

“containable”

Other = Container.dup Other.name # “Other”

A container, once duplicated, can be assigned to a local variable or a new constant. When assigning to a variable, the container will default to a temporary name of containable for identification.

=== Clones

Cloning a container is identical to duplicating a container except if the container is frozen then the clone will be frozen too. Example:

[source,ruby]

Container.freeze Container.clone.frozen? # true

=== Customization

You can customize how the container registers and resolves dependencies by creating your own register and resolver. Internally, both of these objects have access to and use dependencies (i.e. Concurrent::Hash) which stores the registered key and tuple. Example:

[source,ruby]

{ “one” => [1, :cache], “two” => [Proc:0x000000013f613a10, :fresh] }

Each tuple captures the dependency (value) and directive (i.e. :cache or :fresh). This allows you to have access to all information captured at registration. Below are a few examples on how to use and customize this information for your own purposes.

Here’s how to use a custom register that doesn’t care if you override an existing key.

[source,ruby]

require “containable”

class CustomRegister < Containable::Register def call(key, value = nil, as: :cache, &block) dependencies[namespacify(key)] = [block || value, as] end end

module Container extend Containable[register: CustomRegister]

register :one, 1 register :one, “override” end

Container[:one] # “override”

Here’s an example with a custom resolver that only allows specific keys to be resolved:

[source,ruby]

require “containable”

class CustomResolver < Containable::Resolver def initialize , allowed_keys: %i[one three] super() @allowed_keys = allowed_keys end

def call key fail KeyError, “Only use these keys: #{allowed_keys.inspect}” unless allowed_keys.include? key

super

end

private

attr_reader :allowed_keys end

module Container extend Containable[resolver: CustomResolver]

register :one, 1 register :two, 2 register :three, 3 end

Container[:one] # 1 Container[:two] # Only use these keys: [:one, :three] (KeyError) Container[:three] # 3

In both cases, you only need to inject your custom register or resolver when extending your container with Containable. Both of these classes should inherit from either Containable::Register or Containable::Resolver to customize behavior as you like. Definitely read the source code of both these classes to learn more.

=== Infusible

To fully leverage the power of this gem, check out {infusible_link}. You can get far with simple containers but if you want to supercharge your containers and make your architecture truly come alive then make sure to couple this gem with the {infusible_link} gem. 🚀

=== Tests

As you architect your implementation, you’ll want to swap out your original dependencies with {test_doubles_link} to simplify testing especially for situations, like making HTTP requests, with a fake. For demonstration purposes, I’ll assume you are using {rspec_link} but you can adapt for whatever testing framework you are using.

Consider the following:

[source,ruby]

module Container extend Containable

register :kernel, Kernel end

class Demo def initialize container: Container @container = container end

def speak(text) = kernel.puts text

private

attr_reader :container

def kernel = container[method] end

With our implementation defined, we can test as follows:

[source,ruby]

RSpec.describe Demo do subject(:demo) { Demo.new }

let(:kernel) { class_spy Kernel }

before { Container.stub! kernel: } after { Container.restore }

describe “#call” do it “prints message” do demo.speak “Hello” expect(kernel).to have_received(:puts).with(“Hello”) end end end

Notice there is little setup required to test the injected dependencies. Simply define what you want stubbed in your before and after blocks. That’s it!

While the above works great for a single spec, over time you’ll want to reduce duplicated setup by using a shared context. Here’s a rewrite of the above spec which significantly reduces duplication when needing to test multiple objects using the same dependencies:

[source,ruby]

spec/support/shared_contexts/application_container.rb

RSpec.shared_context “with application dependencies” do let(:kernel) { class_spy Kernel }

before { Container.stub! kernel: } after { Container.restore } end

[source,ruby]

spec/lib/demo_spec.rb

RSpec.describe Demo do subject(:demo) { Demo.new }

include_context “with application dependencies”

describe “#call” do it “prints message” do demo.speak “Hello” expect(kernel).to have_received(:puts).with(“Hello”) end end end

You’ll notice, in all of the examples, only two methods are used: .stub! and .restore. The first allows you supply keyword arguments of all dependencies you want stubbed. The last ensures your test suite is properly cleaned up so all stubs are removed and the container is restored to it’s original state. If you don’t restore your container after each spec, you’ll end up with stubs leaking across your specs and {rspec_link} will error to the same effect as well.

Always use .stub! to set your container up for testing. Once set up, you can add more stubs by using the .stub method (without the bang). So, to recap, use .stub! as a one-liner for setup and initial stubs then use .stub to add more stubs after the fact. Finally, ensure you restore (i.e. .restore) your container for proper cleanup after each test.

‼️ Use of .stub!, while convenient for testing, should – under no circumstances – be used in production code because it is meant for testing purposes only.

== Development

To contribute, run:

[source,bash]

git clone https://github.com/bkuhlmann/containable cd containable bin/setup

You can also use the IRB console for direct access to all objects:

[source,bash]

bin/console

== Tests

To test, run:

[source,bash]

bin/rake

== link:https://alchemists.io/policies/license[License]

== link:https://alchemists.io/policies/security[Security]

== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]

== link:https://alchemists.io/policies/contributions[Contributions]

== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]

== link:https://alchemists.io/projects/containable/versions[Versions]

== link:https://alchemists.io/community[Community]

== Credits

• Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].
• Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].