convenient_service 0.17.0 → 0.19.0

data/lib/convenient_service/rspec/primitive_matchers/classes/delegate_to.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "delegate_to/commands"
 require_relative "delegate_to/entities"
+require_relative "delegate_to/exceptions"
 
 ##
 # @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
+#   - https://github.com/marian13/convenient_service_docs/blob/main/docs/api/tests/rspec/matchers/delegate_to.mdx
 #
 module ConvenientService
   module RSpec
@@ -13,122 +15,242 @@ module ConvenientService
       module Classes
         ##
         # @internal
-        #   NOTE: This is a Facade class.
-        #   https://refactoring.guru/design-patterns/facade
+        #   NOTE: Consider the following concrete usage example to simplify understanding of variable namings used throughout this class:
+        #     specify do
+        #       expect { method_class.cast(other, **options) }
+        #         .to delegate_to(ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Commands::CastMethod, :call)
+        #         .with_arguments(other: other, options: options)
+        #         .and_return_its_value
+        #     end
+        #
+        #   Block `{ method_class.cast(other, **options) }` is named as `block_expectation`.
+        #   Class `ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Commands::CastMethod` is named as `object`.
+        #   Symbol `:call` is named as `method`.
+        #   Arguments `(other: other, options: options)` are named as `expected_arguments`.
+        #   Additional submatcher added by `and_return_its_value` chaining is named as `sub_matchers.return_its_value`.
+        #
+        #   NOTE: A similar (with different behaviour) matcher exists in `saharspec`.
+        #   - https://github.com/zverok/saharspec#send_messageobject-method-matcher
         #
         class DelegateTo
-          include Support::Delegate
+          ##
+          # @api private
+          #
+          # @!attribute [r] inputs
+          #   @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::Inputs]
+          #
+          attr_reader :inputs
 
           ##
-          # @return [Boolean]
+          # @api private
+          #
+          # @!attribute [r] outputs
+          #   @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::Outputs]
           #
-          delegate :matches?, to: :matcher
+          attr_reader :outputs
 
           ##
+          # @api private
+          #
+          # @param object [Object]
+          # @param method [String, Symbol]
+          # @param block_expectation [Proc]
+          # @return [void]
+          #
           # @internal
-          #   NOTE: Required by RSpec.
-          #   https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/custom-matchers/define-a-matcher-supporting-block-expectations
+          #   TODO: `raise unless object.respond_to?(method)`.
+          #   TODO: `any_block`.
+          #   TODO: `with_warmup`.
+          #   TODO: `compare_by`.
           #
-          delegate :supports_block_expectations?, to: :matcher
+          def initialize(object, method, block_expectation = proc { Support::UNDEFINED })
+            @inputs = Entities::Inputs.new(object: object, method: method, block_expectation: block_expectation)
+            @outputs = Entities::Outputs.new
+          end
 
           ##
-          # @return [String]
+          # @api public
+          #
+          # @param block_expectation [Proc]
+          # @return [Boolean]
           #
-          delegate :description, to: :matcher
+          def matches?(block_expectation)
+            inputs.block_expectation = block_expectation
+
+            sub_matchers.matches?(inputs.block_expectation)
+          end
 
           ##
-          # @return [String]
+          # @api public
           #
-          delegate :failure_message, to: :matcher
+          # @param block_expectation [Proc]
+          # @return [Boolean]
+          #
+          def does_not_match?(block_expectation)
+            inputs.block_expectation = block_expectation
+
+            !sub_matchers.matches?(inputs.block_expectation)
+          end
 
           ##
+          # @api public
+          #
+          # @internal
+          #   NOTE: Required by RSpec.
+          #   - https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/custom-matchers/define-a-matcher-supporting-block-expectations
+          #
+          def supports_block_expectations?
+            true
+          end
+
+          ##
+          # @api public
+          #
           # @return [String]
           #
-          delegate :failure_message_when_negated, to: :matcher
+          def description
+            "delegate to `#{inputs.printable_method}`"
+          end
 
           ##
-          # @overload initialize(object, method)
-          #   @param object [Object]
-          #   @param method [String, Symbol]
-          #   @return [void]
+          # @api public
           #
-          # @overload initialize(matcher)
-          #   @param matcher [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::Matcher]
-          #   @return [void]
-          #   @api private
+          # @return [String]
           #
