convenient_service 0.5.0 → 0.6.0

data/lib/convenient_service/rspec/matchers/custom/delegate_to.rb

@@ -1,291 +1,115 @@
 # frozen_string_literal: true
 
+require_relative "delegate_to/entities"
+
 ##
-# IMPORTANT: This matcher has a dedicated end-user doc. Do NOT forget to update it when needed.
-# https://github.com/marian13/convenient_service_docs/blob/main/docs/api/tests/rspec/matchers/delegate_to.mdx
-#
-# TODO: Refactor into composition:
-#   - Ability to compose when `delegate_to` is used `without_arguments`.
-#   - Ability to compose when `delegate_to` is used `with_arguments`.
-#   - Ability to compose when `delegate_to` is used `and_return_its_value`.
-#
-# TODO: Refactor to NOT use `expect` inside this matcher.
-# This way the matcher will return true or false, but never raise exceptions (descendant of Exception, not StandardError).
-# Then it will be easier to developer a fully comprehensive spec suite for `delegate_to`.
+# @internal
+#   IMPORTANT: This matcher has a dedicated end-user doc. Do NOT forget to update it when needed.
+#   https://github.com/marian13/convenient_service_docs/blob/main/docs/api/tests/rspec/matchers/delegate_to.mdx
 #
 module ConvenientService
   module RSpec
     module Matchers
       module Custom
         ##
-        #   specify {
-        #     expect { method_class.cast(other, **options) }
-        #       .to delegate_to(ConvenientService::Service::Plugins::HasResultSteps::Entities::Method::Commands::CastMethod, :call)
-        #       .with_arguments(other: other, options: options)
-        #       .and_return_its_value
-        #   }
-        #
-        #   { method_class.cast(other, **options) }
-        #   # => block_expectation
-        #
-        #   ConvenientService::Service::Plugins::HasResultSteps::Entities::Method::Commands::CastMethod
-        #   # => object
-        #
-        #   :call
-        #   #=> method
-        #
-        #   (other: other, options: options)
-        #   # => chain[:with]
-        #
-        #   and_return_its_value
-        #   # => chain[:and_return_its_value]
-        #
-        # NOTE: A similar (with different behaviour) matcher exists in `saharspec`.
-        # https://github.com/zverok/saharspec#send_messageobject-method-matcher
+        # @internal
+        #   NOTE: This is a Facade class.
+        #   https://refactoring.guru/design-patterns/facade
         #
         class DelegateTo
+          include Support::Delegate
+
           ##
-          # NOTE: `include ::RSpec::Expectations`.
-          # - https://github.com/rspec/rspec-expectations/blob/v3.11.0/lib/rspec/expectations.rb
-          # - https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/expectations.rb#L60
+          # @return [Boolean]
           #
-          include ::RSpec::Expectations
+          delegate :matches?, to: :matcher
 
           ##
-          # NOTE: `include ::RSpec::Matchers`.
-          # - https://github.com/rspec/rspec-expectations/blob/v3.11.0/lib/rspec/matchers.rb
-          # - https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/matchers.rb
+          # @internal
+          #   NOTE: Required by RSpec.
+          #   https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/custom-matchers/define-a-matcher-supporting-block-expectations
           #
-          include ::RSpec::Matchers
+          delegate :supports_block_expectations?, to: :matcher
 
           ##
-          # NOTE: `include ::RSpec::Mocks::ExampleMethods`.
-          # - https://github.com/rspec/rspec-mocks/blob/v3.11.1/lib/rspec/mocks/example_methods.rb
-          # - https://github.com/rspec/rspec-mocks/blob/main/lib/rspec/mocks/example_methods.rb
+          # @return [String]
           #
-          include ::RSpec::Mocks::ExampleMethods
+          delegate :description, to: :matcher
 
           ##
+          # @return [String]
           #
-          #
-          def initialize(object, method)
-            @object = object
-            @method = method
-          end
+          delegate :failure_message, to: :matcher
 
           ##
+          # @return [String]
           #
