dry-system 0.19.2 → 0.23.0

data/lib/dry/system/config/component_dir.rb

@@ -1,9 +1,15 @@
+# frozen_string_literal: true
+
 require "dry/configurable"
+require "dry/core/deprecations"
+require "dry/system/constants"
 require "dry/system/loader"
+require_relative "namespaces"
 
 module Dry
   module System
     module Config
+      # @api public
       class ComponentDir
         include Dry::Configurable
 
@@ -14,7 +20,7 @@ module Dry
         #   Sets the auto-registration policy for the component dir.
         #
         #   This may be a simple boolean to enable or disable auto-registration for all
-        #   components, or a proc accepting a `Dry::Sytem::Component` and returning a
+        #   components, or a proc accepting a {Dry::System::Component} and returning a
         #   boolean to configure auto-registration on a per-component basis
         #
         #   Defaults to `true`.
@@ -27,11 +33,12 @@ module Dry
         #
         #   @example
         #     dir.auto_register = proc do |component|
-        #       !component.start_with?("entities")
+        #       !component.identifier.start_with?("entities")
         #     end
         #
         #   @see auto_register
         #   @see Component
+        #   @api public
         #
         # @!method auto_register
         #
@@ -40,68 +47,61 @@ module Dry
         #   @return [Boolean, Proc] the configured policy
         #
         #   @see auto_register=
-        setting :auto_register, true
+        #   @api public
+        setting :auto_register, default: true
 
-        # @!method add_to_load_path=(policy)
-        #
-        #   Sets whether the dir should be added to the `$LOAD_PATH` after the container
-        #   is configured.
-        #
-        #   Defaults to `true`. This may need to be set to `false` when using a class
-        #   autoloading system.
+        # @!method instance=(instance_proc)
         #
-        #   @param policy [Boolean]
-        #   @return [Boolean]
+        #   Sets a proc used to return the instance of any component within the component
+        #   dir.
         #
-        #   @see add_to_load_path
-        #   @see Container.configure
+        #   This proc should accept a {Dry::System::Component} and return the object to
+        #   serve as the component's instance.
         #
-        # @!method add_to_load_path
-        #
-        #   Returns the configured value.
-        #
-        #   @return [Boolean]
-        #
-        #   @see add_to_load_path=
-        setting :add_to_load_path, true
-
-        # @!method default_namespace=(leading_namespace)
-        #
-        #   Sets the leading namespace segments to be stripped when registering components
-        #   from the dir in the container.
-        #
-        #   This is useful to configure when the dir contains components in a module
-        #   namespace that you don't want repeated in their identifiers.
+        #   When you provide an instance proc, it will be used in preference to the
+        #   {loader} (either the default loader or an explicitly configured one). Provide
+        #   an instance proc when you want a simple way to customize the instance for
+        #   certain components. For complete control, provide a replacement loader via
+        #   {loader=}.
         #
         #   Defaults to `nil`.
         #
-        #   @param leading_namespace [String, nil]
-        #   @return [String, nil]
+        #   @param instance_proc [Proc, nil]
+        #   @return [Proc]
         #
         #   @example
-        #     dir.default_namespace = "my_app"
-        #
-        #   @example
-        #     dir.default_namespace = "my_app.admin"
+        #     dir.instance = proc do |component|
+        #       if component.key.match?(/workers\./)
+        #         # Register classes for jobs
+        #         component.loader.constant(component)
+        #       else
+        #         # Otherwise register regular instances per default loader
+        #         component.loader.call(component)
+        #       end
+        #     end
         #
-        #   @see default_namespace
+        #   @see Component, Loader
+        #   @api public
         #
-        # @!method default_namespace
+        # @!method instance
         #
-        #   Returns the configured value.
+        #   Returns the configured instance proc.
         #
-        #   @return [String, nil]
+        #   @return [Proc, nil]
         #
-        #   @see default_namespace=
-        setting :default_namespace
+        #   @see instance=
+        #   @api public
+        setting :instance
 
         # @!method loader=(loader)
         #
-        #   Sets the loader to use when registering coponents from the dir in the container.
+        #   Sets the loader to use when registering components from the dir in the
+        #   container.
         #
         #   Defaults to `Dry::System::Loader`.
         #
-        #   When using a class autoloader, consider using `Dry::System::Loader::Autoloading`
+        #   When using an autoloader like Zeitwerk, consider using
+        #   `Dry::System::Loader::Autoloading`
         #
         #   @param loader [#call] the loader
         #   @return [#call] the configured loader
@@ -109,6 +109,7 @@ module Dry
         #   @see loader
         #   @see Loader
         #   @see Loader::Autoloading
+        #   @api public
         #
         # @!method loader
         #
@@ -117,7 +118,8 @@ module Dry
         #   @return [#call]
         #
         #   @see loader=