-          # @internal
-          #   TODO: `overload do`?
+          def failure_message
+            sub_matchers.failure_message
+          end
+
+          ##
+          # @api public
           #
-          def initialize(object = nil, method = nil, matcher: nil)
-            @matcher = matcher || Entities::Matcher.new(object, method)
+          # @return [String]
+          #
+          def failure_message_when_negated
+            sub_matchers.failure_message_when_negated
           end
 
           ##
+          # @api public
+          #
           # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
           # @raise [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Exceptions::ArgumentsChainingIsAlreadySet]
           #
           def with_arguments(...)
-            matcher.with_arguments(...)
+            ::ConvenientService.raise Exceptions::ArgumentsChainingIsAlreadySet.new if sub_matchers.has_arguments?
+
+            inputs.expected_arguments = Support::Arguments.new(...)
+
+            sub_matchers.arguments = Entities::SubMatchers::WithConcreteArguments.new(matcher: self)
 
             self
           end
 
           ##
+          # @api public
+          #
           # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
           # @raise [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Exceptions::ArgumentsChainingIsAlreadySet]
           #
           def with_any_arguments
-            matcher.with_any_arguments
+            ::ConvenientService.raise Exceptions::ArgumentsChainingIsAlreadySet.new if sub_matchers.has_arguments?
+
+            sub_matchers.arguments = Entities::SubMatchers::WithAnyArguments.new(matcher: self)
 
             self
           end
 
           ##
+          # @api public
+          #
           # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
           # @raise [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Exceptions::ArgumentsChainingIsAlreadySet]
           #
           def without_arguments
-            matcher.without_arguments
+            ::ConvenientService.raise Exceptions::ArgumentsChainingIsAlreadySet.new if sub_matchers.has_arguments?
+
+            sub_matchers.arguments = Entities::SubMatchers::WithoutArguments.new(matcher: self)
 
             self
           end
 
           ##
+          # @api public
+          #
           # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
-          # @raise [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Exceptions::ReturnItsValueChainingIsAlreadySet]
+          # @raise [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Exceptions::ReturnValueChainingIsAlreadySet]
           #
           def and_return_its_value
-            matcher.and_return_its_value
+            ::ConvenientService.raise Exceptions::ReturnValueChainingIsAlreadySet.new if sub_matchers.has_return_value?
+
+            sub_matchers.return_value = Entities::SubMatchers::ReturnDelegationValue.new(matcher: self)
 
             self
           end
 
           ##
-          # TODO: `and_return`.
+          # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
+          # @raise [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Exceptions::ReturnValueChainingIsAlreadySet]
           #
-          # def and_return(...)
-          #   matcher.and_return(...)
+          def and_return(...)
+            ::ConvenientService.raise Exceptions::ReturnValueChainingIsAlreadySet.new if sub_matchers.has_return_value?
+
+            inputs.update_expected_return_value_block(...)
+
+            sub_matchers.return_value = Entities::SubMatchers::ReturnCustomValue.new(matcher: self)
+
+            self
+          end
+
+          ##
+          # @api public
+          #
+          # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
           #
-          #   self
-          # end
+          def with_calling_original
+            ::ConvenientService.raise Exceptions::CallOriginalChainingIsAlreadySet.new if inputs.has_call_original?
+
+            inputs.should_call_original = true
+
+            self
+          end
 
           ##
+          # @api public
+          #
           # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo]
           #
           def without_calling_original
-            matcher.without_calling_original
+            ::ConvenientService.raise Exceptions::CallOriginalChainingIsAlreadySet.new if inputs.has_call_original?
+
+            inputs.should_call_original = false
 
             self
           end
 
-          private
+          ##
+          # @api private
+          #
+          # @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::SubMatchers]
+          #
+          def sub_matchers
+            @sub_matchers ||= Entities::SubMatcherCollection.new(matcher: self)
+          end
 
           ##
-          # @!attribute [r] matcher
-          #   @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::Matcher]
+          # @api private
           #
-          attr_reader :matcher
+          # @param other [Object] Can be any type.
+          # @return [Boolean, nil]
+          #
+          def ==(other)
+            return unless other.instance_of?(self.class)
+
+            return false if inputs != other.inputs
+            return false if outputs != other.outputs
+
+            true
+          end
         end
       end
     end