-          #
-          def matches?(block_expectation)
-            @block_expectation = block_expectation
-
-            ##
-            # TODO: Support multiple `with_arguments` calls.
-            #
-            if used_with_arguments?
-              ##
-              # NOTE: RSpec `allow(object).to receive(method).with(*args, **kwargs)` does NOT support block.
-              # https://github.com/rspec/rspec-mocks/issues/1182#issuecomment-679820352
-              #
-              # NOTE: RSpec `allow(object).to receive(method) do` does NOT support `and_call_original`.
-              # https://github.com/rspec/rspec-mocks/issues/774#issuecomment-54245277
-              #
-              # NOTE: That is why `and_wrap_original` is used.
-              # https://relishapp.com/rspec/rspec-mocks/docs/configuring-responses/wrapping-the-original-implementation
-              #
-              allow(object).to receive(method).and_wrap_original do |original, *actual_args, **actual_kwargs, &actual_block|
-                actual_arguments_collection << [actual_args, actual_kwargs, actual_block]
-
-                ##
-                # NOTE: Imitates `and_call_original`.
-                #
-                original.call(*actual_args, **actual_kwargs, &actual_block)
-              end
-            else
-              allow(object).to receive(method).and_call_original
-            end
-
-            ##
-            # NOTE: Calls `block_expectation` before checking expections.
-            #
-            value = block_expectation.call
-
-            ##
-            # NOTE: If this expectation fails, it means `delegate_to` is NOT met.
-            #
-            expect(object).to have_received(method).at_least(1) unless used_with_arguments?
-
-            ##
-            # IMPORTANT: `and_return_its_value` works only when `delegate_to` checks a pure function.
-            #
-            # For example (1):
-            #   def require_dependencies_pure
-            #     RequireDependenciesPure.call
-            #   end
-            #
-            #   class RequireDependenciesPure
-            #     def self.call
-            #       dependencies.require!
-            #
-            #       true
-            #     end
-            #   end
-            #
-            #   # Works since `RequireDependenciesPure.call` always returns `true`.
-            #   specify do
-            #     expect { require_dependencies_pure }
-            #       .to delegate_to(RequireDependenciesPure, :call)
-            #       .and_return_its_value
-            #   end
-            #
-            # Example (2):
-            #   def require_dependencies_not_pure
-            #     RequireDependenciesNotPure.call
-            #   end
-            #
-            #   class RequireDependenciesNotPure
-            #     def self.call
-            #       return false if dependencies.required?
-            #
-            #       dependencies.require!
-            #
-            #       true
-            #     end
-            #   end
-            #
-            #   # Does NOT work since `RequireDependenciesNotPure.call` returns `true` for the first time and `false` for the subsequent call.
-            #   specify do
-            #     expect { require_dependencies_not_pure }
-            #       .to delegate_to(RequireDependenciesNotPure, :call)
-            #       .and_return_its_value
-            #   end
-            #
-            # NOTE: If this expectation fails, it means `and_return_its_value` is NOT met.
-            #
-            expect(value).to eq(object.__send__(method, *args, **kwargs, &block)) if used_and_return_its_value?
-
-            ##
-            # IMPORTANT: A matcher should always return a boolean.
-            # https://github.com/zverok/saharspec/blob/master/lib/saharspec/matchers/send_message.rb#L59
-            #
-            # NOTE: RSpec raises exception when any `expect` is NOT satisfied.
-            # So, this `true` is returned only when all `expect` are successful.
-            #
-            if used_with_arguments?
-              actual_arguments_collection.any? do |(actual_args, actual_kwargs, actual_block)|
-                actual_args == expected_args && actual_kwargs == expected_kwargs && actual_block == expected_block
-              end
-            else
-              true
-            end
-          end
+          delegate :failure_message_when_negated, to: :matcher
 
           ##
-          # NOTE: Required by RSpec.
-          # https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/custom-matchers/define-a-matcher-supporting-block-expectations
+          # @overload initialize(object, method)
+          #   @param object [Object]
+          #   @param method [String, Symbol]
+          #   @return [void]
           #
-          def supports_block_expectations?
-            true
+          # @overload initialize(matcher)
+          #   @param matcher [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher]
+          #   @return [void]
+          #   @api private
+          #
+          # @internal
+          #   TODO: `overload do`?
+          #
+          def initialize(object = nil, method = nil, matcher: nil)
+            @matcher = matcher || Entities::Matcher.new(object, method)
           end
 
           ##
+          # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+          # @raise [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Errors::ArgumentsChainingIsAlreadySet]
           #
