dry-system 0.18.2 → 0.20.0

data/lib/dry/system/container.rb

@@ -7,11 +7,11 @@ require "dry-configurable"
 require "dry-container"
 require "dry/inflector"
 
+require "dry/core/constants"
 require "dry/core/deprecations"
 
 require "dry/system"
 require "dry/system/errors"
-require "dry/system/loader"
 require "dry/system/booter"
 require "dry/system/auto_registrar"
 require "dry/system/manual_registrar"
@@ -20,6 +20,9 @@ require "dry/system/component"
 require "dry/system/constants"
 require "dry/system/plugins"
 
+require_relative "component_dir"
+require_relative "config/component_dirs"
+
 module Dry
   module System
     # Abstract container class to inherit from
@@ -61,7 +64,7 @@ module Dry
     #     end
     #
     #     # this will configure $LOAD_PATH to include your `lib` dir
-    #     load_paths!('lib')
+    #     add_dirs_to_load_paths!('lib')
     #   end
     #
     # @api public
@@ -71,19 +74,17 @@ module Dry
       extend Dry::System::Plugins
 
       setting :name
-      setting :default_namespace
-      setting(:root, Pathname.pwd.freeze) { |path| Pathname(path) }
-      setting :system_dir, "system"
-      setting :bootable_dirs, ["system/boot"]
-      setting :registrations_dir, "container"
-      setting :auto_register, []
-      setting :inflector, Dry::Inflector.new
-      setting :loader, Dry::System::Loader
-      setting :booter, Dry::System::Booter
-      setting :auto_registrar, Dry::System::AutoRegistrar
-      setting :manual_registrar, Dry::System::ManualRegistrar
-      setting :importer, Dry::System::Importer
-      setting(:components, {}, reader: true, &:dup)
+      setting :root, default: Pathname.pwd.freeze, constructor: -> path { Pathname(path) }
+      setting :system_dir, default: "system"
+      setting :bootable_dirs, default: ["system/boot"]
+      setting :registrations_dir, default: "container"
+      setting :component_dirs, default: Config::ComponentDirs.new, cloneable: true
+      setting :inflector, default: Dry::Inflector.new
+      setting :booter, default: Dry::System::Booter
+      setting :auto_registrar, default: Dry::System::AutoRegistrar
+      setting :manual_registrar, default: Dry::System::ManualRegistrar
+      setting :importer, default: Dry::System::Importer
+      setting :components, default: {}, reader: true, constructor: :dup.to_proc
 
       class << self
         def strategies(value = nil)
@@ -101,13 +102,12 @@ module Dry
         # @see https://dry-rb.org/gems/dry-configurable
         #
         # @api public
-        def setting(name, *args, &block)
-          super(name, *args, &block)
+        def setting(name, default = Dry::Core::Constants::Undefined, **options, &block)
+          super(name, default, **options, &block)
           # TODO: dry-configurable needs a public API for this
           config._settings << _settings[name]
           self
         end
-        ruby2_keywords(:setting) if respond_to?(:ruby2_keywords, true)
 
         # Configures the container
         #
@@ -126,7 +126,6 @@ module Dry
         def configure(&block)
           hooks[:before_configure].each { |hook| instance_eval(&hook) }
           super(&block)
-          load_paths!(config.system_dir)
           hooks[:after_configure].each { |hook| instance_eval(&hook) }
           self
         end
@@ -385,7 +384,7 @@ module Dry
           self
         end
 
-        # Sets load paths relative to the container's root dir
+        # Adds the directories (relative to the container's root) to the Ruby load path
         #
         # @example
         #   class MyApp < Dry::System::Container
@@ -393,7 +392,7 @@ module Dry
         #       # ...
         #     end
         #
-        #     load_paths!('lib')
+        #     add_to_load_path!('lib')
         #   end
         #
         # @param [Array<String>] dirs
@@ -401,12 +400,9 @@ module Dry
         # @return [self]
         #
         # @api public
-        def load_paths!(*dirs)
-          dirs.map(&root.method(:join)).each do |path|
-            next if load_paths.include?(path)
-
-            load_paths << path
-            $LOAD_PATH.unshift(path.to_s)
+        def add_to_load_path!(*dirs)
+          dirs.reverse.map(&root.method(:join)).each do |path|
+            $LOAD_PATH.prepend(path.to_s) unless $LOAD_PATH.include?(path.to_s)
           end
           self
         end