data/lib/convenient_service/service/configs/amazing_print_inspect/aliases.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module AmazingPrintInspect
+    Config = ::ConvenientService::Service::Configs::AmazingPrintInspect
+  end
+end

data/lib/convenient_service/service/configs/amazing_print_inspect.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Configs
+      module AmazingPrintInspect
+        include Support::Concern
+
+        # rubocop:disable Lint/ConstantDefinitionInBlock
+        included do
+          include Configs::Essential
+
+          ##
+          # @internal
+          #   TODO: Plugin groups for autoreplacement of plugins with same purpose.
+          #
+          concerns do
+            use ConvenientService::Plugins::Service::HasAmazingPrintInspect::Concern
+          end
+
+          class self::Result
+            concerns do
+              use ConvenientService::Plugins::Result::HasAmazingPrintInspect::Concern
+            end
+
+            class self::Data
+              concerns do
+                use ConvenientService::Plugins::Data::HasAmazingPrintInspect::Concern
+              end
+            end
+
+            class self::Message
+              concerns do
+                use ConvenientService::Plugins::Message::HasAmazingPrintInspect::Concern
+              end
+            end
+
+            class self::Code
+              concerns do
+                use ConvenientService::Plugins::Code::HasAmazingPrintInspect::Concern
+              end
+            end
+
+            class self::Status
+              concerns do
+                use ConvenientService::Plugins::Status::HasAmazingPrintInspect::Concern
+              end
+            end
+          end
+
+          class self::Step
+            concerns do
+              use ConvenientService::Plugins::Step::HasAmazingPrintInspect::Concern
+            end
+          end
+        end
+        # rubocop:enable Lint/ConstantDefinitionInBlock
+      end
+    end
+  end
+end

data/lib/convenient_service/service/configs/awesome_print_inspect.rb

@@ -8,7 +8,7 @@ module ConvenientService
 
         # rubocop:disable Lint/ConstantDefinitionInBlock
         included do
-          include Configs::Minimal
+          include Configs::Essential
 
           ##
           # @internal

data/lib/convenient_service/service/configs/{minimal.rb → essential.rb}

@@ -4,34 +4,14 @@ module ConvenientService
   module Service
     module Configs
       ##
-      # Defines minimal configuration that adds a constructor, JSend-inspired result, steps, basic inspects, and internals to services.
+      # Defines essential configuration that adds a constructor, JSend-inspired result, steps, basic inspects, and internals to services.
       #
       # @note This config is NOT intented for the end-user usage. Use `Standard` instead.
       #
-      # @note
-      #   `use ConvenientService::Plugins::Common::NormalizesEnv::Middleware` should be used in a config that has the first `concern` that introduces a method.
-      #   For example, `:result` is added by `use ConvenientService::Plugins::Service::HasJSendResult::Concern` in `Minimal`.
-      #   That is why the following code is written in the `Minimal` config.
-      #
-      #     middlewares :result do
-      #       use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-      #
-      #       # ...
-      #     end
-      #
-      #   In turn, `:fallback_result` is added by `use ConvenientService::Plugins::Service::CanHaveFallbacks::Concern` in `Standard`.
-      #   That is why it is the responsibility of the `Standard` config, to define:
-      #
-      #     middlewares :fallback_result do
-      #       use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-      #
-      #       # ...
-      #     end
-      #
       # @internal
       #   NOTE: Heavily used in specs to test concerns and middlewares in isolation.
       #
-      module Minimal
+      module Essential
         include Support::Concern
 
         ##
@@ -56,45 +36,45 @@ module ConvenientService
 
             use ConvenientService::Plugins::Service::HasResult::Concern
             use ConvenientService::Plugins::Service::HasJSendResult::Concern
+
+            use ConvenientService::Plugins::Service::HasNegatedResult::Concern
+            use ConvenientService::Plugins::Service::HasNegatedJSendResult::Concern
+
             use ConvenientService::Plugins::Service::CanHaveSteps::Concern
-          end
+            use ConvenientService::Plugins::Service::CanHaveConnectedSteps::Concern
 
-          middlewares :initialize do
-            use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
+            use ConvenientService::Plugins::Service::CanHaveFallbacks::Concern
           end
 
           middlewares :result do
