dry-core 0.7.1 → 1.0.1

data/lib/dry/core/container/mixin.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require "concurrent/hash"
+require "dry/core/constants"
+
+module Dry
+  module Core
+    class Container
+      include Dry::Core::Constants
+
+      # @api public
+      Error = Class.new(StandardError)
+
+      # Error raised when key is not defined in the registry
+      #
+      # @api public
+      KeyError = Class.new(::KeyError)
+
+      if defined?(DidYouMean::KeyErrorChecker)
+        DidYouMean.correct_error(KeyError, DidYouMean::KeyErrorChecker)
+      end
+
+      # Mixin to expose Inversion of Control (IoC) container behaviour
+      #
+      # @example
+      #
+      #   class MyClass
+      #     extend Dry::Core::Container::Mixin
+      #   end
+      #
+      #   MyClass.register(:item, 'item')
+      #   MyClass.resolve(:item)
+      #   => 'item'
+      #
+      #   class MyObject
+      #     include Dry::Core::Container::Mixin
+      #   end
+      #
+      #   container = MyObject.new
+      #   container.register(:item, 'item')
+      #   container.resolve(:item)
+      #   => 'item'
+      #
+      # @api public
+      #
+      # rubocop:disable Metrics/ModuleLength
+      module Mixin
+        PREFIX_NAMESPACE = lambda do |namespace, key, config|
+          [namespace, key].join(config.namespace_separator)
+        end
+
+        # @private
+        def self.extended(base)
+          hooks_mod = ::Module.new do
+            def inherited(subclass)
+              subclass.instance_variable_set(:@_container, @_container.dup)
+              super
+            end
+          end
+
+          base.class_eval do
+            extend Configuration
+            extend hooks_mod
+
+            @_container = ::Concurrent::Hash.new
+          end
+        end
+
+        # @private
+        module Initializer
+          def initialize(*args, &block)
+            @_container = ::Concurrent::Hash.new
+            super
+          end
+        end
+
+        # @private
+        def self.included(base)
+          base.class_eval do
+            extend Configuration
+            prepend Initializer
+
+            def config
+              self.class.config
+            end
+          end
+        end
+
+        # Register an item with the container to be resolved later
+        #
+        # @param [Mixed] key
+        #   The key to register the container item with (used to resolve)
+        # @param [Mixed] contents
+        #   The item to register with the container (if no block given)
+        # @param [Hash] options
+        #   Options to pass to the registry when registering the item
+        # @yield
+        #   If a block is given, contents will be ignored and the block
+        #   will be registered instead
+        #
+        # @return [Dry::Core::Container::Mixin] self
+        #
+        # @api public
+        def register(key, contents = nil, options = EMPTY_HASH, &block)
+          if block_given?
+            item = block
+            options = contents if contents.is_a?(::Hash)
+          else
+            item = contents
+          end
+
+          config.registry.call(_container, key, item, options)
+
+          self
+        rescue FrozenError
+          raise FrozenError,
+                "can't modify frozen #{self.class} (when attempting to register '#{key}')"
+        end
+
+        # Resolve an item from the container
+        #
+        # @param [Mixed] key
+        #   The key for the item you wish to resolve
+        # @yield
+        #   Fallback block to call when a key is missing. Its result will be returned
+        # @yieldparam [Mixed] key Missing key
+        #
+        # @return [Mixed]
+        #
+        # @api public
+        def resolve(key, &block)
+          config.resolver.call(_container, key, &block)
+        end
+
+        # Resolve an item from the container
+        #
+        # @param [Mixed] key
+        #   The key for the item you wish to resolve
+        #
+        # @return [Mixed]
+        #
+        # @api public
+        # @see Dry::Core::Container::Mixin#resolve
+        def [](key)
+          resolve(key)
+        end
+
+        # Merge in the items of the other container
+        #
+        # @param [Dry::Core::Container] other
+        #   The other container to merge in
+        # @param [Symbol, nil] namespace
+        #   Namespace to prefix other container items with, defaults to nil
+        #
+        # @return [Dry::Core::Container::Mixin] self
+        #
+        # @api public
+        def merge(other, namespace: nil, &block)
+          if namespace
+            _container.merge!(
+              other._container.each_with_object(::Concurrent::Hash.new) { |(key, item), hsh|
+                hsh[PREFIX_NAMESPACE.call(namespace, key, config)] = item
+              },
+              &block
+            )
+          else
+            _container.merge!(other._container, &block)
+          end
+
+          self
+        end
+
+        # Check whether an item is registered under the given key
+        #
+        # @param [Mixed] key
+        #   The key you wish to check for registration with
+        #
+        # @return [Bool]
+        #
+        # @api public
+        def key?(key)
+          config.resolver.key?(_container, key)
+        end
+
+        # An array of registered names for the container
+        #
+        # @return [Array<String>]
+        #
+        # @api public
+        def keys
+          config.resolver.keys(_container)
+        end
+
+        # Calls block once for each key in container, passing the key as a parameter.
+        #
+        # If no block is given, an enumerator is returned instead.
+        #
+        # @return [Dry::Core::Container::Mixin] self
+        #
+        # @api public
+        def each_key(&block)
+          config.resolver.each_key(_container, &block)
+          self
+        end
+
+        # Calls block once for each key/value pair in the container, passing the key and
+        # the registered item parameters.
+        #
+        # If no block is given, an enumerator is returned instead.
+        #
+        # @return [Enumerator]
+        #
+        # @api public
+        #
+        # @note In discussions with other developers, it was felt that being able to iterate
+        #       over not just the registered keys, but to see what was registered would be
+        #       very helpful. This is a step toward doing that.
+        def each(&block)
+          config.resolver.each(_container, &block)
+        end
+
+        # Decorates an item from the container with specified decorator
+        #
+        # @return [Dry::Core::Container::Mixin] self
+        #
+        # @api public
+        def decorate(key, with: nil, &block)
+          key = key.to_s
+          original = _container.delete(key) do
+            raise KeyError, "Nothing registered with the key #{key.inspect}"
+          end
+
+          if with.is_a?(Class)
+            decorator = with.method(:new)
+          elsif block.nil? && !with.respond_to?(:call)
+            raise Error, "Decorator needs to be a Class, block, or respond to the `call` method"
+          else
+            decorator = with || block
+          end
+
+          _container[key] = original.map(decorator)
+          self
+        end
+
+        # Evaluate block and register items in namespace
+        #
+        # @param [Mixed] namespace
+        #   The namespace to register items in
+        #
+        # @return [Dry::Core::Container::Mixin] self
+        #
+        # @api public
+        def namespace(namespace, &block)
+          ::Dry::Core::Container::NamespaceDSL.new(
+            self,
+            namespace,
+            config.namespace_separator,
+            &block
+          )
+
+          self
+        end
+
+        # Import a namespace
+        #
+        # @param [Dry::Core::Container::Namespace] namespace
+        #   The namespace to import
+        #
+        # @return [Dry::Core::Container::Mixin] self
+        #
+        # @api public
+        def import(namespace)
+          namespace(namespace.name, &namespace.block)
+
+          self
+        end
+
+        # Freeze the container. Nothing can be registered after freezing
+        #
+        # @api public
+        def freeze
+          super
+          _container.freeze
+          self
+        end
+
+        # @private no, really
+        def _container
+          @_container
+        end
+
+        # @api public
+        def dup
+          copy = super
+          copy.instance_variable_set(:@_container, _container.dup)
+          copy
+        end
+
+        # @api public
+        def clone
+          copy = super
+          unless copy.frozen?
+            copy.instance_variable_set(:@_container, _container.dup)
+          end
+          copy
+        end
+      end
+      # rubocop:enable Metrics/ModuleLength
+    end
+  end
+end