-          #
-          def description
-            "delegate to `#{printable_method}`"
-          end
+          def with_arguments(...)
+            matcher.with_arguments(...)
 
-          def failure_message
-            if used_with_arguments?
-              "expected `#{printable_block_expectation}` to delegate to `#{printable_method}` with expected arguments at least once, but it didn't."
-            else
-              "expected `#{printable_block_expectation}` to delegate to `#{printable_method}` at least once, but it didn't."
-            end
+            self
           end
 
           ##
-          # IMPORTANT: `failure_message_when_negated` is NOT supported yet.
+          # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+          # @raise [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Errors::ArgumentsChainingIsAlreadySet]
           #
-
-          def with_arguments(*args, **kwargs, &block)
-            chain[:with_arguments] = {args: args, kwargs: kwargs, block: block}
+          def without_arguments
+            matcher.without_arguments
 
             self
           end
 
+          ##
+          # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
+          # @raise [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Errors::ReturnItsValueChainingIsAlreadySet]
+          #
           def and_return_its_value
-            chain[:and_return_its_value] = true
+            matcher.and_return_its_value
 
             self
           end
 
-          def printable_method
-            @printable_method ||=
-              case Utils::Object.resolve_type(object)
-              when "class", "module"
-                "#{object}.#{method}"
-              when "instance"
-                "#{object.class}##{method}"
-              end
-          end
-
-          private
-
-          attr_reader :object, :method, :block_expectation
-
-          def used_with_arguments?
-            chain.key?(:with_arguments)
-          end
-
-          def used_and_return_its_value?
-            chain.key?(:and_return_its_value)
-          end
-
-          def chain
-            @chain ||= {}
-          end
-
-          def args
-            @args ||= chain.dig(:with_arguments, :args) || []
-          end
-
-          alias_method :expected_args, :args
-
-          def kwargs
-            @kwargs ||= chain.dig(:with_arguments, :kwargs) || {}
-          end
-
-          alias_method :expected_kwargs, :kwargs
-
           ##
-          # NOTE: `if defined?` is used in order to cache `nil` if needed.
+          # @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo]
           #
-          def block
-            return @block if defined? @block
+          def without_calling_original
+            matcher.without_calling_original
 
-            @block = chain.dig(:with_arguments, :block)
+            self
           end
 
-          alias_method :expected_block, :block
-
-          def actual_arguments_collection
-            @actual_arguments_collection ||= []
-          end
+          private
 
           ##
-          # NOTE: An example of how RSpec extracts block source, but they marked it as private.
-          # https://github.com/rspec/rspec-expectations/blob/311aaf245f2c5493572bf683b8c441cb5f7e44c8/lib/rspec/matchers/built_in/change.rb#L437
+          # @!attribute [r] matcher
+          #   @return [ConvenientService::RSpec::Matchers::Custom::DelegateTo::Entities::Matcher]
           #
-          # TODO: `printable_block_expectation` when `method_source` is available.
-          # https://github.com/banister/method_source
-          #
-          # def printable_block_expectation
-          #   @printable_block_expectation ||= block_expectation.source
-          # end
-          #
-          def printable_block_expectation
-            @printable_block_expectation ||= "{ ... }"
-          end
+          attr_reader :matcher
         end
       end
     end

data/lib/convenient_service/rspec/matchers/custom/singleton_prepend_module.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Custom
+        ##
+        # @internal
+        #   class User
+        #     include InstanceMethods
+        #
+        #     singleton_class.include ClassMethods # or more common `extend ClassMethods`.
+        #
+        #     prepend InstanceMethods
+        #
+        #     singleton_class.prepend ClassMethods # no short form like `extend`.
+        #   end
+        #
+        class SingletonPrependModule
+          ##
+          # @param mod [Module]
+          # @return [void]
+          #
+          # @internal
+          #   NOTE: `mod` since `module` is a keyword.
+          #
+          def initialize(mod)
+            @mod = mod
+          end
+
+          ##
+          # @param klass [Class, Module]
+          # @return [Boolean]
+          #
+          def matches?(klass)
+            @klass = klass
+
+            klass.singleton_class.ancestors.take_while { |ancestor| ancestor != klass }.include?(mod)
+          end
+
+          ##
+          # @return [String]
+          #
+          def description
+            "`singleton_class.prepend` module `#{mod}`"
+          end
+
+          ##
+          # @return [String]
+          #
+          def failure_message
+            "expected `#{klass}` to `singleton_class.prepend` module `#{mod}`"
+          end
+
+          ##
+          # @return [String]
+          #
+          def failure_message_when_negated
+            "expected `#{klass}` NOT to `singleton_class.prepend` module `#{mod}`"
+          end
+
+          private
+
+          ##
+          # @!attribute [r] klass
+          #   @return [Class, Module]
+          #
+          attr_reader :klass
+
+          ##
+          # @!attribute [r] mod
+          #   @return [Module]
+          #
+          attr_reader :mod
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/custom.rb

