Containable

This gem provides a thread-safe container for defining dependencies for reuse within your application. Coupled with the Infusible gem, this powerful combination makes Dependency Injection Containers simple to implement, test, and maintain.

Table of Contents

Features
Requirements
Setup
Usage
- Modules
- Registration
- Resolution
- Namespaces
- Enumeration
- Freezing
- Duplicates
- Clones
- Customization
- Infusible
- Tests
Development
Tests
License
Security
Code of Conduct
Contributions
Developer Certificate of Origin
Versions
Community
Credits

Features

Provides a thread-safe dependency injection container.
Encourages composition over inheritance.
Includes test suite support so you can swap in Test Doubles if desired.
Compatible with Infusible.

Requirements

Ruby.
A strong understanding of Dependency Injection Containers.

Setup

To install with security, run:

# 💡 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:

gem install containable

You can also add the gem directly to your project:

bundle add containable

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

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:

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:

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:

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:

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 Resolution). You can also register procs, lambdas, and functions in the same manner:

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:

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):

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:

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:

# 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:

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:

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:

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:

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:

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:

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:

Container["one.blue"]      # "blue"
Container["two.green"]     # "green"
Container["three.silver"]  # "silver"

Enumeration

Enumeration is possible but limited. Given the following:

require "containable"

module Container
  extend Containable

  register :one, 1
  register :two, 2
end

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

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:

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:

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):

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:

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:

{
  "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.

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:

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. 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 gem. 🚀

Tests

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

Consider the following:

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:

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:

# 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

# 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 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:

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

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

bin/console

Tests

To test, run:

bin/rake

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

Runtime

Containable

Features

Requirements

Setup

Usage

Modules

Registration

Resolution

Namespaces

Enumeration

Freezing

Duplicates

Clones

Customization

Infusible

Tests

Development

Tests

Credits