data/lib/dry/core/container/namespace.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Dry
+  module Core
+    class Container
+      # Create a namespace to be imported
+      #
+      # @example
+      #
+      #   ns = Dry::Core::Container::Namespace.new('name') do
+      #     register('item', 'item')
+      #   end
+      #
+      #   container = Dry::Core::Container.new
+      #
+      #   container.import(ns)
+      #
+      #   container.resolve('name.item')
+      #   => 'item'
+      #
+      #
+      # @api public
+      class Namespace
+        # @return [Mixed] The namespace (name)
+        attr_reader :name
+
+        # @return [Proc] The block to be executed when the namespace is imported
+        attr_reader :block
+
+        # Create a new namespace
+        #
+        # @param [Mixed] name
+        #   The name of the namespace
+        # @yield
+        #   The block to evaluate when the namespace is imported
+        #
+        # @return [Dry::Core::Container::Namespace]
+        #
+        # @api public
+        def initialize(name, &block)
+          @name = name
+          @block = block
+        end
+      end
+    end
+  end
+end

data/lib/dry/core/container/namespace_dsl.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Dry
+  module Core
+    class Container
+      # @api private
+      class NamespaceDSL < ::SimpleDelegator
+        # DSL for defining namespaces
+        #
+        # @param [Dry::Core::Container::Mixin] container
+        #   The container
+        # @param [String] namespace
+        #   The namespace (name)
+        # @param [String] namespace_separator
+        #   The namespace separator
+        # @yield
+        #   The block to evaluate to define the namespace
+        #
+        # @return [Mixed]
+        #
+        # @api private
+        def initialize(container, namespace, namespace_separator, &block)
+          @namespace = namespace
+          @namespace_separator = namespace_separator
+
+          super(container)
+
+          if block.arity.zero?
+            instance_eval(&block)
+          else
+            yield self
+          end
+        end
+
+        def register(key, *args, &block)
+          super(namespaced(key), *args, &block)
+        end
+
+        def namespace(namespace, &block)
+          super(namespaced(namespace), &block)
+        end
+
+        def import(namespace)
+          namespace(namespace.name, &namespace.block)
+
+          self
+        end
+
+        def resolve(key)
+          super(namespaced(key))
+        end
+
+        private
+
+        def namespaced(key)
+          [@namespace, key].join(@namespace_separator)
+        end
+      end
+    end
+  end
+end