-        setting :loader, Dry::System::Loader
+        #   @api public
+        setting :loader, default: Dry::System::Loader
 
         # @!method memoize=(policy)
         #
@@ -138,11 +140,12 @@ module Dry
         #
         #   @example
         #     dir.memoize = proc do |component|
-        #       !component.start_with?("providers")
+        #       !component.identifier.start_with?("providers")
         #     end
         #
         #   @see memoize
         #   @see Component
+        #   @api public
         #
         # @!method memoize
         #
@@ -151,7 +154,79 @@ module Dry
         #   @return [Boolean, Proc] the configured memoization policy
         #
         #   @see memoize=
-        setting :memoize, false
+        #   @api public
+        setting :memoize, default: false
+
+        # @!method namespaces
+        #
+        #   Returns the configured namespaces for the component dir.
+        #
+        #   Allows namespaces to added on the returned object via {Namespaces#add}.
+        #
+        #   @return [Namespaces] the namespaces
+        #
+        #   @see Namespaces#add
+        #   @api public
+        setting :namespaces, default: Namespaces.new, cloneable: true
+
+        # @!method add_to_load_path=(policy)
+        #
+        #   Sets whether the dir should be added to the `$LOAD_PATH` after the container
+        #   is configured.
+        #
+        #   Defaults to `true`. This may need to be set to `false` when using a class
+        #   autoloading system.
+        #
+        #   @param policy [Boolean]
+        #   @return [Boolean]
+        #
+        #   @see add_to_load_path
+        #   @see Container.configure
+        #   @api public
+        #
+        # @!method add_to_load_path
+        #
+        #   Returns the configured value.
+        #
+        #   @return [Boolean]
+        #
+        #   @see add_to_load_path=
+        #   @api public
+        setting :add_to_load_path, default: true
+
+        # @api public
+        def default_namespace=(namespace)
+          Dry::Core::Deprecations.announce(
+            "Dry::System::Config::ComponentDir#default_namespace=",
+            "Add a namespace instead: `dir.namespaces.add #{namespace.to_s.inspect}, key: nil`",
+            tag: "dry-system",
+            uplevel: 1
+          )
+
+          # We don't have the configured separator here, so the best we can do is guess
+          # that it's a dot
+          namespace_path = namespace.gsub(".", PATH_SEPARATOR)
+
+          return if namespaces.namespaces[namespace_path]
+
+          namespaces.add namespace_path, key: nil
+        end
+
+        # @api public
+        def default_namespace
+          Dry::Core::Deprecations.announce(
+            "Dry::System::Config::ComponentDir#default_namespace",
+            "Use namespaces instead, e.g. `dir.namespaces`",
+            tag: "dry-system",
+            uplevel: 1
+          )
+
+          ns_path = namespaces.to_a.reject(&:root?).first&.path
+
+          # We don't have the configured separator here, so the best we can do is guess
+          # that it's a dot
+          ns_path&.gsub(PATH_SEPARATOR, ".")
+        end
 
         # @!endgroup
 
@@ -160,7 +235,7 @@ module Dry
         # @return [String] the path
         attr_reader :path
 
-        # @api private
+        # @api public
         def initialize(path)
           super()
           @path = path
@@ -172,15 +247,28 @@ module Dry
           !!config.auto_register
         end
 
-        # Returns true if a setting has been explicitly configured and is not returning
-        # just a default value.
+        # Returns true if the given setting has been explicitly configured by the user
         #
-        # This is used to determine which settings from `ComponentDirs` should be applied
-        # as additional defaults.
+        # This is used when determining whether to apply system-wide default values to a
+        # component dir (explicitly configured settings will not be overridden by
+        # defaults)
         #
+        # @param key [Symbol] the setting name
+        #
+        # @return [Boolean]
+        #
+        # @see Dry::System::Config::ComponentDirs#apply_defaults_to_dir
         # @api private
         def configured?(key)
-          config._settings[key].input_defined?
+          case key
+          when :namespaces
+            # Because we mutate the default value for the `namespaces` setting, rather
+            # than assign a new one, to check if it's configured we must see whether any
+            # namespaces have been added
+            !config.namespaces.empty?
+          else
+            config._settings[key].input_defined?
+          end
         end
 
         private

data/lib/dry/system/config/component_dirs.rb

@@ -1,5 +1,5 @@
-require "concurrent/map"
-require "dry/configurable"
+# frozen_string_literal: true
+
 require "dry/system/constants"
 require "dry/system/errors"
 require_relative "component_dir"
@@ -7,21 +7,17 @@ require_relative "component_dir"
 module Dry
   module System
     module Config
+      # The configured component dirs for a container
+      #
+      # @api public
       class ComponentDirs
