dry-system 0.19.1 → 0.22.0

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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "dry/core/deprecations"
+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
+
+        # Returns the namespace configured for the path, or nil if no such namespace has
+        # been configured
+        #
+        # @return [Namespace, nil] the namespace, if configured
+        #
+        # @api public
+        def namespace(path)
+          namespaces[path]
+        end
+        alias_method :[], :namespace
+
+        # Returns the namespace configured for the root path, or nil if the root namespace
+        # has not been configured
+        #
+        # @return [Namespace, nil] the root namespace, if configured
+        #
+        # @api public
+        def root(**options)
+          if options.any?
+            Dry::Core::Deprecations.announce(
+              "Dry::System::Config::Namespaces#root (with arguments)",
+              "Use `#add_root(key: nil, const: nil)` instead",
+              tag: "dry-system",
+              uplevel: 1
+            )
+
+            add_root(**options)
+            return
+          end
+
+          namespaces[Namespace::ROOT_PATH]
+        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 key [String, nil] the leading namespace to apply to the container keys
+        #   for the components. Set `nil` for the keys 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 add_root(key: nil, const: nil)
+          add(Namespace::ROOT_PATH, key: key, const: const)
+        end
+
+        # Deletes the configured namespace for the given path and returns the namespace
+        #
+        # If no namespace was previously configured for the given path, returns nil
+        #
+        # @param path [String] the path for the namespace
+        #
+        # @return [Namespace, nil]
+        #
+        # @api public
+        def delete(path)
+          namespaces.delete(path)
+        end
+
+        # Deletes the configured root namespace and returns the namespace
+        #
+        # If no root namespace was previously configured, returns nil
+        #
+        # @return [Namespace, nil]
+        #
+        # @api public
+        def delete_root
+          delete(Namespace::ROOT_PATH)
+        end
+
+        # Returns the paths of the configured namespaces
+        #
+        # @return [Array<String,nil>] the namespace paths, with nil representing the root
+        #   namespace
+        #
+        # @api public
+        def paths
+          namespaces.keys
+        end
+
+        # Returns the count of configured namespaces
+        #
+        # @return [Integer]
+        #
+        # @api public
+        def length
+          namespaces.length
+        end
+        alias_method :size, :length
+
+        # Returns true if there are no configured namespaces
+        #
+        # @return [Boolean]
+        #
+        # @api public
+        def empty?
+          namespaces.empty?
+        end
+
+        # Returns the configured namespaces as an array
+        #
+        # Adds a default root namespace to the end of the array if one was not added
+        # explicitly. This fallback ensures that all components in the component dir can
+        # be loaded.
+        #
+        # @return [Array<Namespace>] the namespaces
+        #
+        # @api public
+        def to_a
+          namespaces.values.tap do |arr|
+            arr << Namespace.default_root unless arr.any?(&:root?)
+          end
+        end
+
+        # Calls the given block once for each configured namespace, passing the namespace
+        # as an argument.
+        #
+        # @yieldparam namespace [Namespace] the yielded namespace
+        #
+        # @api public
+        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

@@ -7,16 +7,19 @@ 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/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"
@@ -48,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
@@ -73,17 +76,17 @@ module Dry
       extend Dry::System::Plugins
 
       setting :name
-      setting(:root, Pathname.pwd.freeze) { |path| Pathname(path) }
-      setting :system_dir, "system"
-      setting :bootable_dirs, ["system/boot"]
-      setting :registrations_dir, "container"
-      setting :component_dirs, Config::ComponentDirs.new, cloneable: true
-      setting :inflector, Dry::Inflector.new
-      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,8 +104,8 @@ 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
@@ -233,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
         #
@@ -261,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
@@ -490,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
         #
@@ -580,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)
@@ -614,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

data/lib/dry/system/identifier.rb

@@ -13,42 +13,29 @@ module Dry
     #
     # @api public
     class Identifier
-      include Dry::Equalizer(:identifier, :namespace, :separator)
+      include Dry::Equalizer(:key, :separator)
 
-      # @return [String] the identifier string
+      # @return [String] the identifier's string key
       # @api public
-      attr_reader :identifier
-
-      # @return [String, nil] the namespace for the component
-      # @api public
-      attr_reader :namespace
+      attr_reader :key
 
       # @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
+      def initialize(key, separator: DEFAULT_SEPARATOR)
+        @key = key.to_s
         @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
+      #   Returns the identifier string key
       #
       #   @return [String]
-      #   @see #identifier
+      #   @see #key
       #   @api public
-      alias_method :to_s, :identifier
+      alias_method :to_s, :key
 
       # Returns the root namespace segment of the identifier string, as a symbol
       #
@@ -62,31 +49,11 @@ module Dry
         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"
+      # Returns true if the given leading namespaces are a leading part of the
+      # identifier's key
       #
-      #   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
+      # Also returns true if nil is given (technically, from nothing everything is
+      # wrought)
       #
       # @example
       #   identifier.key # => "articles.operations.create"
@@ -94,63 +61,74 @@ module Dry
       #   identifier.start_with?("articles.operations") # => true
       #   identifier.start_with?("articles") # => true
       #   identifier.start_with?("article") # => false
+      #   identifier.start_with?(nil) # => true
       #
       # @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}")
+        leading_namespaces.nil? ||
+          key.start_with?("#{leading_namespaces}#{separator}") ||
+          key.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
+      # Returns the key with its segments separated by the given separator
       #
-      # @return [Dry::System::Identifier] the copy of the identifier
+      # @example
+      #   identifier.key # => "articles.operations.create"
+      #   identifier.key_with_separator("/") # => "articles/operations/create"
       #
-      # @see #initialize
+      # @return [String] the key using the separator
       # @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
-        )
+      def key_with_separator(separator)
+        segments.join(separator)
       end
 
-      # Returns a copy of the identifier with the given options applied
+      # Returns a copy of the identifier with the key's leading namespace(s) replaced
+      #
+      # @example Changing a namespace
+      #   identifier.key # => "articles.operations.create"
+      #   identifier.namespaced(from: "articles", to: "posts").key # => "posts.commands.create"
+      #
+      # @example Removing a namespace
+      #   identifier.key # => "articles.operations.create"
+      #   identifier.namespaced(from: "articles", to: nil).key # => "operations.create"
       #
-      # @param namespace [String, nil] a new namespace to be used
+      # @example Adding a namespace
+      #   identifier.key # => "articles.operations.create"
+      #   identifier.namespaced(from: nil, to: "admin").key # => "admin.articles.operations.create"
+      #
+      # @param from [String, nil] the leading namespace(s) to replace
+      # @param to [String, nil] the replacement for the leading namespace
       #
       # @return [Dry::System::Identifier] the copy of the identifier
       #
       # @see #initialize
       # @api private
-      def with(namespace:)
-        self.class.new(
-          identifier,
-          namespace: namespace,
-          separator: separator
-        )
+      def namespaced(from:, to:)
+        return self if from == to
+
+        separated_to = "#{to}#{separator}" if to
+
+        new_key =
+          if from.nil?
+            "#{separated_to}#{key}"
+          else
+            key.sub(
+              /^#{Regexp.escape(from.to_s)}#{Regexp.escape(separator)}/,
+              separated_to || EMPTY_STRING
+            )
+          end
+
+        return self if new_key == key
+
+        self.class.new(new_key, separator: separator)
       end
 
       private
 
       def segments
-        @segments ||= identifier.split(separator)
+        @segments ||= key.split(separator)
       end
     end
   end