data/lib/dry/core/container/registry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Dry
+  module Core
+    class Container
+      # Default registry for registering items with the container
+      #
+      # @api public
+      class Registry
+        # @private
+        def initialize
+          @_mutex = ::Mutex.new
+        end
+
+        # Register an item with the container to be resolved later
+        #
+        # @param [Concurrent::Hash] container
+        #   The container
+        # @param [Mixed] key
+        #   The key to register the container item with (used to resolve)
+        # @param [Mixed] item
+        #   The item to register with the container
+        # @param [Hash] options
+        # @option options [Symbol] :call
+        #   Whether the item should be called when resolved
+        #
+        # @raise [Dry::Core::Container::KeyError]
+        #   If an item is already registered with the given key
+        #
+        # @return [Mixed]
+        #
+        # @api public
+        def call(container, key, item, options)
+          key = key.to_s.dup.freeze
+
+          @_mutex.synchronize do
+            if container.key?(key)
+              raise KeyError, "There is already an item registered with the key #{key.inspect}"
+            end
+
+            container[key] = factory.call(item, options)
+          end
+        end
+
+        # @api private
+        def factory
+          @factory ||= Container::Item::Factory.new
+        end
+      end
+    end
+  end
+end

data/lib/dry/core/container/resolver.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Dry
+  module Core
+    class Container
+      # Default resolver for resolving items from container
+      #
+      # @api public
+      class Resolver
+        # Resolve an item from the container
+        #
+        # @param [Concurrent::Hash] container
+        #   The container
+        # @param [Mixed] key
+        #   The key for the item you wish to resolve
+        # @yield
+        #   Fallback block to call when a key is missing. Its result will be returned
+        # @yieldparam [Mixed] key Missing key
+        #
+        # @raise [KeyError]
+        #   If the given key is not registered with the container (and no block provided)
+        #
+        #
+        # @return [Mixed]
+        #
+        # @api public
+        def call(container, key)
+          item = container.fetch(key.to_s) do
+            if block_given?
+              return yield(key)
+            else
+              raise KeyError.new(%(key not found: "#{key}"), key: key.to_s, receiver: container)
+            end
+          end
+
+          item.call
+        end
+
+        # Check whether an items is registered under the given key
+        #
+        # @param [Concurrent::Hash] container
+        #   The container
+        # @param [Mixed] key
+        #   The key you wish to check for registration with
+        #
+        # @return [Bool]
+        #
+        # @api public
+        def key?(container, key)
+          container.key?(key.to_s)
+        end
+
+        # An array of registered names for the container
+        #
+        # @return [Array]
+        #
+        # @api public
+        def keys(container)
+          container.keys
+        end
+
+        # Calls block once for each key in container, passing the key as a parameter.
+        #
+        # If no block is given, an enumerator is returned instead.
+        #
+        # @return Hash
+        #
+        # @api public
+        def each_key(container, &block)
+          container.each_key(&block)
+        end
+
+        # Calls block once for each key in container, passing the key and
+        # the registered item parameters.
+        #
+        # If no block is given, an enumerator is returned instead.
+        #
+        # @return Key, Value
+        #
+        # @api public
+        # @note In discussions with other developers, it was felt that being able
+        #       to iterate over not just the registered keys, but to see what was
+        #       registered would be very helpful. This is a step toward doing that.
+        def each(container, &block)
+          container.map { |key, value| [key, value.call] }.each(&block)
+        end
+      end
+    end
+  end
+end

