convenient_service 0.12.0 → 0.13.0

data/lib/convenient_service/rspec/helpers/custom/wrap_method/entities/wrapped_method.rb

@@ -14,49 +14,83 @@ module ConvenientService
             #
             class WrappedMethod
               ##
-              # @param entity [Object, Class]
+              # @!attribute [r] entity
+              #   @return [Object] Can be any type.
+              #
+              attr_reader :entity
+
+              ##
+              # @!attribute [r] method
+              #   @return [Symbol, String]
+              #
+              attr_reader :method
+
+              ##
+              # @!attribute [r] observe_middleware
+              #   @return [Class]
+              #
+              attr_reader :observe_middleware
+
+              ##
+              # @param entity [Object] Can be any type.
               # @param method [String]
-              # @param middlewares [Array<ConvenientService::Core::MethodChainMiddleware>]
+              # @param observe_middleware [Class]
               # @return [void]
               #
-              # @internal
-              #   NOTE: `middlewares` are `MethodChainMiddleware` classes.
-              #
-              def initialize(entity:, method:, middlewares:)
+              def initialize(entity:, method:, observe_middleware:)
                 @entity = entity
                 @method = method
-                @middlewares = middlewares
-
-                @stack = Support::Middleware::StackBuilder.new do |stack|
-                  middlewares.each { |middleware| stack.use middleware }
-
-                  ##
-                  # NOTE: The following proc middleware is triggered only when `chain.next` is called from method chain middleware.
-                  #
-                  stack.use(
-                    proc do |env|
-                      @chain_arguments = {args: env[:args], kwargs: env[:kwargs], block: env[:block]}
-
-                      ##
-                      # IMPORTANT: Forces Ruby to define `@chain_value` instance variable.
-                      #
-                      # NOTE: If `@chain_value` is still set to `Support::UNDEFINED` after running the begin block - an exception was raised by `chain.next`. See `chain_called?` for more info.
-                      #
-                      @chain_value = Support::UNDEFINED
-
-                      begin
-                        @chain_value = entity.__send__(method, *env[:args], **env[:kwargs], &env[:block])
-                      rescue => exception
-                        @chain_exception = exception
-
-                        ##
-                        # NOTE: `raise` with no args inside `rescue` reraises rescued exception.
-                        #
-                        raise
-                      end
-                    end
-                  )
-                end
+                @observe_middleware = observe_middleware
+
+                ##
+                # TODO: When middleware is NOT used yet.
+                #
+                observable_middleware.middleware_events[:before_chain_next].add_observer(self)
+                observable_middleware.middleware_events[:after_chain_next].add_observer(self)
+
+                ##
+                # TODO: Consider `ObjectSpace.define_finalizer`? Is it really needed?
+                #
+                # observable_middleware.middleware_events[:before_chain_next].delete_observer(self)
+                # observable_middleware.middleware_events[:after_chain_next].delete_observer(self)
+              end
+
+              ##
+              # @internal
+              #   NOTE: The following handler is triggered only when `chain.next` is called from method chain middleware.
+              #
+              def handle_before_chain_next(arguments)
+                @chain_called = true
+                @chain_arguments = arguments
+              end
+
+              ##
+              # @internal
+              #   NOTE: The following handler is triggered only when `chain.next` is called from method chain middleware.
+              #
+              def handle_after_chain_next(value, _arguments)
+                @chain_value = value
+              end
+
+              ##
+              # @return [String]
+              #
+              def scope
+                @scope ||= Utils::Object.resolve_type(entity).to_sym
+              end
+
+              ##
+              # @return [Class]
+              #
+              def klass
+                @klass ||= Utils::Object.clamp_class(entity)
+              end
+
+              ##
+              # @return [Class]
+              #
+              def observable_middleware
+                @observable_middleware ||= klass.middlewares(method, scope: scope).to_a.find { |other| other == observe_middleware.observable }
               end
 
               ##
