dry-system 0.20.0 → 0.21.0

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

@@ -1,5 +1,10 @@
+# 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
@@ -27,7 +32,7 @@ module Dry
         #
         #   @example
         #     dir.auto_register = proc do |component|
-        #       !component.start_with?("entities")
+        #       !component.identifier.start_with?("entities")
         #     end
         #
         #   @see auto_register
@@ -65,39 +70,10 @@ module Dry
         #   @see add_to_load_path=
         setting :add_to_load_path, default: 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.
-        #
-        #   Defaults to `nil`.
-        #
-        #   @param leading_namespace [String, nil]
-        #   @return [String, nil]
-        #
-        #   @example
-        #     dir.default_namespace = "my_app"
-        #
-        #   @example
-        #     dir.default_namespace = "my_app.admin"
-        #
-        #   @see default_namespace
-        #
-        # @!method default_namespace
-        #
-        #   Returns the configured value.
-        #
-        #   @return [String, nil]
-        #
-        #   @see default_namespace=
-        setting :default_namespace
-
         # @!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`.
         #
@@ -138,7 +114,7 @@ module Dry
         #
         #   @example
         #     dir.memoize = proc do |component|
-        #       !component.start_with?("providers")
+        #       !component.identifier.start_with?("providers")
         #     end
         #
         #   @see memoize
@@ -153,6 +129,49 @@ module Dry
         #   @see memoize=
         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}.
+        #
+        #   @see Namespaces#add
+        #
+        #   @return [Namespaces] the namespaces
+        setting :namespaces, default: Namespaces.new, cloneable: true
+
+        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
+
+        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
 
         # Returns the component dir path, relative to the configured container root
@@ -172,15 +191,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,6 @@
+# frozen_string_literal: true
+
 require "concurrent/map"
-require "dry/configurable"
 require "dry/system/constants"
 require "dry/system/errors"
 require_relative "component_dir"
@@ -8,13 +9,6 @@ module Dry
   module System
     module Config
       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)
@@ -43,19 +37,6 @@ module Dry
         #
         #   @see add_to_load_path=
 
-        # @!method default_namespace=(value)
-        #
-        #   Sets a default `default_namespace` value for all added component dirs
-        #
-        #   @see ComponentDir.default_namespace
-        #   @see default_namespace
-        #
-        # @!method default_namespace
-        #
-        #   Returns the configured default `default_namespace`
-        #
-        #   @see default_namespace=
-
         # @!method loader=(value)
         #
         #   Sets a default `loader` value for all added component dirs
@@ -82,17 +63,34 @@ module Dry
         #
         #   @see memoize=
 
+        # @!method namespaces
+        #
+        #   Returns the default configured namespaces for all added component dirs
+        #
+        #   Allows namespaces to added on the returned object via {Namespaces#add}.
+        #
+        #   @see Namespaces#add
+        #
+        #   @return [Namespaces] the namespaces
+
         # @!endgroup
 
+        # A ComponentDir for configuring the default values to apply to all added
+        # component dirs
+        #
+        # @api private
+        attr_reader :defaults
+
         # @api private
         def initialize
           @dirs = Concurrent::Map.new
+          @defaults = ComponentDir.new(nil)
         end
 
         # @api private
         def initialize_copy(source)
-          super
           @dirs = source.dirs.dup
+          @defaults = source.defaults.dup
         end
 
         # Adds and configures a component dir
@@ -114,8 +112,8 @@ module Dry
           raise ComponentDirAlreadyAddedError, path if dirs.key?(path)
 
           dirs[path] = ComponentDir.new(path).tap do |dir|
-            apply_defaults_to_dir(dir)
             yield dir if block_given?
+            apply_defaults_to_dir(dir)
           end
         end
 
@@ -143,40 +141,29 @@ module Dry
 
         private
 