@@ -417,47 +413,6 @@ module Dry
           self
         end
 
-        # Auto-registers components from the provided directory
-        #
-        # Typically you want to configure auto_register directories, and it will
-        # work automatically. Use this method in cases where you want to have an
-        # explicit way where some components are auto-registered, or if you want
-        # to exclude some components from being auto-registered
-        #
-        # @example
-        #   class MyApp < Dry::System::Container
-        #     configure do |config|
-        #       # ...
-        #     end
-        #
-        #     # with a dir
-        #     auto_register!('lib/core')
-        #
-        #     # with a dir and a custom registration block
-        #     auto_register!('lib/core') do |config|
-        #       config.instance do |component|
-        #         # custom way of initializing a component
-        #       end
-        #
-        #       config.exclude do |component|
-        #         # return true to exclude component from auto-registration
-        #       end
-        #     end
-        #   end
-        #
-        # @param [String] dir The dir name relative to the root dir
-        #
-        # @yield AutoRegistrar::Configuration
-        # @see AutoRegistrar::Configuration
-        #
-        # @return [self]
-        #
-        # @api public
-        def auto_register!(dir, &block)
-          auto_registrar.(dir, &block)
-          self
-        end
-
         # Builds injector for this container
         #
         # An injector is a useful mixin which injects dependencies into
@@ -526,8 +481,8 @@ module Dry
         end
 
         # @api public
-        def resolve(key, &block)
-          load_component(key, &block) unless finalized?
+        def resolve(key)
+          load_component(key) unless finalized?
 
           super
         end
@@ -558,8 +513,8 @@ module Dry
         end
 
         # @api private
-        def load_paths
-          @load_paths ||= []
+        def component_dirs
+          config.component_dirs.to_a.map { |dir| ComponentDir.new(config: dir, container: self) }
         end
 
         # @api private
@@ -595,67 +550,6 @@ module Dry
           @importer ||= config.importer.new(self)
         end
 
-        # @api private
-        def component(identifier, **options)
-          if (component = booter.components.detect { |c| c.identifier == identifier })
-            component
-          else
-            Component.new(
-              identifier,
-              loader: config.loader,
-              namespace: config.default_namespace,
-              separator: config.namespace_separator,
-              inflector: config.inflector,
-              **options
-            )
-          end
-        end
-
-        # @api private
-        def require_component(component)
-          return if registered?(component.identifier)
-
-          raise FileNotFoundError, component unless component.file_exists?(load_paths)
-
-          require_path(component.path)
-
-          yield
-        end
-
-        # Allows subclasses to use a different strategy for required files.
-        #
-        # E.g. apps that use `ActiveSupport::Dependencies::Loadable#require_dependency`
-        # will override this method to allow container managed dependencies to be reloaded
-        # for non-finalized containers.
-        #
-        # @api private
-        def require_path(path)
-          require path
-        end
-
-        # @api private
-        def load_component(key, &block)
-          return self if registered?(key)
-
-          component(key).tap do |component|
-            if component.bootable?
-              booter.start(component)
-            else
-              root_key = component.root_key
-
-              if (root_bootable = component(root_key)).bootable?
-                booter.start(root_bootable)
-              elsif importer.key?(root_key)
-                load_imported_component(component.namespaced(root_key))
-              end
-
-              load_local_component(component, &block) unless registered?(key)
-            end
-          end
-
-          self
-        end
-
         # @api private
         def after(event, &block)
           hooks[:"after_#{event}"] << block
@@ -672,46 +566,87 @@ module Dry
 
         # @api private
         def inherited(klass)
-          new_hooks = Container.hooks.dup
-
           hooks.each do |event, blocks|
-            new_hooks[event].concat(blocks)
-            new_hooks[event].concat(klass.hooks[event])
+            klass.hooks[event].concat blocks.dup
           end
 
-          klass.instance_variable_set(:@hooks, new_hooks)
           klass.instance_variable_set(:@__finalized__, false)
