dry-system 0.18.1 → 1.0.1

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

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "dry/system/constants"
+
+module Dry
+  module System
+    module Config
+      # @api public
+      class ComponentDir
+        include Dry::Configurable
+
+        # @!group Settings
+
+        # @!method auto_register=(policy)
+        #
+        #   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::System::Component} and returning a
+        #   boolean to configure auto-registration on a per-component basis
+        #
+        #   Defaults to `true`.
+        #
+        #   @param policy [Boolean, Proc]
+        #   @return [Boolean, Proc]
+        #
+        #   @example
+        #     dir.auto_register = false
+        #
+        #   @example
+        #     dir.auto_register = proc do |component|
+        #       !component.identifier.start_with?("entities")
+        #     end
+        #
+        #   @see auto_register
+        #   @see Component
+        #   @api public
+        #
+        # @!method auto_register
+        #
+        #   Returns the configured auto-registration policy.
+        #
+        #   @return [Boolean, Proc] the configured policy
+        #
+        #   @see auto_register=
+        #   @api public
+        setting :auto_register, default: true
+
+        # @!method instance=(instance_proc)
+        #
+        #   Sets a proc used to return the instance of any component within the component
+        #   dir.
+        #
+        #   This proc should accept a {Dry::System::Component} and return the object to
+        #   serve as the component's instance.
+        #
+        #   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 instance_proc [Proc, nil]
+        #   @return [Proc]
+        #
+        #   @example
+        #     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 Component, Loader
+        #   @api public
+        #
+        # @!method instance
+        #
+        #   Returns the configured instance proc.
+        #
+        #   @return [Proc, nil]
+        #
+        #   @see instance=
+        #   @api public
+        setting :instance
+
+        # @!method loader=(loader)
+        #
+        #   Sets the loader to use when registering components from the dir in the
+        #   container.
+        #
+        #   Defaults to `Dry::System::Loader`.
+        #
+        #   When using an autoloader like Zeitwerk, consider using
+        #   `Dry::System::Loader::Autoloading`
+        #
+        #   @param loader [#call] the loader
+        #   @return [#call] the configured loader
+        #
+        #   @see loader
+        #   @see Loader
+        #   @see Loader::Autoloading
+        #   @api public
+        #
+        # @!method loader
+        #
+        #   Returns the configured loader.
+        #
+        #   @return [#call]
+        #
+        #   @see loader=
+        #   @api public
+        setting :loader, default: Dry::System::Loader
+
+        # @!method memoize=(policy)
+        #
+        #   Sets whether to memoize components from the dir when registered in the
+        #   container.
+        #
+        #   This may be a simple boolean to enable or disable memoization for all
+        #   components, or a proc accepting a `Dry::Sytem::Component` and returning a
+        #   boolean to configure memoization on a per-component basis
+        #
+        #   Defaults to `false`.
+        #
+        #   @param policy [Boolean, Proc]
+        #   @return [Boolean, Proc] the configured memoization policy
+        #
+        #   @example
+        #     dir.memoize = true
+        #
+        #   @example
+        #     dir.memoize = proc do |component|
+        #       !component.identifier.start_with?("providers")
+        #     end
+        #
+        #   @see memoize
+        #   @see Component
+        #   @api public
+        #
+        # @!method memoize
+        #
+        #   Returns the configured memoization policy.
+        #
+        #   @return [Boolean, Proc] the configured memoization policy
+        #
+        #   @see memoize=
+        #   @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
+
+        # @!endgroup
+
+        # Returns the component dir path, relative to the configured container root
+        #
+        # @return [String] the path
+        attr_reader :path
+
+        # @api public
+        def initialize(path)
+          super()
+          @path = path
+          yield self if block_given?
+        end
+
+        # @api private
+        def auto_register?
+          !!config.auto_register
+        end
+
+        private
+
+        def method_missing(name, *args, &block)
+          if config.respond_to?(name)
+            config.public_send(name, *args, &block)
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(name, include_all = false)
+          config.respond_to?(name) || super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require "dry/system/constants"
+require "dry/system/errors"
+
+module Dry
+  module System
+    module Config
+      # The configured component dirs for a container
+      #
+      # @api public
+      class ComponentDirs
+        # @!group Settings
+
+        # @!method auto_register=(value)
+        #
+        #   Sets a default `auto_register` for all added component dirs
+        #
+        #   @see ComponentDir.auto_register=
+        #   @see auto_register
+        #
+        # @!method auto_register
+        #
+        #   Returns the configured default `auto_register`
+        #
+        #   @see auto_register=
+
+        # @!method instance=(value)
+        #
+        #   Sets a default `instance` for all added component dirs
+        #
+        #   @see ComponentDir.instance=
+        #   @see auto_register
+        #
+        # @!method auto_register
+        #
+        #   Returns the configured default `instance`
+        #
+        #   @see instance=
+
+        # @!method loader=(value)
+        #
+        #   Sets a default `loader` value for all added component dirs
+        #
+        #   @see ComponentDir.loader=
+        #   @see loader
+        #
+        # @!method loader
+        #
+        #   Returns the configured default `loader`
+        #
+        #   @see loader=
+
+        # @!method memoize=(value)
+        #
+        #   Sets a default `memoize` value for all added component dirs
+        #
+        #   @see ComponentDir.memoize=
+        #   @see memoize
+        #
+        # @!method memoize
+        #
+        #   Returns the configured default `memoize`
+        #
+        #   @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 = {}
+          @defaults = ComponentDir.new(nil)
+        end
+
+        # @api private
+        def initialize_copy(source)
+          @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
+
+        # @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
+        #
+        #   @return [ComponentDir] the added component dir
+        #
+        #   @example
+        #     component_dirs.add "lib" do |dir|
+        #       dir.default_namespace = "my_app"
+        #     end
+        #
+        #   @see ComponentDir
+        #   @api public
+        #
+        # @overload add(dir)
+        #   Adds a configured component dir
+        #
+        #   @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] = 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)
+          end
+        end
+
+        # 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]
+        #
+        # @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
+
+        # Calls the given block once for each added component dir, passing the dir as an
+        # 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
+
+        # 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)
+          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
+
+        def method_missing(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)
+          defaults.respond_to?(name) || super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "dry/system/constants"
+
+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 public
+      class Namespace
+        ROOT_PATH = nil
+
+        include Dry::Equalizer(:path, :key, :const)
+
+        # @api public
+        attr_reader :path
+
+        # @api public
+        attr_reader :key
+
+        # @api public
+        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
+
+        # @api private
+        def initialize(path:, key:, const:)
+          @path = path
+          # Default keys (i.e. when the user does not explicitly provide one) for non-root
+          # paths will include path separators, which we must convert into key separators
+          @key = key && key == path ? key.gsub(PATH_SEPARATOR, KEY_SEPARATOR) : key
+          @const = const
+        end
+
+        # @api public
+        def root?
+          path == ROOT_PATH
+        end
+
+        # @api public
+        def path?
+          !root?
+        end
+      end
+    end
+  end
+end