@@ -14,3 +14,4 @@ require_relative "custom/have_attr_writer"
 require_relative "custom/include_module"
 require_relative "custom/prepend_module"
 require_relative "custom/results"
+require_relative "custom/singleton_prepend_module"

data/lib/convenient_service/rspec/matchers/singleton_prepend_module.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module SingletonPrependModule
+        def singleton_prepend_module(...)
+          Custom::SingletonPrependModule.new(...)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers.rb

@@ -16,6 +16,7 @@ require_relative "matchers/have_attr_writer"
 require_relative "matchers/include_module"
 require_relative "matchers/prepend_module"
 require_relative "matchers/results"
+require_relative "matchers/singleton_prepend_module"
 
 module ConvenientService
   module RSpec
@@ -37,6 +38,7 @@ module ConvenientService
         include Matchers::IncludeModule
         include Matchers::PrependModule
         include Matchers::Results
+        include Matchers::SingletonPrependModule
       end
     end
   end

data/lib/convenient_service/service/plugins/has_result_steps/concern.rb

@@ -8,6 +8,9 @@ module ConvenientService
           include Support::Concern
 
           instance_methods do
+            ##
+            # @return [Array]
+            #
             def steps
               internals.cache.fetch(:steps) do
                 self.class
@@ -27,6 +30,11 @@ module ConvenientService
           end
 
           class_methods do
+            ##
+            # @params args [Array]
+            # @params kwargs [Hash]
+            # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
+            #
             def step(*args, **kwargs)
               step_class.new(*args, **kwargs.merge(container: self))
                 .tap { |step_instance| steps << step_instance }
@@ -41,14 +49,31 @@ module ConvenientService
             #   # that is converted to the following service invocation:
             #   AssertFeatureEnabled.result(name: :chat_v2)
             #
+            # @param value [Object] Can be any type.
+            # @return [ConvenientService::Support::RawValue]
+            #
             def raw(value)
               Support::RawValue.wrap(value)
             end
 
+            ##
+            # @param method_name [String, Symbol]
+            # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Method::Entities::Values::Reassignment]
+            #
+            def reassign(method_name)
+              Entities::Method::Entities::Values::Reassignment.new(method_name)
+            end
+
+            ##
+            # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::StepCollection]
+            #
             def steps
               @steps ||= Entities::StepCollection.new
             end
 
+            ##
+            # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
+            #
             def step_class
               @step_class ||= Commands::CreateStepClass.call(service_class: self)
             end

data/lib/convenient_service/service/plugins/has_result_steps/entities/method/commands/cast_method.rb

@@ -7,6 +7,9 @@ module ConvenientService
         module Entities
           class Method
             module Commands
+              ##
+              # TODO: Abstract factory.
+              #
               class CastMethod < Support::Command
                 attr_reader :other, :options
 

data/lib/convenient_service/service/plugins/has_result_steps/entities/method/commands/cast_method_caller.rb

@@ -8,7 +8,7 @@ module ConvenientService
           class Method
             module Commands
               ##
-              # TODO: Replace `CastMethodKey`, `CastMethodName`, `CastMethodCaller` by declarative caster?
+              # TODO: Abstract factory.
               #
               class CastMethodCaller < Support::Command
                 attr_reader :other, :options
@@ -23,6 +23,7 @@ module ConvenientService
                   when ::Symbol then cast_symbol
                   when ::String then cast_string
                   when ::Hash then cast_hash
+                  when Entities::Values::Reassignment then cast_reassignment
                   when Method then cast_method
                   end
                 end
