containable 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49be2a5c56c8ad8cd53ce41a6498bdb8aa47ab042cb123660dae6936ff4daade
-  data.tar.gz: dc75daed9d1f05881d54164e76e0e57a505a9d0699dc49bd1fde20f698dc6f45
+  metadata.gz: 7c5be0b5f9d940c754f77ded0f06992cb9d1dc13e45ec055ccde1a877fbe1782
+  data.tar.gz: 156d209e8b763fe0f995fa19bb709282537c2122c1a54e05c167e082f052055d
 SHA512:
-  metadata.gz: 4a67b2f11f343e08f9e351605e9721dbd302db977c4cd0ba6146235cca362e8b348be834f274c665669de8102659445519eb08f19ddaa54d948e09613d816b18
-  data.tar.gz: 3cf88215110cc8e90f84280df6bbcc764744454b8b58a4a9cbe53bd115a4d78824cff6a5dcb08927cacafa33fc062298fa8ccd38efacdc4d8a17e23c4d10fe45
+  metadata.gz: 8c6fa5e47492849f7d67121a0725dae9466f0bb79fdc4e014f8ba80daa02d68507b6efb3dc56a3d75fc87b0130d2b001127a78c709eb8a54b345bd8f09d14d53
+  data.tar.gz: 9a43d1dfce8ea6768240a48c4292b10b26abd984fa51c969dd68b6bd4a5170edaabac3a7dc716b9995559b592b844bb3bea4ab0a01b7aa5535a298c67dd2f757

data/README.adoc

@@ -110,7 +110,7 @@ module Container
 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:
+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 lazy register a dependency, use a block with parameters:
 
 [source,ruby]
 ----
