dry-system 0.18.1 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7634be14c7b544e14f693cd158cd4cdf072e89ea5c947fafec45a0b31e58eb18
-  data.tar.gz: 34a55fe75bbae237be83dbcf534c0c13947a66788b146ee2ec12a387d3976e38
+  metadata.gz: 2c09b2200301d76a2ac09297583d2a58711db80b43fbe191086bd859f1d3b4fe
+  data.tar.gz: 7f08ad0fb730b2a7281737f799722c30dc649926f36e18e2cd07144637edbb20
 SHA512:
-  metadata.gz: 1802eb1c676eb114126b37fd1ac9607a446317e209de17c62018f6a61bd9dd6770093e673671685c6a8d665ec53c7d7897141c3a7896c4d64ee3f5161c47bc30
-  data.tar.gz: '08fd659802b48151cf10598eb45fcb6555b8f9fa8b55340e6e9f393469608b965ecdefae143e79a880c394bcbede49b719f71f9bf6b96726af73921020121a35'
+  metadata.gz: 646a9ef47bce754608ae670ebb43aaad911e2c8b67d79a10f7c0f284cd379c4ce4992263fb22f48f42768e180cfdb6e9f1a3df8bb590245a9a29579858862000
+  data.tar.gz: 293fddcf0085814fc9628ee77ad6360d04ae076fb8b623117a1a336aceb39be1d5c1a8a44c92f10b7e48ca53e4939284ae91b8e6ed2a3514039f65c15d7d5d54

data/CHANGELOG.md

