convenient_service 0.12.0 → 0.14.0

data/lib/convenient_service/examples/standard/v1/request_params.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "request_params/constants"
+require_relative "request_params/entities"
+require_relative "request_params/services"
+require_relative "request_params/utils"
+
+##
+# @since 0.3.0
+#
+# @internal
+#   Usage example:
+#
+#     http_string =
+#       <<~TEXT
+#         POST /rules/1000000.json HTTP/1.1
+#         User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36
+#         Host: code-review.com
+#         Content-Type: application/json; charset=utf-8
+#         Content-Length: 134
+#         Accept-Language: en-us
+#         Accept-Encoding: gzip, deflate
+#         Connection: Keep-Alive
+#
+#         {"title":"Avoid error shadowing","description":"Check the official User Docs","tags":["error-shadowing"]}
+#       TEXT
+#
+#     request = ConvenientService::Examples::Standard::V1::RequestParams::Entities::Request.new(http_string:)
+#
+#     ConvenientService::Examples::Standard::V1::RequestParams.prepare(request)
+#
+#   - https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types
+#   - https://www.whatismybrowser.com/guides/the-latest-user-agent/chrome
+#   - https://www.tutorialspoint.com/http/http_requests.htm
+#
+module ConvenientService
+  module Examples
+    module Standard
+      module V1
+        class RequestParams
+          include ConvenientService::Feature
+
+          entry :prepare do |request|
+            Services::Prepare[request: request]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/exception.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+##
+# Base class for all `ConvenientService` exceptions.
+# Can be used as a catch-all solution, for example:
+#
+#   begin
+#     any_service.result
+#   rescue ConvenientService::Exception => exception
+#     puts exception.message
+#   end
+#
+module ConvenientService
+  class Exception < ::StandardError
+  end
+end

data/lib/convenient_service/feature.rb

@@ -6,7 +6,6 @@ module ConvenientService
 
     included do
       include Support::DependencyContainer::Entry
-      include Support::DependencyContainer::Export
     end
   end
 end

data/lib/convenient_service/logger.rb

@@ -1,71 +1,116 @@
 # frozen_string_literal: true
 
 ##
-# Usage example:
+# @example Usage.
 #
 #   ConvenientService::Logger.instance
 #   ConvenientService::Logger.instance.level = ::Logger::WARN
 #   ConvenientService::Logger.instance.warn { "log message" }
 #
-# Docs:
-#
-# - https://ruby-doc.org/stdlib-3.1.0/libdoc/logger/rdoc/Logger.html
-# - https://newbedev.com/ruby-create-singleton-with-parameters
+# @see https://ruby-doc.org/stdlib-2.7.0/libdoc/logger/rdoc/Logger.html
+# @see https://newbedev.com/ruby-create-singleton-with-parameters
 #
 module ConvenientService
   ##
-  # TODO: Custom matcher to track log messages.
+  # @internal
+  #   TODO: Custom matcher to track log messages.
   #
   class Logger < ::Logger
     include ::Singleton
 
     class << self
-      private
-
       ##
+      # @return [ConvenientService::Logger]
+      #
       # @internal
-      #   NOTE: `super` is `Logger.new`.
-      #   - https://ruby-doc.org/stdlib-3.1.0/libdoc/logger/rdoc/Logger.html#method-c-new
+      #   NOTE: `super` is `::Logger.new`.
+      #   - https://ruby-doc.org/stdlib-2.7.0/libdoc/logger/rdoc/Logger.html#method-c-new
+      #
+      #   IMPORTANT: Older versions of `::Logger` do NOT support `level` as a string.
+      #   - https://github.com/ruby/logger/blob/v1.2.8.1/lib/logger.rb#L333
+      #   - https://github.com/ruby/logger/blob/v1.2.8.1/lib/logger.rb#L740
+      #   - https://github.com/ruby/logger/blob/v1.5.3/lib/logger.rb#L651
+      #   - https://github.com/ruby/logger/blob/v1.5.3/lib/logger.rb#L397
+      #
+      #   TODO: Specs for `super(::STDOUT)`.
       #
       # rubocop:disable Style/GlobalStdStream
       def new
         super(::STDOUT).tap do |logger|
-          logger.level = ::ENV["CONVENIENT_SERVICE_LOGGER_LEVEL"] || "INFO"
+          logger.level = ::ENV["CONVENIENT_SERVICE_LOGGER_LEVEL"] || ::Logger::INFO
 