-        include Dry::Configurable
-
-        # Settings from ComponentDir are configured here as defaults for all added dirs
-        ComponentDir._settings.each do |setting|
-          _settings << setting.dup
-        end
-
         # @!group Settings
 
         # @!method auto_register=(value)
         #
         #   Sets a default `auto_register` for all added component dirs
         #
-        #   @see ComponentDir.auto_register
+        #   @see ComponentDir.auto_register=
         #   @see auto_register
         #
         # @!method auto_register
@@ -30,37 +26,24 @@ module Dry
         #
         #   @see auto_register=
 
-        # @!method add_to_load_path=(value)
-        #
-        #   Sets a default `add_to_load_path` value for all added component dirs
-        #
-        #   @see ComponentDir.add_to_load_path
-        #   @see add_to_load_path
-        #
-        # @!method add_to_load_path
-        #
-        #   Returns the configured default `add_to_load_path`
-        #
-        #   @see add_to_load_path=
-
-        # @!method default_namespace=(value)
+        # @!method instance=(value)
         #
-        #   Sets a default `default_namespace` value for all added component dirs
+        #   Sets a default `instance` for all added component dirs
         #
-        #   @see ComponentDir.default_namespace
-        #   @see default_namespace
+        #   @see ComponentDir.instance=
+        #   @see auto_register
         #
-        # @!method default_namespace
+        # @!method auto_register
         #
-        #   Returns the configured default `default_namespace`
+        #   Returns the configured default `instance`
         #
-        #   @see default_namespace=
+        #   @see instance=
 
         # @!method loader=(value)
         #
         #   Sets a default `loader` value for all added component dirs
         #
-        #   @see ComponentDir.loader
+        #   @see ComponentDir.loader=
         #   @see loader
         #
         # @!method loader
@@ -73,7 +56,7 @@ module Dry
         #
         #   Sets a default `memoize` value for all added component dirs
         #
-        #   @see ComponentDir.memoize
+        #   @see ComponentDir.memoize=
         #   @see memoize
         #
         # @!method memoize
@@ -82,54 +65,154 @@ module Dry
         #
         #   @see memoize=
 
+        # rubocop:disable Layout/LineLength
+
+        # @!method namespaces
+        #
+        #   Returns the default configured namespaces for all added component dirs
+        #
+        #   Allows namespaces to added on the returned object via {Dry::System::Config::Namespaces#add}.
+        #
+        #   @see Dry::System::Config::Namespaces#add
+        #
+        #   @return [Namespaces] the namespaces
+
+        # @!method add_to_load_path=(value)
+        #
+        #   Sets a default `add_to_load_path` value for all added component dirs
+        #
+        #   @see ComponentDir.add_to_load_path=
+        #   @see add_to_load_path
+        #
+        # @!method add_to_load_path
+        #
+        #   Returns the configured default `add_to_load_path`
+        #
+        #   @see add_to_load_path=
+
+        # rubocop:enable Layout/LineLength
+
         # @!endgroup
 
+        # A ComponentDir for configuring the default values to apply to all added
+        # component dirs
+        #
+        # @see #method_missing
+        # @api private
+        attr_reader :defaults
+
+        # Creates a new component dirs
+        #
         # @api private
         def initialize
-          @dirs = Concurrent::Map.new
+          @dirs = {}
+          @defaults = ComponentDir.new(nil)
         end
 
         # @api private
         def initialize_copy(source)
-          super
-          @dirs = source.dirs.dup
+          @dirs = source.dirs.map { |path, dir| [path, dir.dup] }.to_h
+          @defaults = source.defaults.dup
+        end
+
+        # Returns and optionally yields a previously added component dir
+        #
+        # @param path [String] the path for the component dir
+        # @yieldparam dir [ComponentDir] the component dir
+        #
+        # @return [ComponentDir] the component dir
+        #
+        # @api public
+        def dir(path)
+          dirs[path].tap do |dir|
+            # Defaults can be (re-)applied first, since the dir has already been added
+            apply_defaults_to_dir(dir) if dir
+            yield dir if block_given?
+          end
         end
+        alias_method :[], :dir
 
-        # Adds and configures a component dir
+        # @overload add(path)
+        #   Adds and configures a component dir for the given path
+        #
+        #   @param path [String] the path for the component dir, relative to the configured
+        #     container root
+        #   @yieldparam dir [ComponentDir] the component dir to configure
         #
-        # @param path [String] the path for the component dir, relative to the configured
-        #   container root
+        #   @return [ComponentDir] the added component dir
         #
-        # @yieldparam dir [ComponentDir] the component dir to configure
+        #   @example
+        #     component_dirs.add "lib" do |dir|
+        #       dir.default_namespace = "my_app"
+        #     end
         #
-        # @return [ComponentDir] the added component dir
+        #   @see ComponentDir
+        #   @api public
         #