-        # Apply default settings to a component dir. This is run every time the dirs are
+        # 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

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+
+module Dry
+  module System
+    module Config
+      # A configured namespace for a component dir
+      #
+      # Namespaces consist of three elements:
+      #
+      # - The `path` within the component dir to which its namespace rules should apply.
+      # - A `key`, which determines the leading part of the key used to register
+      #   each component in the container.
+      # - A `const`, which is the Ruby namespace expected to contain the class constants
+      #   defined within each component's source file. This value is expected to be an
+      #   "underscored" string, intended to be run through the configured inflector to be
+      #   converted into a real constant (e.g. `"foo_bar/baz"` will become `FooBar::Baz`)
+      #
+      # Namespaces are added and configured for a component dir via {Namespaces#add}.
+      #
+      # @see Namespaces#add
+      #
+      # @api private
+      class Namespace
+        ROOT_PATH = nil
+
+        include Dry::Equalizer(:path, :key, :const)
+
+        attr_reader :path
+
+        attr_reader :key
+
+        attr_reader :const
+
+        # Returns a namespace configured to serve as the default root namespace for a
+        # component dir, ensuring that all code within the dir can be loaded, regardless
+        # of any other explictly configured namespaces
+        #
+        # @return [Namespace] the root namespace
+        #
+        # @api private
+        def self.default_root
+          new(
+            path: ROOT_PATH,
+            key: nil,
+            const: nil
+          )
+        end
+
+        def initialize(path:, key:, const:)
+          @path = path
+          @key = key
+          @const = const
+        end
+
+        def root?
+          path == ROOT_PATH
+        end
+
+        def path?
+          !root?
+        end
+
+        def default_key?
+          key == path
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "dry/system/errors"
+require_relative "namespace"
+
+module Dry
+  module System
+    module Config
+      # The configured namespaces for a ComponentDir
+      #
+      # @see Config::ComponentDir#namespaces
+      #
+      # @api private
+      class Namespaces
+        # @api private
+        attr_reader :namespaces
+
+        # @api private
+        def initialize
+          @namespaces = {}
+        end
+
+        # @api private
+        def initialize_copy(source)
+          super
+          @namespaces = source.namespaces.dup
+        end
+
+        # rubocop:disable Layout/LineLength
+
+        # Adds a component dir namespace
+        #
+        # A namespace encompasses a given sub-directory of the component dir, and
+        # determines (1) the leading segments of its components' registered identifiers,
+        # and (2) the expected constant namespace of their class constants.
+        #
+        # A namespace for a path can only be added once.
+        #
+        # @example Adding a namespace with top-level identifiers
+        #   # Components defined within admin/ (e.g. admin/my_component.rb) will be:
+        #   #
+        #   # - Registered with top-level identifiers ("my_component")
+        #   # - Expected to have constants in `Admin`, matching the namespace's path (Admin::MyComponent)
+        #
+        #   namespaces.add "admin", key: nil
+        #
+        # @example Adding a namespace with top-level class constants
+        #   # Components defined within adapters/ (e.g. adapters/my_adapter.rb) will be:
+        #   #
+        #   # - Registered with leading identifiers matching the namespace's path ("adapters.my_adapter")
+        #   # - Expected to have top-level constants (::MyAdapter)
+        #
+        #   namespaces.add "adapters", const: nil
+        #
+        # @example Adding a namespace with distinct identifiers and class constants
+        #   # Components defined within `bananas/` (e.g. bananas/banana_split.rb) will be:
+        #   #
+        #   # - Registered with the given leading identifier ("desserts.banana_split")
+        #   # - Expected to have constants within the given namespace (EatMe::Now::BananaSplit)
+        #
+        #   namespaces.add "bananas", key: "desserts", const: "eat_me/now"
+        #
+        # @param path [String] the path to the sub-directory of source files to which this
+        #   namespace should apply, relative to the component dir
+        # @param identifier [String, nil] the leading namespace to apply to the registered
+        #   identifiers for the components. Set `nil` for the identifiers to be top-level.
+        # @param const [String, nil] the Ruby constant namespace to expect for constants
+        #   defined within the components. This should be provided in underscored string
+        #   form, e.g. "hello_there/world" for a Ruby constant of `HelloThere::World`. Set
+        #   `nil` for the constants to be top-level.
+        #
+        # @return [Namespace] the added namespace
+        #
+        # @see Namespace
+        #
+        # @api public
+        def add(path, key: path, const: path)
+          raise NamespaceAlreadyAddedError, path if namespaces.key?(path)
+
+          namespaces[path] = Namespace.new(path: path, key: key, const: const)
+        end
+
+        # rubocop:enable Layout/LineLength
+
+        # Adds a root component dir namespace
+        #
+        # @see #add
+        #
+        # @api public
+        def root(key: nil, const: nil)
+          add(Namespace::ROOT_PATH, key: key, const: const)
+        end
+
+        # @api private
+        def empty?
+          namespaces.empty?
+        end
+
+        # Returns the configured namespaces as an array
+        #
+        # This adds a root namespace to the end of the array if one was not configured
+        # manually. This fallback ensures that all components in the component dir can be
+        # loaded.
+        #
+        # @return [Array<Namespace>] the namespaces
+        #
+        # @api private
+        def to_a
+          namespaces.values.tap do |arr|
+            arr << Namespace.default_root unless arr.any?(&:root?)
+          end
+        end
+
+        # @api private
+        def each(&block)
+          to_a.each(&block)
+        end
+      end
+    end
+  end
+end

