convenient_service 0.12.0 → 0.13.0

data/lib/convenient_service/core/concern/class_methods.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Concern
+      module ClassMethods
+        ##
+        # @see ConvenientService::Core::Entities::Config#concerns
+        #
+        # @internal
+        #   NOTE: The instance variable is named `@__convenient_service_config__` intentionally in order to decrease the possibility of accidental redefinition by the end-user.
+        #   NOTE: An `attr_reader` for `@__convenient_service_config__` is NOT created intentionally in order to NOT pollute the end-user class interface.
+        #
+        def concerns(...)
+          (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).concerns(...)
+        end
+
+        ##
+        # @see ConvenientService::Core::Entities::Config#middlewares
+        #
+        # @internal
+        #   NOTE: The instance variable is named `@__convenient_service_config__` intentionally in order to decrease the possibility of accidental redefinition by the end-user.
+        #   NOTE: An `attr_reader` for `@__convenient_service_config__` is NOT created intentionally in order to NOT pollute the end-user class interface.
+        #
+        def middlewares(...)
+          (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).middlewares(...)
+        end
+
+        ##
+        # @return [Boolean] Returns `true` when config is committed, otherwise - `false`.
+        #
+        def has_committed_config?
+          (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).committed?
+        end
+
+        ##
+        # Commits config when called for the first time.
+        # Does nothing for the subsequent calls.
+        #
+        # @param trigger [ConvenientService::Support::UniqueValue]
+        # @return [Boolean] `true` if called for the first time, `false` otherwise (similarly as `Kernel#require`).
+        #
+        # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-require
+        #
+        # @internal
+        #   NOTE: The instance variable is named `@__convenient_service_config__` intentionally in order to decrease the possibility of accidental redefinition by the end-user.
+        #   NOTE: An `attr_reader` for `@__convenient_service_config__` is NOT created intentionally in order to NOT pollute the end-user class interface.
+        #
+        def commit_config!(trigger: ConvenientService::Core::Constants::Triggers::USER)
+          (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).commit!(trigger: trigger)
+            .tap { ConvenientService.logger.debug { "[Core] Committed config for `#{self}` | Triggered by `.commit_config!(trigger: #{trigger.inspect})` " } }
+        end
+
+        ##
+        # @internal
+        #   TODO: Create `def uncommit_config` that raises an explanatory exception why the "uncommitment" is NOT possible (because Ruby can NOT "uninclude" modules).
+        ##
+
+        ##
+        # @param args [Array<Object>]
+        # @param kwargs [Hash{Symbol => Object}]
+        # @param block [Proc, nil]
+        # @return [Object] Can be any type.
+        #
+        def new(*args, **kwargs, &block)
+          has_committed_config? ? super : method_missing(:new, *args, **kwargs, &block)
+        end
+
+        private
+
+        ##
+        # @see https://thoughtbot.com/blog/always-define-respond-to-missing-when-overriding
+        # @see https://stackoverflow.com/a/3304683/12201472
+        #
+        # @param method_name [Symbol, String]
+        # @param include_private [Boolean]
+        # @return [Boolean]
+        #
+        # @internal
+        #   IMPORTANT: `respond_to_missing?` is like `initialize`. It is always `private`.
+        #   - https://ruby-doc.org/core-2.7.0/Object.html#method-i-respond_to_missing-3F
+        #   - https://github.com/ruby/spec/blob/master/language/def_spec.rb#L65
+        #
+        def respond_to_missing?(method_name, include_private = false)
+          return true if singleton_class.method_defined?(method_name)
+          return true if concerns.class_method_defined?(method_name)
+
+          if include_private
+            return true if singleton_class.private_method_defined?(method_name)
+            return true if concerns.private_class_method_defined?(method_name)
+          end
+
+          false
+        end
+
+        ##
+        # Commits config. In other words, includes `concerns` into the mixing class.
+        # If `method` is still NOT defined, raises `NoMethodError`, otherwise - retries to call the `method`.
+        #
+        # @param method [Symbol]
+        # @param args [Array<Object>]
+        # @param kwargs [Hash{Symbol => Object}]
+        # @param block [Proc, nil]
+        # @return [void]
+        #
+        # @note Config commitment via a missing class method is very common. Convenient Service Standard config does that by `.new`, `.result` and `.step` most of the time.
+        #
+        # @internal
+        #   IMPORTANT: `method_missing` MUST be thread-safe.
+        #
+        #   NOTE: `__send__` is used instead of `Support::SafeMethod` intentionally, since checking whether a method is defined is performed earlier by `Utils::Module.class_method_defined?`.
+        #
+        #   TODO: Include `method` into trigger metadata.
+        #
+        def method_missing(method, *args, **kwargs, &block)
+          commit_config!(trigger: Constants::Triggers::CLASS_METHOD_MISSING)
+
+          return super unless Utils::Module.class_method_defined?(self, method, public: true, protected: false, private: false)
+
+          return super if middlewares(method, scope: :class).defined_without_super_method?
+
+          ConvenientService.logger.debug { "[Core] Committed config for `#{self}` | Triggered by `method_missing` | Method: `.#{method}`" }
+
+          __send__(method, *args, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/concern/instance_methods.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Concern
+      module InstanceMethods
+        ##
+        # @return [void]
+        #
+        # @internal
+        #   NOTE: required by `.new` in `ClassMethods`.
+        #
+        def initialize(...)
+        end
+
+        private
+
+        ##
+        # @see https://thoughtbot.com/blog/always-define-respond-to-missing-when-overriding
+        # @see https://stackoverflow.com/a/3304683/12201472
+        #
+        # @param method_name [Symbol, String]
+        # @param include_private [Boolean]
+        # @return [Boolean]
+        #
+        # @internal
+        #   IMPORTANT: `respond_to_missing?` is like `initialize`. It is always `private`.
+        #   - https://ruby-doc.org/core-2.7.0/Object.html#method-i-respond_to_missing-3F
+        #   - https://github.com/ruby/spec/blob/master/language/def_spec.rb#L65
+        #
+        def respond_to_missing?(method_name, include_private = false)
+          return true if self.class.method_defined?(method_name)
+          return true if self.class.concerns.instance_method_defined?(method_name)
+
+          if include_private
+            return true if self.class.private_method_defined?(method_name)
+            return true if self.class.concerns.private_instance_method_defined?(method_name)
+          end
+
+          false
+        end
+
+        ##
+        # Commits config. In other words, includes `concerns` into the mixing class.
+        # If `method` is still NOT defined, raises `NoMethodError`, otherwise - retries to call the `method`.
+        #
+        # @param method [Symbol]
+        # @param args [Array<Object>]
+        # @param kwargs [Hash{Symbol => Object}]
+        # @param block [Proc, nil]
+        # @return [void]
+        #
+        # @note Config commitment via a missing instance method is very rare. It is only possible when an instance is created without calling `.new` on a class.
+        #
+        # @internal
+        #   IMPORTANT: `method_missing` MUST be thread-safe.
+        #
+        #   NOTE: `__send__` is used instead of `Support::SafeMethod` intentionally, since checking whether a method is defined is performed earlier by `Utils::Module.instance_method_defined?`.
+        #
+        #   TODO: Include `method` into trigger metadata.
+        #
+        def method_missing(method, *args, **kwargs, &block)
+          self.class.commit_config!(trigger: Constants::Triggers::INSTANCE_METHOD_MISSING)
+
+          return super unless Utils::Module.instance_method_defined?(self.class, method, public: true, protected: false, private: false)
+
+          return super if self.class.middlewares(method, scope: :instance).defined_without_super_method?
+
+          ConvenientService.logger.debug { "[Core] Committed config for `#{self.class}` | Triggered by `method_missing` | Method: `##{method}`" }
+
+          __send__(method, *args, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/concern.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "concern/instance_methods"
+require_relative "concern/class_methods"
+
+module ConvenientService
+  module Core
+    module Concern
+      include Support::Concern
+
+      included do |entity_class|
+        ##
+        # NOTE: Currently this aliasing is tested indirectly by `HasConstructor`.
+        #
+        # TODO: Direct test when `have_alias_method` starts to support classes.
+        #
+        entity_class.singleton_class.alias_method :new_without_commit_config, :new
+
+        entity_class.include InstanceMethods
+
+        entity_class.extend ClassMethods
+      end
+    end
+  end
+end

data/lib/convenient_service/core/entities/config/commands/track_method_missing_commit_trigger.rb

@@ -35,7 +35,7 @@ module ConvenientService
               return unless method_missing_trigger_valid?
               return if method_missing_commits_counter_incremented?
 
-              raise Errors::TooManyCommitsFromMethodMissing.new(config: config)
+              raise Exceptions::TooManyCommitsFromMethodMissing.new(config: config)
             end
 
             ##
@@ -49,7 +49,7 @@ module ConvenientService
             # @return [Boolean]
             #
             def method_missing_commits_counter_incremented?
-              Utils::Object.memoize_including_falsy_values(self, :@method_missing_commits_counter_incremented) { config.method_missing_commits_counter.bincrement }
+              Utils.memoize_including_falsy_values(self, :@method_missing_commits_counter_incremented) { config.method_missing_commits_counter.bincrement }
             end
 
             ##

data/lib/convenient_service/core/entities/config/entities/concerns/entities/middleware/commands/cast_middleware.rb

@@ -28,9 +28,9 @@ module ConvenientService
                     # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Middleware, nil]
                     #
                     def call
-                      if other.instance_of?(Class) && other < Entities::Middleware
+                      if other.instance_of?(::Class) && other < Entities::Middleware
                         cast_middleware(other)
-                      elsif other.instance_of?(Module)
+                      elsif other.instance_of?(::Module)
                         cast_module(other)
                       end
                     end

data/lib/convenient_service/core/entities/config/entities/concerns/entities/middleware.rb

@@ -24,6 +24,7 @@ module ConvenientService
                   ##
                   # @internal
                   #   TODO: Why regular `include Support::AbstractMethod` does NOT work?.
+                  #   NOTE: That is probably happening since the `included` block is evaluated once per hierarchy.
                   #
                   extend Support::AbstractMethod::ClassMethods
 

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/cast_caller.rb

@@ -47,9 +47,9 @@ module ConvenientService
 
                       case hash[:scope]
                       when :instance
-                        Caller.new(prefix: Caller::INSTANCE_PREFIX)
+                        Caller.new(prefix: Constants::INSTANCE_PREFIX)
                       when :class
-                        Caller.new(prefix: Caller::CLASS_PREFIX)
+                        Caller.new(prefix: Constants::CLASS_PREFIX)
                       end
                     end
 

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/concern/instance_methods.rb

@@ -49,10 +49,17 @@ module ConvenientService
                     end
 
                     ##
-                    # @return [Hash]
+                    # @return [Hash{Symbol => Object}]
                     #
                     def to_kwargs
-                      {prefix: prefix}
+                      to_arguments.kwargs
+                    end
+
+                    ##
+                    # @return [ConvenientService::Support::Arguments]
+                    #
+                    def to_arguments
+                      Support::Arguments.new(prefix: prefix)
                     end
                   end
                 end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/constants.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "concern/instance_methods"
+require_relative "concern/class_methods"
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              class Caller
+                module Constants
+                  INSTANCE_PREFIX = "self.class."
+
+                  CLASS_PREFIX = ""
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller.rb

@@ -2,6 +2,7 @@
 
 require_relative "caller/commands"
 require_relative "caller/concern"
+require_relative "caller/constants"
 
 module ConvenientService
   module Core
@@ -11,9 +12,6 @@ module ConvenientService
           class MethodMiddlewares
             module Entities
               class Caller
-                INSTANCE_PREFIX = "self.class."
-                CLASS_PREFIX = ""
-
                 include Concern
               end
             end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/container/concern/instance_methods.rb

@@ -37,7 +37,7 @@ module ConvenientService
                     # @return [UnboundMethod, nil]
                     #
                     def super_method_defined?(method_name)
-                      Utils::Bool.to_bool(resolve_unbound_super_method(method_name))
+                      Utils.to_bool(resolve_unbound_super_method(method_name))
                     end
 
                     ##
@@ -148,10 +148,17 @@ module ConvenientService
                     end
 
                     ##
-                    # @return [Hash]
+                    # @return [Hash{Symbol => Object}]
                     #
                     def to_kwargs
-                      {klass: klass}
+                      to_arguments.kwargs
+                    end
+
+                    ##
+                    # @return [ConvenientService::Support::Arguments]
+                    #
+                    def to_arguments
+                      Support::Arguments.new(klass: klass)
                     end
                   end
                 end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware_creators/base.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module MiddlewareCreators
+                class Base
+                  include Support::Delegate
+
+                  ##
+                  # @!attribute [r] middleware
+                  #   @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                  #
+                  attr_reader :middleware
+
+                  ##
+                  # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                  #
+                  delegate :to_observable_middleware, to: :middleware
+
+                  ##
+                  # @return [void]
+                  #
+                  # @internal
+                  #   TODO: Verbose exception.
+                  #
+                  def initialize(**kwargs)
+                    @middleware = kwargs.fetch(:middleware)
+                  end
+
+                  ##
+                  # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::MiddlewareCreators::With]
+                  #
+                  def with(...)
+                    Entities::MiddlewareCreators::With.new(middleware: self, middleware_arguments: Support::Arguments.new(...))
+                  end
+
+                  ##
+                  # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::MiddlewareCreators::Observable]
+                  #
+                  def observable
+                    Entities::MiddlewareCreators::Observable.new(middleware: self)
+                  end
+
+                  ##
+                  # @param stack [#call<Hash>]
+                  # @param kwargs [Hash{Symbol => Object}]
+                  # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                  #
+                  def new(stack, **kwargs)
+                    decorated_middleware.new(stack, **[extra_kwargs, middleware.extra_kwargs, kwargs].reduce(:merge))
+                  end
+
+                  ##
+                  # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                  #
+                  # @note May be overridden by descendants.
+                  #
+                  def decorated_middleware
+                    middleware
+                  end
+
+                  ##
+                  # @return [Hash{Symbol => Object}]
+                  #
+                  # @note May be overridden by descendants.
+                  #
+                  def extra_kwargs
+                    {}
+                  end
+
+                  ##
+                  # @param other [Object]
+                  # @return [Boolean, nil]
+                  #
+                  def ==(other)
+                    return unless other.instance_of?(self.class)
+
+                    return false if middleware != other.middleware
+
+                    true
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware_creators/observable/entities/event.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module MiddlewareCreators
+                class Observable < MiddlewareCreators::Base
+                  module Entities
+                    class Event
+                      include ::Observable
+
+                      ##
+                      # @!attribute [r] type
+                      #   @return [Symbol]
+                      #
+                      attr_reader :type
+
+                      ##
+                      # @param type [Symbol]
+                      # @return [void]
+                      #
+                      def initialize(type:)
+                        @type = type
+                      end
+
+                      ##
+                      # @return [String]
+                      #
+                      def default_handler_name
+                        "handle_#{type}"
+                      end
+
+                      ##
+                      # @param observer [Object] Can be any type.
+                      # @return [void]
+                      #
+                      # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html#method-i-add_observer
+                      #
+                      def add_observer(observer, func = default_handler_name)
+                        super
+                      end
+
+                      ##
+                      # @return [void]
+                      #
+                      # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html#method-i-changed
+                      # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html#method-i-notify_observers
+                      #
+                      def notify_observers(...)
+                        changed
+
+                        super
+                      end
+
+                      ##
+                      # @param other [Object] Can be any type.
+                      # @return [Boolean, nil]
+                      #
+                      def ==(other)
+                        return unless other.instance_of?(self.class)
+
+                        return false if type != other.type
+                        return false if observer_peers != other.observer_peers
+
+                        true
+                      end
+
+                      protected
+
+                      ##
+                      # @return [Hash]
+                      #
+                      # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html#method-i-count_observers
+                      #
+                      # @internal
+                      #   IMPORTANT: This method is using inherited private instance varaible. Ruby may change its name without any warning.
+                      #
+                      def observer_peers
+                        @observer_peers if defined? @observer_peers
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware_creators/observable/entities.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "entities/event"

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware_creators/observable.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "observable/entities"
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module MiddlewareCreators
+                class Observable < MiddlewareCreators::Base
+                  ##
+                  # @return [Hash{Symbol => ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::MiddlewareCreators::Observable::Entities::Event}]
+                  #
+                  def middleware_events
+                    @middleware_events ||= ::Hash.new { |hash, key| hash[key] = Entities::Event.new(type: key) }
+                  end
+
+                  ##
+                  # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+                  #
+                  def decorated_middleware
+                    middleware.to_observable_middleware
+                  end
+
+                  ##
+                  # @return [Hash{Symbol => Hash{Symbol => ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::MiddlewareCreators::Observable::Entities::Event}}]
+                  #
+                  def extra_kwargs
+                    {middleware_events: middleware_events}
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware_creators/with.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module MiddlewareCreators
+                class With < MiddlewareCreators::Base
+                  ##
+                  # @!attribute [r] middleware_arguments
+                  #   @return [ConvenientService::Support::Arguments]
+                  #
+                  attr_reader :middleware_arguments
+
+                  ##
+                  # @param kwargs [Hash{Symbol => ConvenientService::Support::Arguments}]
+                  # @return [void]
+                  #
+                  def initialize(**kwargs)
+                    super
+
+                    @middleware_arguments = kwargs.fetch(:middleware_arguments) { Support::Arguments.null_arguments }
+                  end
+
+                  ##
+                  # @return [Hash{Symbol => ConvenientService::Support::Arguments}]
+                  #
+                  def extra_kwargs
+                    {middleware_arguments: middleware_arguments}
+                  end
+
+                  ##
+                  # @param other [Object] Can be any type.
+                  # @return [Boolean, nil]
+                  #
+                  def ==(other)
+                    super && Utils.to_bool(middleware_arguments == other.middleware_arguments)
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware_creators.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "middleware_creators/base"
+
+require_relative "middleware_creators/observable"
+require_relative "middleware_creators/with"