+
           super
         end
 
-        private
+        protected
 
         # @api private
-        def load_local_component(component, default_namespace_fallback = false, &block)
-          if booter.bootable?(component) || component.file_exists?(load_paths)
-            booter.boot_dependency(component) unless finalized?
+        def load_component(key)
+          return self if registered?(key)
 
-            require_component(component) do
-              register(component.identifier) { component.instance }
-            end
-          elsif !default_namespace_fallback
-            load_local_component(component.prepend(config.default_namespace), true, &block)
+          component = component(key)
+
+          if component.bootable?
+            booter.start(component)
+            return self
+          end
+
+          booter.boot_dependency(component)
+          return self if registered?(key)
+
+          if component.file_exists?
+            load_local_component(component)
           elsif manual_registrar.file_exists?(component)
             manual_registrar.(component)
-          elsif block_given?
-            yield
-          else
-            raise ComponentLoadError, component
+          elsif importer.key?(component.identifier.root_key)
+            load_imported_component(component.identifier)
           end
+
+          self
         end
 
-        # @api private
-        def load_imported_component(component)
-          container = importer[component.namespace]
-          container.load_component(component.identifier)
-          importer.(component.namespace, container)
+        private
+
+        def load_local_component(component)
+          if component.auto_register?
+            register(component.identifier, memoize: component.memoize?) { component.instance }
+          end
+        end
+
+        def load_imported_component(identifier)
+          import_namespace = identifier.root_key
+
+          container = importer[import_namespace]
+
+          container.load_component(identifier.dequalified(import_namespace).key)
+
+          importer.(import_namespace, container)
+        end
+
+        def component(identifier)
+          if (bootable_component = booter.find_component(identifier))
+            return bootable_component
+          end
+
+          # 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.
+          component_dirs.detect { |dir|
+            if (component = dir.component_for_identifier(identifier))
+              break component
+            end
+          } || Component.new(identifier)
         end
       end
+
+      # Default hooks
+      after :configure do
+        # Add appropriately configured component dirs to the load path
+        #
+        # Do this in a single pass to preserve ordering (i.e. earliest dirs win)
+        paths = config.component_dirs.to_a.each_with_object([]) { |dir, arr|
+          arr << dir.path if dir.add_to_load_path
+        }
+        add_to_load_path!(*paths)
+      end
     end
   end
 end

data/lib/dry/system/errors.rb

@@ -2,13 +2,22 @@
 
 module Dry
   module System
+    # Error raised when a component dir is added to configuration more than once
+    #
+    # @api public
+    ComponentDirAlreadyAddedError = Class.new(StandardError) do
+      def initialize(dir)
+        super("Component directory #{dir.inspect} already added")
+      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.identifier}")
+        super("could not resolve require file for component '#{component.identifier}'")
       end
     end
 
@@ -18,20 +27,11 @@ module Dry
     ComponentFileMismatchError = Class.new(StandardError) do
       def initialize(component)
         super(<<-STR)
-          Bootable component #{component.identifier.inspect} not found
+          Bootable component '#{component.identifier}' not found
         STR
       end
     end
 
-    # Error raised when a resolved component couldn't be found
-    #
-    # @api public
-    ComponentLoadError = Class.new(StandardError) do
-      def initialize(component)
-        super("could not load component #{component.inspect}")
-      end
-    end
-
     # Error raised when resolved component couldn't be loaded
     #
     # @api public
@@ -81,8 +81,17 @@ module Dry
       end
     end
 
-    ComponentsDirMissing = Class.new(StandardError)
+    # Error raised when a configured component directory could not be found
+    #
+    # @api public
+    ComponentDirNotFoundError = Class.new(StandardError) do
+      def initialize(dir)
+        super("Component dir '#{dir}' not found")
+      end
+    end
+
     DuplicatedComponentKeyError = Class.new(ArgumentError)
+
     InvalidSettingsError = Class.new(ArgumentError) do
       # @api private
       def initialize(attributes)