@@ -66,73 +100,96 @@ module ConvenientService
               # @return [Object] Can be any type.
               #
               def call(*args, **kwargs, &block)
-                @stack.call(entity: @entity, method: @method, args: args, kwargs: kwargs, block: block)
+                entity.__send__(method, *args, **kwargs, &block)
+              rescue => exception
+                @chain_exception = exception
+
+                ##
+                # NOTE: `raise` with no args inside `rescue` reraises rescued exception.
+                #
+                raise
               end
 
               ##
               # @return [void]
               #
               def reset!
+                remove_instance_variable(:@chain_called) if defined? @chain_called
                 remove_instance_variable(:@chain_value) if defined? @chain_value
                 remove_instance_variable(:@chain_arguments) if defined? @chain_arguments
+                remove_instance_variable(:@chain_exception) if defined? @chain_exception
               end
 
               ##
               # @return [Boolean]
               #
               def chain_called?
-                Utils::Bool.to_bool(defined? @chain_value)
+                Utils.to_bool(defined? @chain_called)
               end
 
               ##
               # @return [Object] Can be any type.
-              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Errors::ChainAttributePreliminaryAccess]
+              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Exceptions::ChainAttributePreliminaryAccess]
               #
               def chain_value
-                raise Errors::ChainAttributePreliminaryAccess.new(attribute: :value) unless chain_called?
+                raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :value) unless chain_called?
 
                 @chain_value
               end
 
               ##
               # @return [Array]
-              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Errors::ChainAttributePreliminaryAccess]
+              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Exceptions::ChainAttributePreliminaryAccess]
               #
               def chain_args
-                raise Errors::ChainAttributePreliminaryAccess.new(attribute: :args) unless chain_called?
+                raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :args) unless chain_called?
 
-                @chain_arguments[:args]
+                @chain_arguments.args
               end
 
               ##
               # @return [Hash]
-              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Errors::ChainAttributePreliminaryAccess]
+              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Exceptions::ChainAttributePreliminaryAccess]
               #
               def chain_kwargs
-                raise Errors::ChainAttributePreliminaryAccess.new(attribute: :kwargs) unless chain_called?
+                raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :kwargs) unless chain_called?
 
-                @chain_arguments[:kwargs]
+                @chain_arguments.kwargs
               end
 
               ##
               # @return [Proc, nil]
-              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Errors::ChainAttributePreliminaryAccess]
+              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Exceptions::ChainAttributePreliminaryAccess]
               #
               def chain_block
-                raise Errors::ChainAttributePreliminaryAccess.new(attribute: :block) unless chain_called?
+                raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :block) unless chain_called?
 
-                @chain_arguments[:block]
+                @chain_arguments.block
               end
 
               ##
               # @return [StandardError, nil]
-              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Errors::ChainAttributePreliminaryAccess]
+              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Exceptions::ChainAttributePreliminaryAccess]
               #
               def chain_exception
-                raise Errors::ChainAttributePreliminaryAccess.new(attribute: :exception) unless chain_called?
+                raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :exception) unless chain_called?
 
                 @chain_exception
               end
+
+              ##
+              # @param other [Object] Can be any type.
+              # @return [Boolean, nil]
+              #
+              def ==(other)
+                return unless other.instance_of?(self.class)
+
+                return false if entity != other.entity
+                return false if method != other.method
+                return false if observe_middleware != other.observe_middleware
+
+                true
+              end
             end
           end
         end

data/lib/convenient_service/rspec/helpers/custom/wrap_method/{errors.rb → exceptions.rb}

@@ -5,8 +5,8 @@ module ConvenientService
     module Helpers
       module Custom
         class WrapMethod < Support::Command
-          module Errors
-            class ChainAttributePreliminaryAccess < ::ConvenientService::Error
+          module Exceptions
+            class ChainAttributePreliminaryAccess < ::ConvenientService::Exception
               ##
               # @param attribute [Symbol]
               # @return [void]