@@ -1,3 +1,96 @@
+<!--- DO NOT EDIT THIS FILE - IT'S AUTOMATICALLY GENERATED VIA DEVTOOLS --->
+
+## 0.19.0 2021-04-22
+
+This release marks a huge step forward for dry-system, bringing support for Zeitwerk and other autoloaders, plus clearer configuration and improved consistency around component resolution for both finalized and lazy loading containers. [Read the announcement post](https://dry-rb.org/news/2021/04/22/dry-system-0-19-released-with-zeitwerk-support-and-more-leading-the-way-for-hanami-2-0/) for a high-level tour of the new features.
+
+### Added
+
+- New `component_dirs` setting on `Dry::System::Container`, which must be used for specifying the directories which dry-system will search for component source files.
+
+  Each added component dir is relative to the container's `root`, and can have its own set of settings configured:
+
+  ```ruby
+  class MyApp::Container < Dry::System::Container
+    configure do |config|
+      config.root = __dir__
+
+      # Defaults for all component dirs can be configured separately
+      config.component_dirs.auto_register = true # default is already true
+
+      # Component dirs can be added and configured independently
+      config.component_dirs.add "lib" do |dir|
+        dir.add_to_load_path = true # defaults to true
+        dir.default_namespace = "my_app"
+      end
+
+      # All component dir settings are optional. Component dirs relying on default
+      # settings can be added like so:
+      config.component_dirs.add "custom_components"
+    end
+  end
+  ```
+
+  The following settings are available for configuring added `component_dirs`:
+
+  - `auto_register`, a boolean, or a proc accepting a `Dry::System::Component` instance and returning a truthy or falsey value. Providing a proc allows an auto-registration policy to apply on a per-component basis
+  - `add_to_load_path`, a boolean
+  - `default_namespace`, a string representing the leading namespace segments to be stripped from the component's identifier (given the identifier is derived from the component's fully qualified class name)
+  - `loader`, a custom replacement for the default `Dry::System::Loader` to be used for the component dir
+  - `memoize`, a boolean, to enable/disable memoizing all components in the directory, or a proc accepting a `Dry::System::Component` instance and returning a truthy or falsey value. Providing a proc allows a memoization policy to apply on a per-component basis
+
+  _All component dir settings are optional._
+
+  (@timriley in #155, #157, and #162)
+- A new autoloading-friendly `Dry::System::Loader::Autoloading` is available, which is tested to work with [Zeitwerk](https://github.com/fxn/zeitwerk) 🎉
+
+  Configure this on the container (via a component dir `loader` setting), and the loader will no longer `require` any components, instead allowing missing constant resolution to trigger the loading of the required file.
+
+  This loader presumes an autoloading system like Zeitwerk has already been enabled and appropriately configured.
+
+  A recommended setup is as follows:
+
+  ```ruby
+  require "dry/system/container"
+  require "dry/system/loader/autoloading"
+  require "zeitwerk"
+
+  class MyApp::Container < Dry::System::Container
+    configure do |config|
+      config.root = __dir__
+
+      config.component_dirs.loader = Dry::System::Loader::Autoloading
+      config.component_dirs.add_to_load_path = false
+
+      config.component_dirs.add "lib" do |dir|
+        # ...
+      end
+    end
+  end
+
+  loader = Zeitwerk::Loader.new
+  loader.push_dir MyApp::Container.config.root.join("lib").realpath
+  loader.setup
+  ```
+
+  (@timriley in #153)
+- [BREAKING] `Dry::System::Component` instances (which users of dry-system will interact with via custom loaders, as well as via the `auto_register` and `memoize` component dir settings described above) now return a `Dry::System::Identifier` from their `#identifier` method. The raw identifier string may be accessed via the identifier's own `#key` or `#to_s` methods. `Identifier` also provides a helpful namespace-aware `#start_with?` method for returning whether the identifier begins with the provided namespace(s) (@timriley in #158)
+
+### Changed
+
+- Components with `# auto_register: false` magic comments in their source files are now properly ignored when lazy loading (@timriley in #155)
+- `# memoize: true` and `# memoize: false` magic comments at top of component files are now respected (@timriley in #155)
+- [BREAKING] `Dry::System::Container.load_paths!` has been renamed to `.add_to_load_path!`. This method now exists as a mere convenience only. Calling this method is no longer required for any configured `component_dirs`; these are now added to the load path automatically (@timriley in #153 and #155)
+- [BREAKING] `auto_register` container setting has been removed. Configured directories to be auto-registered by adding `component_dirs` instead (@timriley in #155)
+- [BREAKING] `default_namespace` container setting has been removed. Set it when adding `component_dirs` instead (@timriley in #155)
+- [BREAKING] `loader` container setting has been nested under `component_dirs`, now available as `component_dirs.loader` to configure a default loader for all component dirs, as well as on individual component dirs when being added (@timriley in #162)
+- [BREAKING] `Dry::System::ComponentLoadError` is no longer raised when a component could not be lazy loaded; this was only raised in a single specific failure condition. Instead, a `Dry::Container::Error` is raised in all cases of components failing to load (@timriley in #155)
+- [BREAKING] `Dry::System::Container.auto_register!` has been removed. Configure `component_dirs` instead. (@timriley in #157)
+- [BREAKING] The `Dry::System::Loader` interface has changed. It is now a static interface, no longer initialized with a component. The component is instead passed to each method as an argument: `.require!(component)`, `.call(component, *args)`, `.constant(component)` (@timriley in #157)
+- [BREAKING] `Dry::System::Container.require_path` has been removed. Provide custom require behavior by configuring your own `loader` (@timriley in #153)
+
+[Compare v0.18.1...v0.19.0](https://github.com/dry-rb/dry-system/compare/v0.18.1...v0.19.0)
+
 ## 0.18.1 2020-08-26
 
 

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2020 dry-rb team
+Copyright (c) 2015-2021 dry-rb team
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

data/README.md

@@ -21,7 +21,7 @@
 
 This library officially supports the following Ruby versions:
 
-* MRI >= `2.4`
+* MRI >= `2.5`
 * jruby >= `9.2`
 
 ## License

data/dry-system.gemspec

@@ -25,15 +25,14 @@ Gem::Specification.new do |spec|
   spec.metadata['source_code_uri']   = 'https://github.com/dry-rb/dry-system'
   spec.metadata['bug_tracker_uri']   = 'https://github.com/dry-rb/dry-system/issues'
 
-  spec.required_ruby_version = ">= 2.4.0"
+  spec.required_ruby_version = ">= 2.5.0"
 
   # to update dependencies edit project.yml
   spec.add_runtime_dependency "concurrent-ruby", "~> 1.0"
   spec.add_runtime_dependency "dry-auto_inject", ">= 0.4.0"
-  spec.add_runtime_dependency "dry-configurable", "~> 0.11", ">= 0.11.1"
+  spec.add_runtime_dependency "dry-configurable", "~> 0.12", ">= 0.12.1"
   spec.add_runtime_dependency "dry-container", "~> 0.7", ">= 0.7.2"
-  spec.add_runtime_dependency "dry-core", "~> 0.3", ">= 0.3.1"
-  spec.add_runtime_dependency "dry-equalizer", "~> 0.2"
+  spec.add_runtime_dependency "dry-core", "~> 0.5", ">= 0.5"
   spec.add_runtime_dependency "dry-inflector", "~> 0.1", ">= 0.1.2"
   spec.add_runtime_dependency "dry-struct", "~> 1.0"
 

data/lib/dry/system/auto_registrar.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 require "dry/system/constants"
-require "dry/system/magic_comments_parser"
-require "dry/system/auto_registrar/configuration"
+require_relative "component"
 
 module Dry
   module System
@@ -17,83 +16,42 @@ module Dry
     class AutoRegistrar
       attr_reader :container
 
-      attr_reader :config
-
       def initialize(container)
         @container = container
-        @config = container.config
       end
 
       # @api private
       def finalize!
-        Array(config.auto_register).each { |dir| call(dir) }
+        container.component_dirs.each do |component_dir|
+          call(component_dir) if component_dir.auto_register?
+        end
       end
 
       # @api private
-      def call(dir)
-        registration_config = Configuration.new
-        yield(registration_config) if block_given?
-        components(dir).each do |component|
-          next if !component.auto_register? || registration_config.exclude.(component)
+      def call(component_dir)
+        components(component_dir).each do |component|
+          next unless register_component?(component)
 
-          container.require_component(component) do
-            register(component.identifier, memoize: registration_config.memoize) {
-              registration_config.instance.(component)
-            }
-          end
+          container.register(component.identifier, memoize: component.memoize?) { component.instance }
         end
       end
 
       private
 
-      # @api private
-      def components(dir)
-        files(dir)
-          .map { |file_name| [file_name, file_options(file_name)] }
-          .map { |file_name, options| component(relative_path(dir, file_name), **options) }
-          .reject { |component| registered?(component.identifier) }
+      def components(component_dir)
+        files(component_dir.full_path).map { |file_path|
+          component_dir.component_for_path(file_path)
+        }
       end
 
-      # @api private
       def files(dir)
-        components_dir = File.join(root, dir)
-
-        unless ::Dir.exist?(components_dir)
-          raise ComponentsDirMissing, "Components dir '#{components_dir}' not found"
-        end
-
-        ::Dir["#{components_dir}/**/#{RB_GLOB}"].sort
-      end
-
-      # @api private
-      def relative_path(dir, file_path)
-        dir_root = root.join(dir.to_s.split("/")[0])
-        file_path.to_s.sub("#{dir_root}/", "").sub(RB_EXT, EMPTY_STRING)
-      end
+        raise ComponentDirNotFoundError, dir unless Dir.exist?(dir)
 
-      # @api private
-      def file_options(file_name)
-        MagicCommentsParser.(file_name)
-      end
-
-      # @api private
-      def component(path, **options)
-        container.component(path, **options)
+        Dir["#{dir}/**/#{RB_GLOB}"].sort
       end
 
-      # @api private
-      def root
-        container.root
-      end
-
-      # @api private
-      def registered?(name)
-        container.registered?(name)
-      end
-
-      # @api private
-      def register(*args, &block)
-        container.register(*args, &block)
+      def register_component?(component)
+        !container.registered?(component) && component.auto_register?
       end
     end
   end

data/lib/dry/system/booter.rb

@@ -30,17 +30,28 @@ module Dry
         @components = ComponentRegistry.new
       end
 
-      # @api private
-      def bootable?(component)
-        !boot_file(component).nil?
-      end
-
       # @api private
       def register_component(component)
         components.register(component)
         self
       end
 
+      # Returns a bootable component if it can be found or loaded, otherwise nil
+      #
+      # @return [Dry::System::Components::Bootable, nil]
+      # @api private
+      def find_component(name)
+        name = name.to_sym
+
+        return components[name] if components.exists?(name)
+
+        return if finalized?
+
+        require_boot_file(name)
+
+        components[name] if components.exists?(name)
+      end
+
       # @api private
       def finalize!
         boot_files.each do |path|
@@ -54,6 +65,13 @@ module Dry
         freeze
       end
 
+      # @!method finalized?
+      #   Returns true if the booter has been finalized
+      #
+      #   @return [Boolean]
+      #   @api private
+      alias_method :finalized?, :frozen?
+
       # @api private
       def shutdown
         components.each do |component|
@@ -115,12 +133,19 @@ module Dry
 
       # @api private
       def boot_dependency(component)
-        boot_file = boot_file(component)
-
-        start(boot_file.basename(".*").to_s.to_sym) if boot_file
+        if (component = find_component(component.root_key))
+          start(component)
+        end
       end
 
-      # @api private
+      # Returns all boot files within the configured paths
+      #
+      # Searches for files in the order of the configured paths. In the case of multiple
+      # identically-named boot files within different paths, the file found first will be
+      # returned, and other matching files will be discarded.
+      #
+      # @return [Array<Pathname>]
+      # @api public
       def boot_files
         @boot_files ||= paths.each_with_object([[], []]) { |path, (boot_files, loaded)|
           files = Dir["#{path}/#{RB_GLOB}"].sort
@@ -161,12 +186,6 @@ module Dry
         self
       end
 
-      def boot_file(name)
-        name = name.respond_to?(:root_key) ? name.root_key.to_s : name
-
-        find_boot_file(name)
-      end
-
       def require_boot_file(identifier)
         boot_file = find_boot_file(identifier)
 

data/lib/dry/system/component.rb

@@ -2,11 +2,12 @@
 
 require "concurrent/map"
 
-require "dry-equalizer"
+require "dry/core/equalizer"
 require "dry/inflector"
 require "dry/system/loader"
 require "dry/system/errors"
 require "dry/system/constants"
+require_relative "identifier"
 
 module Dry
   module System
@@ -14,106 +15,62 @@ module Dry
     # They expose an API to query this information and use a configurable
     # loader object to initialize class instances.
     #
-    # Components are created automatically through auto-registration and can be
-    # accessed through `Container.auto_register!` which yields them.
-    #
     # @api public
     class Component
-      include Dry::Equalizer(:identifier, :path)
+      include Dry::Equalizer(:identifier, :file_path, :options)
 
       DEFAULT_OPTIONS = {
         separator: DEFAULT_SEPARATOR,
-        namespace: nil,
-        inflector: Dry::Inflector.new
+        inflector: Dry::Inflector.new,
+        loader: Loader
       }.freeze
 
       # @!attribute [r] identifier
       #   @return [String] component's unique identifier
       attr_reader :identifier
 
-      # @!attribute [r] path
-      #   @return [String] component's relative path
-      attr_reader :path
-
-      # @!attribute [r] file
-      #   @return [String] component's file name
-      attr_reader :file
+      # @!attribute [r] file_path
+      #   @return [String, nil] full path to the component's file, if found
+      attr_reader :file_path
 
       # @!attribute [r] options
       #   @return [Hash] component's options
       attr_reader :options
 
-      # @!attribute [r] loader
-      #   @return [Object#call] component's loader object
-      attr_reader :loader
-
       # @api private
-      def self.new(*args, &block)
-        cache.fetch_or_store([*args, block].hash) do
-          name, options = args
-          options = DEFAULT_OPTIONS.merge(options || EMPTY_HASH)
-
-          ns, sep, inflector = options.values_at(:namespace, :separator, :inflector)
-          identifier = extract_identifier(name, ns, sep)
-
-          path = name.to_s.gsub(sep, PATH_SEPARATOR)
-          loader = options.fetch(:loader, Loader).new(path, inflector)
-
-          super(identifier, path, options.merge(loader: loader))
-        end
-      end
-
-      # @api private
-      def self.extract_identifier(name, ns, sep)
-        name_s = name.to_s
-        identifier = ns ? remove_namespace_from_name(name_s, ns) : name_s
-
-        identifier.scan(WORD_REGEX).join(sep)
-      end
-
-      # @api private
-      def self.remove_namespace_from_name(name, ns)
-        match_value = name.match(/^(?<remove_namespace>#{ns})(?<separator>\W)(?<identifier>.*)/)
-
-        match_value ? match_value[:identifier] : name
+      def self.new(identifier, options = EMPTY_HASH)
+        options = DEFAULT_OPTIONS.merge(options)
+
+        namespace = options.delete(:namespace)
+        separator = options.delete(:separator)
+
+        identifier =
+          if identifier.is_a?(Identifier)
+            identifier
+          else
+            Identifier.new(
+              identifier,
+              namespace: namespace,
+              separator: separator
+            )
+          end
+
+        super(identifier, **options)
       end
 
       # @api private
-      def self.cache
-        @cache ||= Concurrent::Map.new
-      end
-
-      # @api private
-      def initialize(identifier, path, options)
+      def initialize(identifier, file_path: nil, **options)
         @identifier = identifier
-        @path = path
+        @file_path = file_path
         @options = options
-        @file = "#{path}#{RB_EXT}"
-        @loader = options.fetch(:loader)
-        freeze
       end
 
-      # Returns components instance
-      #
-      # @example
-      #   class MyApp < Dry::System::Container
-      #     configure do |config|
-      #       config.name = :my_app
-      #       config.root = Pathname('/my/app')
-      #     end
-      #
-      #     auto_register!('lib/clients') do |component|
-      #       # some custom initialization logic, ie:
-      #       constant = component.loader.constant
-      #       constant.create
-      #     end
-      #   end
+      # Returns the component's instance
       #
       # @return [Object] component's class instance
-      #
       # @api public
       def instance(*args)
-        loader.call(*args)
+        loader.call(self, *args)
       end
       ruby2_keywords(:instance) if respond_to?(:ruby2_keywords, true)
 
@@ -122,49 +79,54 @@ module Dry
         false
       end
 
-      # @api private
-      def file_exists?(paths)
-        paths.any? { |path| path.join(file).exist? }
+      def key
+        identifier.to_s
       end
 
-      # @api private
-      def prepend(name)
-        self.class.new(
-          [name, identifier].join(separator), options.merge(loader: loader.class)
-        )
+      def path
+        identifier.path
+      end
+
+      def root_key
+        identifier.root_key
       end
 
+      # Returns true if the component has a corresponding file
+      #
+      # @return [Boolean]
       # @api private
-      def namespaced(namespace)
-        self.class.new(
-          path, options.merge(loader: loader.class, namespace: namespace)
-        )
+      def file_exists?
+        !!file_path
       end
 
       # @api private
-      def separator
-        options[:separator]
+      def loader
+        options[:loader]
       end
 
       # @api private
-      def namespace
-        options[:namespace]
+      def inflector
+        options[:inflector]
       end
 
       # @api private
       def auto_register?
-        !!options.fetch(:auto_register) { true }
+        callable_option?(options[:auto_register])
       end
 
       # @api private
-      def root_key
-        namespaces.first
+      def memoize?
+        callable_option?(options[:memoize])
       end
 
       private
 
-      def namespaces
-        identifier.split(separator).map(&:to_sym)
+      def callable_option?(value)
+        if value.respond_to?(:call)
+          !!value.call(self)
+        else
+          !!value
+        end
       end
     end
   end