convenient_service 0.12.0 → 0.13.0

data/lib/convenient_service/examples/standard/request_params/services/merge_params.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Services
           class MergeParams
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/request_params/services/prepare.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Services
           class Prepare
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/request_params/services/validate_casted_params.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Services
           class ValidateCastedParams
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/request_params/services/validate_uncasted_params.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Services
           class ValidateUncastedParams
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/request_params/utils/array/wrap.rb

@@ -3,10 +3,10 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module Array
-            class Wrap < Support::Command
+            class Wrap < ConvenientService::Command
               ##
               # @!attribute [r] pad
               #   @return [Object] Can be any type.

data/lib/convenient_service/examples/standard/request_params/utils/array.rb

@@ -5,7 +5,7 @@ require_relative "array/wrap"
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module Array
             class << self

data/lib/convenient_service/examples/standard/request_params/utils/http/request/parse_body.rb

@@ -3,14 +3,14 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module HTTP
             module Request
               ##
               # TODO: Specs.
               #
-              class ParseBody < Support::Command
+              class ParseBody < ConvenientService::Command
                 attr_reader :http_string
 
                 def initialize(http_string:)

data/lib/convenient_service/examples/standard/request_params/utils/http/request/parse_path.rb

@@ -3,14 +3,14 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module HTTP
             module Request
               ##
               # TODO: Specs.
               #
-              class ParsePath < Support::Command
+              class ParsePath < ConvenientService::Command
                 attr_reader :http_string
 
                 def initialize(http_string:)

data/lib/convenient_service/examples/standard/request_params/utils/http/request.rb

@@ -6,7 +6,7 @@ require_relative "request/parse_path"
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module HTTP
             module Request

data/lib/convenient_service/examples/standard/request_params/utils/integer/safe_parse.rb

@@ -6,13 +6,13 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module Integer
             ##
             # TODO: Specs.
             #
-            class SafeParse < Support::Command
+            class SafeParse < ConvenientService::Command
               attr_reader :object
 
               def initialize(object)

data/lib/convenient_service/examples/standard/request_params/utils/integer.rb

@@ -9,7 +9,7 @@ require_relative "integer/safe_parse"
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module Integer
             class << self

data/lib/convenient_service/examples/standard/request_params/utils/json/safe_parse.rb

@@ -11,10 +11,10 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module JSON
-            class SafeParse < Support::Command
+            class SafeParse < ConvenientService::Command
               attr_reader :json_string, :default_value
 
               def initialize(json_string, default_value: nil)

data/lib/convenient_service/examples/standard/request_params/utils/json.rb

@@ -5,7 +5,7 @@ require_relative "json/safe_parse"
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module JSON
             class << self

data/lib/convenient_service/examples/standard/request_params/utils/object/blank.rb

@@ -6,13 +6,13 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module Object
             ##
             # TODO: Specs.
             #
-            class Blank < Support::Command
+            class Blank < ConvenientService::Command
               attr_reader :object
 
               def initialize(object)

data/lib/convenient_service/examples/standard/request_params/utils/object/present.rb

@@ -6,13 +6,13 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module Object
             ##
             # TODO: Specs.
             #
-            class Present < Support::Command
+            class Present < ConvenientService::Command
               attr_reader :object
 
               def initialize(object)

data/lib/convenient_service/examples/standard/request_params/utils/object.rb

@@ -6,7 +6,7 @@ require_relative "object/present"
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Utils
           module Object
             class << self

data/lib/convenient_service/examples/standard/request_params/utils/url/valid.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+##
+#
+#
+module ConvenientService
+  module Examples
+    module Standard
+      class RequestParams
+        module Utils
+          module URL
+            ##
+            # TODO: Use to validate URLs.
+            #
+            class Valid < ConvenientService::Command
+              attr_reader :url
+
+              def initialize(url)
+                @url = url
+              end
+
+              ##
+              # NOTE: How to validate URLs?
+              # - https://storck.io/posts/better-http-url-validation-in-ruby-on-rails
+              # - https://github.com/sporkmonger/addressable/issues/1452
+              #
+              # NOTE: URL is NOT URI.
+              # - https://stackoverflow.com/a/16359999/12201472
+              # - https://stackoverflow.com/a/13041565/12201472
+              #
+              # NOTE: Why NOT to match `URI::regexp`?
+              # - https://bugs.ruby-lang.org/issues/6520
+              #
+              def call
+                uri = ::URI.parse(url.to_s)
+
+                uri.is_a?(::URI::HTTPS) || uri.is_a?(::URI::HTTP)
+              rescue ::URI::InvalidURIError
+                false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/examples/standard/request_params/utils/url.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "url/valid"
+
+module ConvenientService
+  module Examples
+    module Standard
+      class RequestParams
+        module Utils
+          module URL
+            class << self
+              def valid?(url)
+                Valid.call(url)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,3 +5,4 @@ require_relative "utils/http"
 require_relative "utils/integer"
 require_relative "utils/json"
 require_relative "utils/object"
+require_relative "utils/url"

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

@@ -36,7 +36,7 @@ require_relative "request_params/utils"
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         include ConvenientService::Feature
 
         entry :prepare do |request|

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