data/lib/convenient_service/rspec/helpers/custom/wrap_method.rb

@@ -1,24 +1,48 @@
 # frozen_string_literal: true
 
 require_relative "wrap_method/entities"
-require_relative "wrap_method/errors"
+require_relative "wrap_method/exceptions"
 
 module ConvenientService
   module RSpec
     module Helpers
       module Custom
-        ##
-        # TODO: Specs.
-        #
         class WrapMethod < Support::Command
-          def initialize(entity, method, middlewares:)
+          ##
+          # @!attribute [r] entity
+          #   @return [Object] Can be any type.
+          #
+          attr_reader :entity
+
+          ##
+          # @!attribute [r] method
+          #   @return [Symbol, String]
+          #
+          attr_reader :method
+
+          ##
+          # @!attribute [r] observe_middleware
+          #   @return [Class]
+          #
+          attr_reader :observe_middleware
+
+          ##
+          # @param entity [Object] Can be any type.
+          # @param method [Symbol, String]
+          # @param observe_middleware [Class]
+          # @return [void]
+          #
+          def initialize(entity, method, observe_middleware:)
             @entity = entity
             @method = method
-            @middlewares = Utils::Array.wrap(middlewares)
+            @observe_middleware = observe_middleware
           end
 
+          ##
+          # @return [ConvenientService::RSpec::Helpers::Custom::Entities::WrappedMethod]
+          #
           def call
-            Entities::WrappedMethod.new(entity: @entity, method: @method, middlewares: @middlewares)
+            Entities::WrappedMethod.new(entity: entity, method: method, observe_middleware: observe_middleware)
           end
         end
       end

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "custom/ignoring_error"
+require_relative "custom/ignoring_exception"
 require_relative "custom/in_threads"
 require_relative "custom/stub_service"
 require_relative "custom/wrap_method"

data/lib/convenient_service/rspec/helpers/{ignoring_error.rb → ignoring_exception.rb}

@@ -3,9 +3,9 @@
 module ConvenientService
   module RSpec
     module Helpers
-      module IgnoringError
-        def ignoring_error(...)
-          Custom::IgnoringError.call(...)
+      module IgnoringException
+        def ignoring_exception(...)
+          Custom::IgnoringException.call(...)
         end
       end
     end

data/lib/convenient_service/rspec/helpers.rb

@@ -2,7 +2,7 @@
 
 require_relative "helpers/custom"
 
-require_relative "helpers/ignoring_error"
+require_relative "helpers/ignoring_exception"
 require_relative "helpers/in_threads"
 require_relative "helpers/stub_service"
 require_relative "helpers/wrap_method"
@@ -13,7 +13,7 @@ module ConvenientService
       include Support::Concern
 
       included do
-        include Helpers::IgnoringError
+        include Helpers::IgnoringException
         include Helpers::InThreads
         include Helpers::StubService
         include Helpers::WrapMethod

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

@@ -22,7 +22,7 @@ module ConvenientService
           def matches?(klass)
             @klass = klass
 
-            Utils::Bool.to_bool(klass < base_klass)
+            Utils.to_bool(klass < base_klass)
           end
 
           def description

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

@@ -5,6 +5,26 @@ module ConvenientService
     module Matchers
       module Custom
         class CacheItsValue
+          ##
+          # @note `cache_its_value` may lead to false positives.
+          # @note `cache_its_value` calls the `expect` block twice to check its return values object ids.
+          #
+          # @example False positive spec.
+          #
+          #   let(:command_result) { command.call }
+          #
+          #   specify do
+          #     # bad - `command_result` is already cached(memoized) by `let`. That is why `cache_its_value` is always satisfied.
+          #     expect { command_result }.to cache_its_value
+          #   end
+          #
+          # @example Correct spec.
+          #
+          #   specify do
+          #     # good - `command.call` is recalculated every time `expect` block is invoked.
+          #     expect { command.call }.to cache_its_value
+          #   end
+          #
           def matches?(block_expectation)
             @block_expectation = block_expectation
 

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

