containable 0.6.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e00775146489a9efd09bc8bdc42f66e88a68a7c6926a4f607577a7803bd931db
-  data.tar.gz: 4d4598a1075e508373691657378c447f8f026a7d6175262d350a4c5a13a06a90
+  metadata.gz: 14490c83a49633550ef45044720f8f42dee80bbcc8cca3824347974d5583c8c9
+  data.tar.gz: dc892f9dfd4257d49401209d0aca17e8cc17b7c6216d024773d9736b66d2d7fb
 SHA512:
-  metadata.gz: b3ecc1217f077b5271888013c127509e5d529175888f2c0d68022ef86afb1fed9468166c232668ca25decf5ee81f85bf5cd730b2869c6159466f5fca14ebff68
-  data.tar.gz: 9c153e67b57f12027c811de578daa9587fd54f84fe4d1b043ed558f1127a2aa57fe520e0416db1d5eecf62e87454387c670061a79538a6536a4ae1af61c080cf
+  metadata.gz: 5526cfe5e1816ecc3fc76e7ba0f24d7d88e95a74e2323c8bef12ee0eb609eef75b81a73c263edcd758d725cf4e8e3447dbb747051609d7c8e1a531deb5d6b84b
+  data.tar.gz: 5fbc220cb0933840900e8e8094748c9b323ce6fa8a180e398177e29cafad1a166d9406adcd329fac227632f0740aa484002a2a49f254dbd179997c5dc873e40f

data/README.adoc

@@ -97,7 +97,7 @@ This is important since containers are only meant to hold your dependencies and
 
 === Registration
 
-As shown above, the best way to register dependencies is as you define your container. The most basic is via a key/value pair:
+The best way to register dependencies is when you define your container. The most basic is via a key/value pair:
 
 [source,ruby]
 ----
@@ -123,7 +123,7 @@ module Container
 end
 ----
 
-In this case the `:demo` key is associated with an instance of an object but the instance _will only be realized when first resolved_. Until the `:demo` key is resolved, the object is not instantiated and remains a closure (more on resolving dependencies shortly). You can also register procs, lambdas, and functions in the same manner:
+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]
 ----
@@ -140,7 +140,26 @@ module Container
 end
 ----
 
-As you can see, registration is quite flexible. That said, you only register either 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):
+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]
 ----
@@ -173,9 +192,9 @@ 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.
+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 flexible to begin with, avoid nesting closures. Example:
+⚠️ Due to registration being so flexible, avoid nesting closures. Example:
 
 [source,ruby]
 ----
@@ -190,7 +209,7 @@ While the former will work, there is no benefit to nesting like this. The latter
 
 === Resolution
 
-Now that you understand how to register dependencies, we can talk about resolving them. There are two ways to resolve a dependency. Example:
+There are two ways to resolve a dependency. Example:
 
 [source,ruby]
 ----
@@ -198,7 +217,7 @@ 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 more 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:
+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]
 ----
@@ -206,9 +225,9 @@ 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 over the value.
+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 takes _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:
+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]
 ----
@@ -222,14 +241,14 @@ module Container
   register :three, -> text { text.reverse }
 end
 
-Container[:one]    # 1
-Container[:two]    # #<Proc:0x000000012e9f8718 /demo:23>
-Container[:three]  # #<Proc:0x000000012e9f8628 /demo:24 (lambda)>
+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 so you can supply the arguments you need later. Here's a closer look of using the `:two` and `:three` dependencies:
+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]
 ----
@@ -239,6 +258,27 @@ 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:
@@ -278,7 +318,7 @@ Container["three.silver"]  # "silver"
 
 === Enumeration
 
-Limited enumeration of your container is possible. Given the following:
+Enumeration is possible but limited. Given the following:
 
 [source,ruby]
 ----
@@ -353,7 +393,7 @@ Other.name
 # "Other"
 ----
 
-As you can see a container, once duplicated, can be assigned to a local variable or a new constant. When assigning to a variable, the container will use a temporary name of `containable` for identification.
+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
 
@@ -367,14 +407,28 @@ Container.clone.frozen?  # true
 
 === Customization
 
-You can customize how the container registers and resolves dependencies by creating your own register and resolver objects. For example, here's how to use a custom register that doesn't care if you override an existing key.
+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, &block) = dependencies[namespacify(key)] = block || value
+  def call(key, value = nil, as: :cache, &block)
+    dependencies[namespacify(key)] = [block || value, as]
+  end
 end
 
 module Container
@@ -387,7 +441,7 @@ end
 Container[:one]  # "override"
 ----
 
-...and here's an example with a custom resolver that only allows specific keys to be resolved:
+Here's an example with a custom resolver that only allows specific keys to be resolved:
 
 [source,ruby]
 ----
@@ -423,7 +477,7 @@ 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 check out the source code of both these classes to learn more and customize as desired.
+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
 
@@ -515,7 +569,7 @@ 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 setup, 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.
+_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.
 