-          logger.formatter = colored_formatter if ::ENV["CONVENIENT_SERVICE_LOGGER_ENABLE_COLORS"] == "true"
+          logger.formatter = (::ENV["CONVENIENT_SERVICE_LOGGER_ENABLE_COLORS"] == "true") ? colored_formatter : original_formatter
         end
       end
       # rubocop:enable Style/GlobalStdStream
 
+      ##
+      # @return [Logger::Formatter]
+      #
       def original_formatter
         ::Logger::Formatter.new
       end
 
       ##
-      # https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html#method-i-add
+      # @return [Proc]
+      #
+      # @internal
+      #   - https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html#method-i-add
+      #
+      #   IMPORTANT: Check `%w(DEBUG INFO WARN ERROR FATAL ANY)` for severity values.
+      #   - https://github.com/ruby/logger/blob/v1.2.8.1/lib/logger.rb#L445
+      #   - https://github.com/ruby/logger/blob/v1.5.3/lib/logger.rb#L736
       #
       def colored_formatter
-        return original_formatter unless defined? ::Paint
+        return original_formatter unless Dependencies.paint.loaded?
 
         proc do |severity, datetime, progname, message|
           log = original_formatter.call(severity, datetime, progname, message)
 
-          case severity.to_s.downcase
-          when "info" then ::Paint[log, :cyan, :bold]
-          when "warn" then ::Paint[log, :yellow, :bold]
-          when "error" then ::Paint[log, :red, :bold]
-          when "fatal" then ::Paint[log, :red, :underline]
-          when "debug" then ::Paint[log, :magenta, :bold]
+          case severity
+          when "INFO" then ::Paint[log, :cyan, :bold]
+          when "WARN" then ::Paint[log, :yellow, :bold]
+          when "ERROR" then ::Paint[log, :red, :bold]
+          when "FATAL" then ::Paint[log, :red, :underline]
+          when "DEBUG" then ::Paint[log, :magenta, :bold]
+          when "ANY" then log
           else log
           end
         end
       end
     end
-  end
 
-  class << self
-    def logger
-      Logger.instance
+    ##
+    # @api public
+    #
+    # @internal
+    #   IMPORTANT: Older versions of `Logger` do NOT support `level` as a string.
+    #   - https://github.com/ruby/logger/blob/v1.2.8.1/lib/logger.rb#L333
+    #   - https://github.com/ruby/logger/blob/v1.2.8.1/lib/logger.rb#L740
+    #   - https://github.com/ruby/logger/blob/v1.5.3/lib/logger.rb#L651
+    #   - https://github.com/ruby/logger/blob/v1.5.3/lib/logger.rb#L397
+    #
+    #   NOTE: Early return is NOT used, since it is NOT possible to return custom values from `writer` methods.
+    #
+    #   NOTE: `Warning.warn` is chosen over `Kernel.warn` in order to have a simple to track delegation from RSpec.
+    #   - https://ruby-doc.org/core-2.7.0/Warning.html#method-i-warn
+    #
+    # TODO: Tag/prefix for all Convenient Service logs.
+    #
+    def level=(severity)
+      if Dependencies.support_logger_non_integer_levels?
+        super(severity)
+      elsif severity.instance_of?(::Integer)
+        super(severity)
+      else
+        ::Warning.warn <<~MESSAGE
+          `ConvenientService.logger.level` is reset from `#{severity}` to `Logger::INFO`.
+
+          Stdlib `logger` with version `#{Dependencies.logger.version}` does NOT support non-integer levels.
+        MESSAGE
+
+        super(::Logger::INFO)
+      end
     end
   end
 end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Helpers