@@ -5,6 +5,7 @@ module ConvenientService
     module Matchers
       module Custom
         ##
+        # @example Common usage.
         #   expect { method.call }
         #     .to call_chain_next.on(method)
         #     .with_arguments(*args, **kwargs, &block)
@@ -15,6 +16,18 @@ module ConvenientService
           include ::RSpec::Matchers
           include ::RSpec::Mocks::ExampleMethods
 
+          ##
+          # @param block_expectation [Proc, nil]
+          # @return [Bool]
+          # @raise [RSpec::Expectations::ExpectationNotMetError]
+          #
+          # @internal
+          #   NOTE: Using `expect` inside custom matchers is NOT a good idea, since failure descriptions are too generic and may mislead the end-user.
+          #   TODO: Refactor to return only boolean, without raises.
+          #
+          #   NOTE: RSpec is using exception for control flow.
+          #   - https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/expectations.rb
+          #
           def matches?(block_expectation)
             @block_expectation = block_expectation
 
@@ -36,7 +49,16 @@ module ConvenientService
           end
 
           ##
-          # https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/matchers/built_in/change.rb#L50
+          # @param block_expectation [Proc, nil]
+          # @return [Bool]
+          # @raise [RSpec::Expectations::ExpectationNotMetError]
+          #
+          # @internal
+          #   NOTE: Using `expect` inside custom matchers is NOT a good idea, since failure descriptions are too generic and may mislead the end-user.
+          #   TODO: Refactor to return only boolean, without raises.
+          #
+          #   NOTE: RSpec is using exception for control flow.
+          #   - https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/expectations.rb
           #
           def does_not_match?(block_expectation)
             @block_expectation = block_expectation
@@ -50,8 +72,10 @@ module ConvenientService
             #     `expect { }.not_to change { }.to()` is not supported
             #
             # That is why `expect(method.chain_called?).to eq(false)` is introduced.
+            # - https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/matchers/built_in/change.rb#L50
             #
             expect(method.chain_called?).to eq(false)
+
             expect { value = block_expectation.call }.not_to change(method, :chain_called?)
 
             if used_with_arguments?
@@ -67,22 +91,38 @@ module ConvenientService
             true
           end
 
+          ##
+          # @return [Boolean]
+          #
           def supports_block_expectations?
             true
           end
 
+          ##
+          # @return [String]
+          #
           def description
             "call `chain.next`"
           end
 
+          ##
+          # @return [String]
+          #
           def failure_message
             "expected to call `chain.next`"
           end
 
+          ##
+          # @return [String]
+          #
           def failure_message_when_negated
             "expected NOT to call `chain.next`"
           end
 
+          ##
+          # @param method [ConvenientService::RSpec::Helpers::Custom::Entities::WrappedMethod]
+          # @return [ConvenientService::RSpec::Matchers::Custom::CallChainNext]
+          #
           def on(method)
             method.reset!
 
@@ -91,12 +131,39 @@ module ConvenientService
             self
           end
 
+          ##
+          # @param args[Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil]
+          # @return [ConvenientService::RSpec::Matchers::Custom::CallChainNext]
+          #
           def with_arguments(*args, **kwargs, &block)
             chain[:with_arguments] = {args: args, kwargs: kwargs, block: block}
 
             self
           end
 
+          ##
+          # @return [ConvenientService::RSpec::Matchers::Custom::CallChainNext]
+          #
+          def with_any_arguments
+            chain.delete(:with_arguments)
+
+            self
+          end
+
+          ##
+          # @return [ConvenientService::RSpec::Matchers::Custom::CallChainNext]
+          #
+          def without_arguments
+            chain[:with_arguments] = {args: [], kwargs: {}, block: nil}
+
+            self
+          end
+
+          ##
+          # @return [ConvenientService::RSpec::Matchers::Custom::CallChainNext]
+          #
           def and_return_its_value
             chain[:and_return_its_value] = true
 