data/lib/dry/system/constants.rb

@@ -8,7 +8,7 @@ module Dry
 
     RB_EXT = ".rb"
     RB_GLOB = "*.rb"
-    PATH_SEPARATOR = "/"
+    PATH_SEPARATOR = File::SEPARATOR
     DEFAULT_SEPARATOR = "."
     WORD_REGEX = /\w+/.freeze
   end

data/lib/dry/system/container.rb

@@ -11,13 +11,15 @@ require "dry/core/constants"
 require "dry/core/deprecations"
 
 require "dry/system"
-require "dry/system/errors"
-require "dry/system/booter"
 require "dry/system/auto_registrar"
-require "dry/system/manual_registrar"
-require "dry/system/importer"
+require "dry/system/booter"
 require "dry/system/component"
 require "dry/system/constants"
+require "dry/system/errors"
+require "dry/system/identifier"
+require "dry/system/importer"
+require "dry/system/indirect_component"
+require "dry/system/manual_registrar"
 require "dry/system/plugins"
 
 require_relative "component_dir"
@@ -49,7 +51,7 @@ module Dry
     #
     # Every container needs to be configured with following settings:
     #
-    # * `:name` - a unique container identifier
+    # * `:name` - a unique container name
     # * `:root` - a system root directory (defaults to `pwd`)
     #
     # @example
@@ -234,7 +236,7 @@ module Dry
         #     persistence.register(:db, DB.new)
         #   end
         #
-        # @param name [Symbol] a unique identifier for a bootable component
+        # @param name [Symbol] a unique name for a bootable component
         #
         # @see Lifecycle
         #
@@ -262,17 +264,15 @@ module Dry
         deprecate :finalize, :boot
 
         # @api private
-        def boot_external(identifier, from:, key: nil, namespace: nil, &block)
+        def boot_external(name, from:, key: nil, namespace: nil, &block)
           System.providers[from].component(
-            identifier, key: key, namespace: namespace, finalize: block, container: self
+            name, key: key, namespace: namespace, finalize: block, container: self
           )
         end
 
         # @api private
-        def boot_local(identifier, namespace: nil, &block)
-          Components::Bootable.new(
-            identifier, container: self, namespace: namespace, &block
-          )
+        def boot_local(name, namespace: nil, &block)
+          Components::Bootable.new(name, container: self, namespace: namespace, &block)
         end
 
         # Return if a container was finalized