+      module Custom
+        class IgnoringException < Support::Command
+          module Exceptions
+            class IgnoredExceptionIsNotRaised < ::ConvenientService::Exception
+              ##
+              # @param exception [StandardError]
+              # @return [void]
+              #
+              def initialize(exception:)
+                message = <<~TEXT
+                  Exception `#{exception}` is NOT raised. That is why it is NOT ignored.
+                TEXT
+
+                super(message)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "ignoring_exception/exceptions"
+
+module ConvenientService
+  module RSpec
+    module Helpers
+      module Custom
+        class IgnoringException < Support::Command
+          ##
+          # @!attribute [r] exception
+          #   @return [StandardError]
+          #
+          attr_reader :exception
+
+          ##
+          # @!attribute [r] block
+          #   @return [Proc]
+          #
+          attr_reader :block
+
+          ##
+          # @param exception [StandardError]
+          # @param block [Proc]
+          #
+          def initialize(exception, &block)
+            @exception = exception
+            @block = block
+          end
+
+          ##
+          # @return [ConvenientService::Support::UniqueValue]
+          # @raise [ConvenientService::RSpec::Helpers::Custom::IgnoringException::Exceptions::IgnoredExceptionIsNotRaised]
+          #
+          # @note Rescue `StandardError`, NOT `Exception`.
+          # @see https://thoughtbot.com/blog/rescue-standarderror-not-exception
+          # @see https://ruby-doc.org/core-2.7.0/StandardError.html
+          # @see https://ruby-doc.org/core-2.7.0/Exception.html
+          #
+          def call
+            block.call
+          rescue exception
+            Support::UNDEFINED
+          else
+            raise Exceptions::IgnoredExceptionIsNotRaised.new(exception: exception)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/helpers/custom/stub_service/entities/result_spec.rb

@@ -106,7 +106,7 @@ module ConvenientService
               #    TODO: Assert.
               #
               def calculate_value
-                service_class.__send__(status, **kwargs)
+                service_class.__send__(status, **kwargs).copy(overrides: {kwargs: {stubbed_result: true}})
               end
 
               ##
@@ -213,7 +213,7 @@ module ConvenientService
               # @return [Object]
               #
               def service_instance
-                @service_instance ||= service_class.create_without_initialize
+                @service_instance ||= service_class.new_without_initialize
               end
             end
           end

data/lib/convenient_service/rspec/helpers/custom/stub_service/entities/stubbed_service.rb

@@ -7,23 +7,34 @@ module ConvenientService
         class StubService < Support::Command
           module Entities
             class StubbedService
+              include Support::DependencyContainer::Import
+
+              ##
+              # @internal
+              #   TODO: Implement shorter form in the following way:
+              #
+              #   import \
+              #     command: :SetServiceStubbedResult,
+              #     from: ConvenientService::Service::Plugins::CanHaveStubbedResults
+              #
+              import \
+                :"commands.SetServiceStubbedResult",
+                from: ConvenientService::Service::Plugins::CanHaveStubbedResults::Container
+
               ##
               # @param service_class [Class]
               # @return [void]
               #
               def initialize(service_class:)
                 @service_class = service_class
-                @arguments = {args: [], kwargs: {}, block: nil}
+                @arguments = Support::Arguments.null_arguments
               end
 
               ##
-              # @param args [Array<Object>]
-              # @param kwargs [Hash{Symbol => Object}]
-              # @param block [Block]
               # @return [ConvenientService::RSpec::Helpers::Custom::StubService::Entities::StubService]
               #
-              def with_arguments(*args, **kwargs, &block)
-                @arguments = {args: args, kwargs: kwargs, block: block}
+              def with_arguments(...)
+                @arguments = Support::Arguments.new(...)
 
                 self
               end
@@ -32,7 +43,7 @@ module ConvenientService
               # @return [ConvenientService::RSpec::Helpers::Custom::StubService::Entities::StubService]
               #
               def without_arguments
-                @arguments = {args: [], kwargs: {}, block: nil}
+                @arguments = Support::Arguments.null_arguments
 
                 self
               end
@@ -46,7 +57,7 @@ module ConvenientService
 
                 service_class.commit_config!(trigger: Constants::Triggers::STUB_SERVICE)
 
-                service_class.stubbed_results[key] = result_value
+                commands.SetServiceStubbedResult[service: service_class, arguments: arguments, result: result_value]
 
                 self
               end
@@ -72,18 +83,11 @@ module ConvenientService
               attr_reader :result_spec
 
               ##
-              # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+              # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
               #
               def result_value
                 @result_value ||= result_spec.for(service_class).calculate_value
               end
-
-              ##
-              # @return [ConvenientService::Support::Cache::Key]
-              #
-              def key
-                @key ||= service_class.stubbed_results.keygen(*arguments[:args], **arguments[:kwargs], &arguments[:block])
-              end
             end
           end
         end

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]