data/lib/dry/system/identifier.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+require_relative "constants"
+
+module Dry
+  module System
+    # An identifier representing a component to be registered.
+    #
+    # Components are eventually registered in the container using plain string
+    # identifiers, available as the `identifier` or `key` attribute here. Additional
+    # methods are provided to make it easier to evaluate or manipulate these identifiers.
+    #
+    # @api public
+    class Identifier
+      include Dry::Equalizer(:identifier, :namespace, :separator)
+
+      # @return [String] the identifier string
+      # @api public
+      attr_reader :identifier
+
+      # @return [String, nil] the namespace for the component
+      # @api public
+      attr_reader :namespace
+
+      # @return [String] the configured namespace separator
+      # @api public
+      attr_reader :separator
+
+      # @api private
+      def initialize(identifier, namespace: nil, separator: DEFAULT_SEPARATOR)
+        @identifier = identifier.to_s
+        @namespace = namespace
+        @separator = separator
+      end
+
+      # @!method key
+      #   Returns the identifier string
+      #
+      #   @return [String]
+      #   @see #identifier
+      #   @api public
+      alias_method :key, :identifier
+
+      # @!method to_s
+      #   Returns the identifier string
+      #
+      #   @return [String]
+      #   @see #identifier
+      #   @api public
+      alias_method :to_s, :identifier
+
+      # Returns the root namespace segment of the identifier string, as a symbol
+      #
+      # @example
+      #   identifier.key # => "articles.operations.create"
+      #   identifier.root_key # => :articles
+      #
+      # @return [Symbol] the root key
+      # @api public
+      def root_key
+        segments.first.to_sym
+      end
+
+      # Returns a path-delimited representation of the identifier, with the namespace
+      # incorporated. This path is intended for usage when requiring the component's
+      # source file.
+      #
+      # @example
+      #   identifier.key # => "articles.operations.create"
+      #   identifier.namespace # => "admin"
+      #
+      #   identifier.path # => "admin/articles/operations/create"
+      #
+      # @return [String] the path
+      # @api public
+      def path
+        @require_path ||= identifier.gsub(separator, PATH_SEPARATOR).yield_self { |path|
+          if namespace
+            namespace_path = namespace.to_s.gsub(separator, PATH_SEPARATOR)
+            "#{namespace_path}#{PATH_SEPARATOR}#{path}"
+          else
+            path
+          end
+        }
+      end
+
+      # Returns true if the given namespace prefix is part of the identifier's leading
+      # namespaces
+      #
+      # @example
+      #   identifier.key # => "articles.operations.create"
+      #
+      #   identifier.start_with?("articles.operations") # => true
+      #   identifier.start_with?("articles") # => true
+      #   identifier.start_with?("article") # => false
+      #
+      # @param leading_namespaces [String] the one or more leading namespaces to check
+      # @return [Boolean]
+      # @api public
+      def start_with?(leading_namespaces)
+        identifier.start_with?("#{leading_namespaces}#{separator}") ||
+          identifier.eql?(leading_namespaces)
+      end
+
+      # Returns a copy of the identifier with the given leading namespaces removed from
+      # the identifier string.
+      #
+      # Additional options may be provided, which are passed to #initialize when
+      # constructing the new copy of the identifier
+      #
+      # @param leading_namespace [String] the one or more leading namespaces to remove
+      # @param options [Hash] additional options for initialization
+      #
+      # @return [Dry::System::Identifier] the copy of the identifier
+      #
+      # @see #initialize
+      # @api private
+      def dequalified(leading_namespaces, **options)
+        new_identifier = identifier.gsub(
+          /^#{Regexp.escape(leading_namespaces)}#{Regexp.escape(separator)}/,
+          EMPTY_STRING
+        )
+
+        return self if new_identifier == identifier
+
+        self.class.new(
+          new_identifier,
+          namespace: namespace,
+          separator: separator,
+          **options
+        )
+      end
+
+      # Returns a copy of the identifier with the given options applied
+      #
+      # @param namespace [String, nil] a new namespace to be used
+      #
+      # @return [Dry::System::Identifier] the copy of the identifier
+      #
+      # @see #initialize
+      # @api private
+      def with(namespace:)
+        self.class.new(
+          identifier,
+          namespace: namespace,
+          separator: separator
+        )
+      end
+
+      private
+
+      def segments
+        @segments ||= identifier.split(separator)
+      end
+    end
+  end
+end