@@ -105,38 +172,69 @@ module ConvenientService
 
           private
 
+          ##
+          # @!attribute [r] block_expectation
+          #   @return [Proc, nil]
+          #
           attr_reader :block_expectation
 
+          ##
+          # @return [Boolean]
+          #
           def used_with_arguments?
             chain.key?(:with_arguments)
           end
 
+          ##
+          # @return [Boolean]
+          #
           def used_and_return_its_value?
             chain.key?(:and_return_its_value)
           end
 
+          ##
+          # @return [Hash{Symbol => Object}]
+          #
           def chain
             @chain ||= {}
           end
 
+          ##
+          # @return [ConvenientService::RSpec::Helpers::Custom::Entities::WrappedMethod]
+          #
           def method
             @method ||= chain[:method]
           end
 
+          ##
+          # @return [Array<Object>]
+          #
           def args
             @args ||= chain.dig(:with_arguments, :args) || []
           end
 
+          ##
+          # @return [Array<Object>]
+          #
           alias_method :expected_args, :args
 
+          ##
+          # @return [Hash{Symbol => Object}]
+          #
           def kwargs
             @kwargs ||= chain.dig(:with_arguments, :kwargs) || {}
           end
 
+          ##
+          # @return [Hash{Symbol => Object}]
+          #
           alias_method :expected_kwargs, :kwargs
 
           ##
-          # NOTE: `if defined?` is used in order to cache `nil` if needed.
+          # @return [Proc, nil]
+          #
+          # @internal
+          #   NOTE: `if defined?` is used in order to cache `nil` if needed.
           #
           def block
             return @block if defined? @block
@@ -144,6 +242,9 @@ module ConvenientService
             @block = chain.dig(:with_arguments, :block)
           end
 
+          ##
+          # @return [Proc, nil]
+          #
           alias_method :expected_block, :block
         end
       end

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings/sub_matchers/return_its_value.rb

@@ -15,6 +15,9 @@ module ConvenientService
                       # @param block_expectation_value [Object]
                       # @return [Boolean]
                       #
+                      # @internal
+                      #   TODO: Proper explanatory message when `matcher.delegation_value` raises exception.
+                      #
                       def matches?(block_expectation_value)
                         super
 

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings/sub_matchers/with_concrete_arguments.rb

@@ -15,7 +15,7 @@ module ConvenientService
                       # @return [Boolean]
                       #
                       def matches_arguments?(arguments)
-                        Utils::Bool.to_bool(arguments == matcher.expected_arguments)
+                        Utils.to_bool(arguments == matcher.expected_arguments)
                       end
 
                       ##

data/lib/convenient_service/rspec/matchers/custom/delegate_to/entities/matcher/entities/chainings_collection/{errors.rb → exceptions.rb}

@@ -9,8 +9,8 @@ module ConvenientService
             class Matcher
               module Entities
                 class ChainingsCollection
-                  module Errors
-                    class CallOriginalChainingIsAlreadySet < ::ConvenientService::Error
+                  module Exceptions
+                    class CallOriginalChainingIsAlreadySet < ::ConvenientService::Exception
                       def initialize
                         message = <<~TEXT
                           Call original chaining is already set.
@@ -22,7 +22,7 @@ module ConvenientService
                       end
                     end
 
-                    class ArgumentsChainingIsAlreadySet < ::ConvenientService::Error
+                    class ArgumentsChainingIsAlreadySet < ::ConvenientService::Exception
                       def initialize
                         message = <<~TEXT
                           Arguments chaining is already set.
@@ -34,7 +34,7 @@ module ConvenientService
                       end
                     end
 
-                    class ReturnItsValueChainingIsAlreadySet < ::ConvenientService::Error
+                    class ReturnItsValueChainingIsAlreadySet < ::ConvenientService::Exception
                       def initialize
                         message = <<~TEXT
                           Returns its value chaining is already set.