-            use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
             use ConvenientService::Plugins::Common::CachesReturnValue::Middleware
 
             use ConvenientService::Plugins::Service::RaisesOnNotResultReturnValue::Middleware
 
-            use ConvenientService::Plugins::Service::CanHaveSteps::Middleware
+            use ConvenientService::Plugins::Service::CanHaveConnectedSteps::Middleware
           end
 
-          middlewares :step do
-            use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
+          middlewares :step, scope: :class do
+            use ConvenientService::Plugins::Service::CanHaveMethodSteps::Middleware
           end
 
-          middlewares :success do
-            use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
+          middlewares :not_step, scope: :class do
+            use ConvenientService::Plugins::Service::CanHaveMethodSteps::Middleware
           end
 
-          middlewares :failure do
-            use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
+          middlewares :and_step, scope: :class do
+            use ConvenientService::Plugins::Service::CanHaveMethodSteps::Middleware
           end
 
-          middlewares :error do
-            use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
+          middlewares :and_not_step, scope: :class do
+            use ConvenientService::Plugins::Service::CanHaveMethodSteps::Middleware
           end
 
-          middlewares :result, scope: :class do
-            use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
+          middlewares :or_step, scope: :class do
+            use ConvenientService::Plugins::Service::CanHaveMethodSteps::Middleware
           end
 
-          middlewares :step, scope: :class do
-            use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-
+          middlewares :or_not_step, scope: :class do
             use ConvenientService::Plugins::Service::CanHaveMethodSteps::Middleware
           end
 
@@ -118,54 +98,14 @@ module ConvenientService
               use ConvenientService::Plugins::Common::HasConstructorWithoutInitialize::Concern
 
               use ConvenientService::Plugins::Result::HasJSendStatusAndAttributes::Concern
+
+              use ConvenientService::Plugins::Result::CanHaveStep::Concern
             end
 
             middlewares :initialize do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-
               use ConvenientService::Plugins::Result::HasJSendStatusAndAttributes::Middleware
             end
 
-            middlewares :success? do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-            end
-
-            middlewares :failure? do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-            end
-
-            middlewares :error? do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-            end
-
-            middlewares :not_success? do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-            end
-
-            middlewares :not_failure? do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-            end
-
-            middlewares :not_error? do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-            end
-
-            middlewares :data do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-            end
-
-            middlewares :message do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-            end
-
-            middlewares :code do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-            end
-
-            middlewares :to_kwargs do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-            end
-
             class self::Data
               include Core
 
@@ -194,8 +134,18 @@ module ConvenientService
               include Core
 
               concerns do
+                use ConvenientService::Plugins::Common::HasInternals::Concern
+
                 use ConvenientService::Plugins::Status::HasInspect::Concern
               end
+
+              class self::Internals
+                include Core
+
+                concerns do
+                  use ConvenientService::Plugins::Internals::HasCache::Concern
+                end
+              end
             end
 
             class self::Internals
@@ -213,35 +163,32 @@ module ConvenientService
             concerns do
               use ConvenientService::Plugins::Common::HasInternals::Concern
 
+              use ConvenientService::Plugins::Step::HasResult::Concern
+
               use ConvenientService::Plugins::Step::CanBeCompleted::Concern
 
               use ConvenientService::Plugins::Step::CanBeMethodStep::Concern
-              use ConvenientService::Plugins::Step::CanBeResultStep::Concern
 
               use ConvenientService::Plugins::Step::HasInspect::Concern
             end
 
-            middlewares :service_result do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
+            ##
+            # TODO: Simple debug for middlewares. For one service only.
+            #
+            middlewares :result do
               use ConvenientService::Plugins::Common::CachesReturnValue::Middleware
 
+              use ConvenientService::Plugins::Step::HasResult::Middleware
+
               use ConvenientService::Plugins::Step::RaisesOnNotResultReturnValue::Middleware
 
-              use ConvenientService::Plugins::Step::CanBeResultStep::CanBeExecuted::Middleware
               use ConvenientService::Plugins::Step::CanBeMethodStep::CanBeExecuted::Middleware
             end
 
-            middlewares :result do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-              use ConvenientService::Plugins::Common::CachesReturnValue::Middleware
-            end
-
             ##
             # TODO: Rename.
             #
             middlewares :printable_service do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-
               use ConvenientService::Plugins::Step::CanBeMethodStep::CanBePrinted::Middleware
             end