@@ -155,7 +155,7 @@ 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.
+* `+: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 lazy 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.
 
@@ -188,8 +188,15 @@ module Container
   register :one, 1
 end
 
+# Single (preferred)
 Container.register :two, 2
+
+# Single (setter)
 Container[:three] = 3
+
+# Multiples.
+Container.register(:four, 4)
+         .register(:five, 5)
 ----
 
 With the above, a combination of `.register` and `.[]=` (setter) messages are used. While the latter is handy, the former is preferred for improved readability.
@@ -246,7 +253,7 @@ 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.
+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 lazy 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:
 
@@ -277,7 +284,65 @@ 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.
+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 lazy evaluate your closure while disabling default caching support.
+
+=== Merges
+
+You can merge dependencies from another container into your current container. Consider the following containers:
+
+[source,ruby]
+----
+module Primary
+  extend Containable
+
+  register :zero, 0
+end
+
+module Secondary
+  extend Containable
+
+  namespace :one do
+    register :two, 2
+  end
+
+  register :three, 3
+end
+
+module Other
+  extend Containable
+
+  register :four, 4
+end
+----
+
+With the above, this means you can do the following:
+
+[source,ruby]
+----
+# Merge a single dependency.
+Primary.merge Secondary, :three
+Primary[:three]  # 3
+
+# Merge multiple dependencies.
+Primary.merge Secondary, "one.two", :three
+Primary["one.two"]  # 2
+Primary[:three]     # 3
+
+# Merge with a namespace.
+Primary.merge Secondary, "one.two", :three, namespace: :top
+Primary["top.one.two"]  # 2
+Primary["top.three"]    # 3
+
+# Merge as fresh (normally, the default is cache).
+Primary.merge Secondary, "one.two", as: :fresh
+
+# Merge with repeated messages since it answers itself.
+Primary.merge(Secondary, :three)
+       .merge(Other, :four)
+
+Primary[:three]  # 3
+Primary[:four]   # 4
+----
 
 === Namespaces
 
@@ -316,6 +381,16 @@ Container["two.green"]     # "green"
 Container["three.silver"]  # "silver"
 ----
 
+You can also send multiple messages to create a namespace register a dependency:
+
+[source,]
+----
+Container.namespace(:one)
+         .register(:two, 2)
+----
+
+This is a convenience that should only be used in rare situations because defining your namespaces and associated dependencies using block syntax improves readability.
+
 === Enumeration
 
 Enumeration is possible but limited. Given the following:
@@ -407,7 +482,7 @@ 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:
+You can customize how the container registers and resolves dependencies by creating your own register and resolver classes. Both classes should inherit from either `Containable::Register` or `Containable::Resolver`. Internally, each subclass has access to the `dependencies` (i.e. `Concurrent::Hash`) object which stores the registered key and associated value (tuple). Example:
 
 [source,ruby]
 ----
@@ -417,9 +492,13 @@ You can customize how the container registers and resolves dependencies by creat
 }
 ----
 
-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.
+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. Definitely read the source code of each class to learn more.
+
+The following provides a few examples on how you can customize further.
 
-Here's how to use a custom register that doesn't care if you override an existing key.
+==== Registers
+
+Here's an example of a custom register that doesn't care if you override an existing key.
 
 [source,ruby]
 ----
@@ -441,6 +520,39 @@ end
 Container[:one]  # "override"
 ----
 
+Alternatively, you could specify which keys are allowed to be overwritten. Here's a modification to the above example that would make this possible:
+
+[source,ruby]
+----
+require "containable"
+require "refinements/array"
+
+class Register < Containable::Register
+  using Refinements::Array
+
+  def initialize(*, allowed_keys: %w[http logger], **)
+    super(*, **)
+    @allowed_keys = allowed_keys
+  end
+
+  protected
+
+  def check_duplicate key, namespaced_key
+    return if allowed_keys.include? namespaced_key
+
+    message = "Dependency is already registered: #{key.inspect}."
+
+    fail KeyError, message if dependencies.key? namespaced_key
+  end
+
+  private
+
+  attr_reader :allowed_keys
+end
+----
+
+==== Resolvers
+
 Here's an example with a custom resolver that only allows specific keys to be resolved:
 
 [source,ruby]
@@ -477,8 +589,6 @@ 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. 🚀

data/containable.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "containable"
-  spec.version = "2.2.0"
+  spec.version = "2.3.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/containable"

data/lib/containable/builder.rb

@@ -40,11 +40,22 @@ module Containable
         fail FrozenError, "Can't modify frozen container." if dependencies.frozen?
 
         target.call key, value, as:, &block
+        self
+      end
+    end
+
+    def define_merge target: register
+      define_method :merge do |other, *keys, namespace: nil, as: :cache|
+        target.merge(other, *keys, namespace:, as:)
+        self
       end
     end
 
     def define_namespace target = register
-      define_method(:namespace) { |name, &block| target.namespace name, &block }
+      define_method :namespace do |name, &block|
+        target.namespace name, &block
+        self
+      end
     end
 
     def define_resolve target = resolver
@@ -89,5 +100,17 @@ module Containable
     def define_frozen?
       define_method(:frozen?) { dependencies.frozen? }
     end
+
+    def define_stub
+      define_method :stub! do |**keywords|
+        require "containable/test"
+
+        extend Test
+
+        stub(**keywords)
+      end
+    end
+
+    def define_restore = define_method(:restore) { false }
   end
 end

data/lib/containable/register.rb

@@ -25,22 +25,31 @@ module Containable
       check_duplicate key, namespaced_key
       check_directive as
       dependencies[namespaced_key] = [block || value, as]
+      self
     end
 
     alias register call
 
+    def merge other, *keys, namespace: nil, as: :cache
+      keys.each { call [namespace, it].compact.join("."), other[it], as: }
+      self
+    end
+
     def namespace(name, &)
       keys.clear if depth.zero?
       keys.append name
       visit(&)
+      self
     end
 
-    private
+    protected
 
     attr_reader :dependencies, :separator, :directives
 
     attr_accessor :keys, :depth
 
+    def namespacify(key) = keys[..depth].append(key).join separator
+
     def check_duplicate key, namespaced_key
       message = "Dependency is already registered: #{key.inspect}."
 
@@ -54,6 +63,8 @@ module Containable
            %(Invalid directive: #{value.inspect}. Use #{directives.map(&:inspect).join " or "}.)
     end
 
+    private
+
     def visit &block
       increment
       instance_eval(&block) if block
@@ -64,7 +75,5 @@ module Containable
     def increment = self.depth += 1
 
     def decrement = self.depth -= 1
-
-    def namespacify(key) = keys[..depth].append(key).join separator
   end
 end

data/lib/containable/resolver.rb

@@ -18,7 +18,7 @@ module Containable
       process key, value, as
     end
 
-    private
+    protected
 
     attr_reader :dependencies
 

data/lib/containable.rb

@@ -12,14 +12,4 @@ module Containable
   end
 
   def self.[](register: Register, resolver: Resolver) = Builder.new(register:, resolver:)
-
-  def stub!(**)
-    require "containable/test"
-
-    extend Test
-
-    stub(**)
-  end
-
-  def restore = false
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: containable
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -90,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.12
 specification_version: 4
 summary: A thread-safe dependency injection container.
 test_files: []