-        # @example
-        #   component_dirs.add "lib" do |dir|
-        #     dir.default_namespace = "my_app"
-        #   end
+        # @overload add(dir)
+        #   Adds a configured component dir
         #
-        # @see ComponentDir
-        def add(path)
+        #   @param dir [ComponentDir] the configured component dir
+        #
+        #   @return [ComponentDir] the added component dir
+        #
+        #   @example
+        #     dir = Dry::System::ComponentDir.new("lib")
+        #     component_dirs.add dir
+        #
+        #   @see ComponentDir
+        #   @api public
+        def add(path_or_dir)
+          path, dir_to_add = path_and_dir(path_or_dir)
+
           raise ComponentDirAlreadyAddedError, path if dirs.key?(path)
 
-          dirs[path] = ComponentDir.new(path).tap do |dir|
+          dirs[path] = dir_to_add.tap do |dir|
+            # Defaults must be applied after yielding, since the dir is being newly added,
+            # and must have its configuration fully in place before we can know which
+            # defaults to apply
+            yield dir if path_or_dir == path && block_given?
             apply_defaults_to_dir(dir)
-            yield dir if block_given?
           end
         end
 
-        # Returns the added component dirs, with default settings applied
+        # Deletes and returns a previously added component dir
+        #
+        # @param path [String] the path for the component dir
+        #
+        # @return [ComponentDir] the removed component dir
+        #
+        # @api public
+        def delete(path)
+          dirs.delete(path)
+        end
+
+        # Returns the paths of the component dirs
+        #
+        # @return [Array<String>] the component dir paths
+        #
+        # @api public
+        def paths
+          dirs.keys
+        end
+
+        # Returns the count of component dirs
+        #
+        # @return [Integer]
         #
-        # @return [Hash<String, ComponentDir>] the component dirs as a hash, keyed by path
-        def dirs
-          @dirs.each { |_, dir| apply_defaults_to_dir(dir) }
+        # @api public
+        def length
+          dirs.length
         end
+        alias_method :size, :length
 
         # Returns the added component dirs, with default settings applied
         #
         # @return [Array<ComponentDir>]
+        #
+        # @api public
         def to_a
+          dirs.each { |_, dir| apply_defaults_to_dir(dir) }
           dirs.values
         end
 
@@ -137,46 +220,69 @@ module Dry
         # argument.
         #
         # @yieldparam dir [ComponentDir] the yielded component dir
+        #
+        # @api public
         def each(&block)
           to_a.each(&block)
         end
 
+        protected
+
+        # Returns the hash of component dirs, keyed by their paths
+        #
+        # Recently changed default configuration may not be applied to these dirs. Use
+        # #to_a or #each to access dirs with default configuration fully applied.
+        #
+        # This method exists to encapsulate the instance variable and to serve the needs
+        # of #initialize_copy
+        #
+        # @return [Hash{String => ComponentDir}]
+        #
+        # @api private
+        attr_reader :dirs
+
         private
 
-        # Apply default settings to a component dir. This is run every time the dirs are
+        # Converts a path string or pre-built component dir into a path and dir tuple
+        #
+        # @param path_or_dir [String,ComponentDir]
+        #
+        # @return [Array<(String, ComponentDir)>]
+        #
+        # @see #add
+        def path_and_dir(path_or_dir)
+          if path_or_dir.is_a?(ComponentDir)
+            dir = path_or_dir
+            [dir.path, dir]
+          else
+            path = path_or_dir
+            [path, ComponentDir.new(path)]
+          end
+        end
+
+        # Applies default settings to a component dir. This is run every time the dirs are
         # accessed to ensure defaults are applied regardless of when new component dirs
         # are added. This method must be idempotent.
         #
         # @return [void]
         def apply_defaults_to_dir(dir)
-          dir.config.values.each do |key, _value|
-            if configured?(key) && !dir.configured?(key)
-              dir.public_send(:"#{key}=", public_send(key))
+          defaults.config.values.each do |key, _|
+            if defaults.configured?(key) && !dir.configured?(key)
+              dir.public_send(:"#{key}=", defaults.public_send(key).dup)
             end
           end
         end
 
-        # Returns true if a setting has been explicitly configured and is not returning
-        # just a default value.
-        #
-        # This is used to determine which settings should be applied to added component
-        # dirs as additional defaults.
-        #
-        # @api private
-        def configured?(key)
-          config._settings[key].input_defined?
-        end
-
         def method_missing(name, *args, &block)
-          if config.respond_to?(name)
-            config.public_send(name, *args, &block)
+          if defaults.respond_to?(name)
+            defaults.public_send(name, *args, &block)
           else
             super
           end
         end
 
         def respond_to_missing?(name, include_all = false)
-          config.respond_to?(name) || super
+          defaults.respond_to?(name) || super
         end
       end
     end