data/lib/dry/core/container/stub.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Dry
+  module Core
+    class Container
+      module Stub
+        # Overrides resolve to look into stubbed keys first
+        #
+        # @api public
+        def resolve(key)
+          _stubs.fetch(key.to_s) { super }
+        end
+
+        # Add a stub to the container
+        def stub(key, value, &block)
+          unless key?(key)
+            raise ArgumentError, "cannot stub #{key.to_s.inspect} - no such key in container"
+          end
+
+          _stubs[key.to_s] = value
+
+          if block
+            yield
+            unstub(key)
+          end
+
+          self
+        end
+
+        # Remove stubbed keys from the container
+        def unstub(*keys)
+          keys = _stubs.keys if keys.empty?
+          keys.each { |key| _stubs.delete(key.to_s) }
+        end
+
+        # Stubs have already been enabled turning this into a noop
+        def enable_stubs!
+          # DO NOTHING
+        end
+
+        private
+
+        # Stubs container
+        def _stubs
+          @_stubs ||= {}
+        end
+      end
+
+      module Mixin
+        # Enable stubbing functionality into the current container
+        def enable_stubs!
+          extend ::Dry::Core::Container::Stub
+        end
+      end
+    end
+  end
+end

data/lib/dry/core/container.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Dry
+  module Core
+    # Thread-safe object registry
+    #
+    # @example
+    #
+    #   container = Dry::Core::Container.new
+    #   container.register(:item, 'item')
+    #   container.resolve(:item)
+    #   => 'item'
+    #
+    #   container.register(:item1, -> { 'item' })
+    #   container.resolve(:item1)
+    #   => 'item'
+    #
+    #   container.register(:item2, -> { 'item' }, call: false)
+    #   container.resolve(:item2)
+    #   => #<Proc:0x007f33b169e998@(irb):10 (lambda)>
+    #
+    # @api public
+    class Container
+      include Container::Mixin
+    end
+  end
+end

data/lib/dry/core/deprecations.rb

@@ -4,7 +4,7 @@ require "logger"
 
 module Dry
   module Core
-    # An extension for issueing warnings on using deprecated methods.
+    # An extension for issuing warnings on using deprecated methods.
     #
     # @example
     #

data/lib/dry/core/equalizer.rb

@@ -1,17 +1,6 @@
 # frozen_string_literal: true
 
 module Dry
-  # Build an equalizer module for the inclusion in other class
-  #
-  # ## Credits
-  #
-  # Equalizer has been originally imported from the equalizer gem created by Dan Kubb
-  #
-  # @api public
-  def self.Equalizer(*keys, **options)
-    Dry::Core::Equalizer.new(*keys, **options)
-  end
-
   module Core
     # Define equality, equivalence and inspection methods
     class Equalizer < ::Module
@@ -149,4 +138,19 @@ module Dry
       end
     end
   end
+
+  # Old modules that depend on dry/core/equalizer may miss
+  # this method if dry/core is not required explicitly
+  unless singleton_class.method_defined?(:Equalizer)
+    # Build an equalizer module for the inclusion in other class
+    #
+    # ## Credits
+    #
+    # Equalizer has been originally imported from the equalizer gem created by Dan Kubb
+    #
+    # @api public
+    def self.Equalizer(*keys, **options)
+      Dry::Core::Equalizer.new(*keys, **options)
+    end
+  end
 end

data/lib/dry/core/errors.rb

@@ -2,7 +2,7 @@
 
 module Dry
   module Core
-    class InvalidClassAttributeValue < StandardError
+    class InvalidClassAttributeValueError < StandardError
       def initialize(name, value)
         super(
           "Value #{value.inspect} is invalid for class attribute #{name.inspect}"