@@ -491,7 +491,7 @@ module Dry
         #
         # @!method registered?(key)
         #   Whether a +key+ is registered (doesn't trigger loading)
-        #   @param [String,Symbol] key Identifier
+        #   @param [String,Symbol] key The key
         #   @return [Boolean]
         #   @api public
         #
@@ -581,17 +581,17 @@ module Dry
         def load_component(key)
           return self if registered?(key)
 
-          component = component(key)
-
-          if component.bootable?
-            booter.start(component)
+          if (bootable_component = booter.find_component(key))
+            booter.start(bootable_component)
             return self
           end
 
+          component = find_component(key)
+
           booter.boot_dependency(component)
           return self if registered?(key)
 
-          if component.file_exists?
+          if component.loadable?
             load_local_component(component)
           elsif manual_registrar.file_exists?(component)
             manual_registrar.(component)
@@ -615,25 +615,21 @@ module Dry
 
           container = importer[import_namespace]
 
-          container.load_component(identifier.dequalified(import_namespace).key)
+          container.load_component(identifier.namespaced(from: import_namespace, to: nil).key)
 
           importer.(import_namespace, container)
         end
 
-        def component(identifier)
-          if (bootable_component = booter.find_component(identifier))
-            return bootable_component
-          end
-
+        def find_component(key)
           # Find the first matching component from within the configured component dirs.
-          # If no matching component is found, return a plain component instance with no
-          # associated file path. This fallback is important because the component may
-          # still be loadable via the manual registrar or an imported container.
+          # If no matching component is found, return a null component; this fallback is
+          # important because the component may still be loadable via the manual registrar
+          # or an imported container.
           component_dirs.detect { |dir|
-            if (component = dir.component_for_identifier(identifier))
+            if (component = dir.component_for_key(key))
               break component
             end
-          } || Component.new(identifier)
+          } || IndirectComponent.new(Identifier.new(key, separator: config.namespace_separator))
         end
       end
 

data/lib/dry/system/errors.rb

@@ -11,13 +11,13 @@ module Dry
       end
     end
 
-    # Error raised when the container tries to load a component with missing
-    # file
-    #
-    # @api public
-    FileNotFoundError = Class.new(StandardError) do
-      def initialize(component)
-        super("could not resolve require file for component '#{component.identifier}'")
+    # Error raised when a namespace for a component dir is added to configuration more
+    # than once
+    NamespaceAlreadyAddedError = Class.new(StandardError) do
+      def initialize(path)
+        path_label = path ? "path #{path.inspect}" : "root path"
+
+        super("Namespace for #{path_label} already added")
       end
     end
 
@@ -27,7 +27,7 @@ module Dry
     ComponentFileMismatchError = Class.new(StandardError) do
       def initialize(component)
         super(<<-STR)
-          Bootable component '#{component.identifier}' not found
+          Bootable component '#{component.name}' not found
         STR
       end
     end
@@ -43,26 +43,17 @@ module Dry
       end
     end
 
-    # Error raised when component's identifier is not valid
+    # Error raised when component's name is not valid
     #
     # @api public
-    InvalidComponentIdentifierError = Class.new(ArgumentError) do
+    InvalidComponentNameError = Class.new(ArgumentError) do
       def initialize(name)
         super(
-          "component identifier +#{name}+ is invalid or boot file is missing"
+          "component +#{name}+ is invalid or boot file is missing"
         )
       end
     end
 
-    # Error raised when component's identifier for booting is not a symbol
-    #
-    # @api public
-    InvalidComponentIdentifierTypeError = Class.new(ArgumentError) do
-      def initialize(name)
-        super("component identifier #{name.inspect} must be a symbol")
-      end
-    end
-
     # Error raised when trying to stop a component that hasn't started yet
     #
     # @api public