@@ -37,6 +38,10 @@ module ConvenientService
                   Entities::Callers::Usual.new(other)
                 end
 
+                def cast_reassignment
+                  Entities::Callers::Reassignment.new(other)
+                end
+
                 def cast_hash
                   return unless other.keys.one?
 
@@ -51,6 +56,8 @@ module ConvenientService
                     Entities::Callers::Proc.new(value)
                   when Support::RawValue
                     Entities::Callers::Raw.new(value)
+                  when Entities::Values::Reassignment
+                    Entities::Callers::Reassignment.new(value)
                   end
                 end
 

data/lib/convenient_service/service/plugins/has_result_steps/entities/method/commands/cast_method_direction.rb

@@ -7,6 +7,9 @@ module ConvenientService
         module Entities
           class Method
             module Commands
+              ##
+              # TODO: Abstract factory.
+              #
               class CastMethodDirection < Support::Command
                 attr_reader :other, :options
 

data/lib/convenient_service/service/plugins/has_result_steps/entities/method/commands/cast_method_key.rb

@@ -8,7 +8,7 @@ module ConvenientService
           class Method
             module Commands
               ##
-              # TODO: Replace `CastMethodKey`, `CastMethodName`, `CastMethodCaller` by declarative caster?
+              # TODO: Abstract factory.
               #
               class CastMethodKey < Support::Command
                 attr_reader :other, :options
@@ -26,6 +26,7 @@ module ConvenientService
                   when ::Symbol then cast_symbol
                   when ::String then cast_string
                   when ::Hash then cast_hash
+                  when Entities::Values::Reassignment then cast_reassignment
                   when Method then cast_method
                   end
                 end
@@ -40,6 +41,10 @@ module ConvenientService
                   Entities::Key.new(other)
                 end
 
+                def cast_reassignment
+                  Entities::Key.new(other.to_sym)
+                end
+
                 def cast_hash
                   return unless other.keys.one?
 
@@ -55,6 +60,8 @@ module ConvenientService
                     Entities::Key.new(key)
                   when Support::RawValue
                     Entities::Key.new(key)
+                  when Entities::Values::Reassignment
+                    Entities::Key.new(key)
                   end
                 end
 

data/lib/convenient_service/service/plugins/has_result_steps/entities/method/commands/cast_method_name.rb

@@ -7,8 +7,8 @@ module ConvenientService
         module Entities
           class Method
             module Commands
-              ##
-              # TODO: Replace `CastMethodKey`, `CastMethodName`, `CastMethodCaller` by declarative caster?
+              #
+              # TODO: Abstract factory.
               #
               class CastMethodName < Support::Command
                 attr_reader :other, :options
@@ -26,6 +26,7 @@ module ConvenientService
                   when ::Symbol then cast_symbol
                   when ::String then cast_string
                   when ::Hash then cast_hash
+                  when Entities::Values::Reassignment then cast_reassignment
                   when Method then cast_method
                   end
                 end
@@ -40,6 +41,10 @@ module ConvenientService
                   Entities::Name.new(other)
                 end
 
+                def cast_reassignment
+                  Entities::Name.new(other.to_sym)
+                end
+
                 def cast_hash
                   return unless other.keys.one?
 
@@ -55,12 +60,11 @@ module ConvenientService
                     Entities::Name.new(key)
                   when Support::RawValue
                     Entities::Name.new(key)
+                  when Entities::Values::Reassignment
+                    Entities::Name.new(value.to_sym)
                   end
                 end
 
-                ##
-                # TODO: Specs.
-                #
                 def cast_method
                   other.name.copy
                 end

data/lib/convenient_service/service/plugins/has_result_steps/entities/method/concern/instance_methods.rb

@@ -38,6 +38,10 @@ module ConvenientService
                   Utils::Bool.to_bool(organizer)
                 end
 
+                def reassignment?(name)
+                  caller.reassignment?(name)
+                end
+
                 def validate_as_input_for_container!(container)
                   direction.validate_as_input_for_container!(container, method: self)
 

data/lib/convenient_service/service/plugins/has_result_steps/entities/method/entities/callers/base.rb

@@ -27,6 +27,10 @@ module ConvenientService
                     @object = object
                   end
 
+                  def reassignment?(name)
+                    false
+                  end
+
                   def ==(other)
                     return unless other.instance_of?(self.class)