data/containable.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "containable"
-  spec.version = "0.6.0"
+  spec.version = "1.1.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/containable"
@@ -22,8 +22,8 @@ Gem::Specification.new do |spec|
   spec.signing_key = Gem.default_key_path
   spec.cert_chain = [Gem.default_cert_path]
 
-  spec.required_ruby_version = ">= 3.3", "<= 3.4"
-  spec.add_dependency "concurrent-ruby", "~> 1.2"
+  spec.required_ruby_version = "~> 3.4"
+  spec.add_dependency "concurrent-ruby", "~> 1.3"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
   spec.files = Dir["*.gemspec", "lib/**/*"]

data/lib/containable/builder.rb

@@ -36,10 +36,10 @@ module Containable
     end
 
     def define_register target = register
-      define_method :register do |key, value = nil, &block|
+      define_method :register do |key, value = nil, as: :cache, &block|
         fail FrozenError, "Can't modify frozen container." if dependencies.frozen?
 
-        target.call key, value, &block
+        target.call key, value, as:, &block
       end
     end
 
@@ -52,7 +52,7 @@ module Containable
     end
 
     def define_each target = dependencies
-      define_method(:each) { |&block| target.each(&block) }
+      define_method(:each) { |&block| target.transform_values(&:first).each(&block) }
     end
 
     def define_each_key target = dependencies
@@ -76,7 +76,6 @@ module Containable
     def define_dup target = self.class,
                    local_register: register.class,
                    local_resolver: resolver.class
-
       define_method :dup do
         instance = target.new dependencies.dup, register: local_register, resolver: local_resolver
         Module.new.set_temporary_name("containable").extend instance

data/lib/containable/register.rb

@@ -3,25 +3,28 @@
 require "concurrent/hash"
 
 module Containable
+  # :reek:TooManyInstanceVariables
   # Registers dependencies for future evaluation.
   class Register
     SEPARATOR = "."
+    DIRECTIVES = %i[cache fresh].freeze
 
-    def initialize dependencies = Concurrent::Hash.new, separator: SEPARATOR
+    def initialize dependencies = Concurrent::Hash.new, separator: SEPARATOR, directives: DIRECTIVES
       @dependencies = dependencies
       @separator = separator
+      @directives = directives
       @keys = []
       @depth = 0
     end
 
-    def call key, value = nil, &block
-      namespaced_key = namespacify key
-      message = "Dependency is already registered: #{key.inspect}."
-
+    def call key, value = nil, as: :cache, &block
       warn "Registration of value is ignored since block takes precedence." if value && block
-      fail KeyError, message if dependencies.key? namespaced_key
 
-      dependencies[namespaced_key] = block || value
+      namespaced_key = namespacify key
+
+      check_duplicate key, namespaced_key
+      check_directive as
+      dependencies[namespaced_key] = [block || value, as]
     end
 
     alias register call
@@ -34,10 +37,23 @@ module Containable
 
     private
 
-    attr_reader :dependencies, :separator
+    attr_reader :dependencies, :separator, :directives
 
     attr_accessor :keys, :depth
 
+    def check_duplicate key, namespaced_key
+      message = "Dependency is already registered: #{key.inspect}."
+
+      fail KeyError, message if dependencies.key? namespaced_key
+    end
+
+    def check_directive value
+      return if directives.include? value
+
+      fail ArgumentError,
+           %(Invalid directive: #{value.inspect}. Use #{directives.map(&:inspect).join " or "}.)
+    end
+
     def visit &block
       increment
       instance_eval(&block) if block

data/lib/containable/resolver.rb

@@ -10,17 +10,29 @@ module Containable
     end
 
     def call key
-      normalized_key = key.to_s
+      tuple = fetch key
+      value, as = tuple
 
-      value = dependencies.fetch normalized_key do
-        fail KeyError, "Unable to resolve dependency: #{key.inspect}."
-      end
+      return value unless value.is_a?(Proc) && value.arity.zero?
 
-      value.is_a?(Proc) && value.arity.zero? ? dependencies[normalized_key] = value.call : value
+      process key, value, as
     end
 
     private
 
     attr_reader :dependencies
+
+    def fetch key
+      dependencies.fetch key.to_s do
+        fail KeyError, "Unable to resolve dependency: #{key.inspect}."
+      end
+    end
+
+    def process key, closure, directive
+      value = closure.call
+      dependencies[key.to_s] = [value, directive] if directive == :cache
+
+      value
+    end
   end
 end

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: containable
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -35,7 +34,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-11-09 00:00:00.000000000 Z
+date: 2025-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -43,15 +42,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
-description:
+        version: '1.3'
 email:
 - brooke@alchemists.io
 executables: []
@@ -79,16 +77,12 @@ metadata:
   label: Containable
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/bkuhlmann/containable
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
-    - !ruby/object:Gem::Version
-      version: '3.3'
-  - - "<="
+  - - "~>"
     - !ruby/object:Gem::Version
       version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
@@ -97,8 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 3.6.3
 specification_version: 4
 summary: A thread-safe dependency injection container.
 test_files: []