convenient_service 0.2.0 → 0.3.0

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

@@ -1,5 +1,18 @@
 # frozen_string_literal: true
 
+##
+# IMPORTANT: This matcher has a dedicated end-user doc. Do NOT forget to update it when needed.
+# https://github.com/marian13/convenient_service_docs/blob/main/docs/api/tests/rspec/matchers/delegate_to.mdx
+#
+# TODO: Refactor into composition:
+#   - Ability to compose when `delegate_to` is used `without_arguments`.
+#   - Ability to compose when `delegate_to` is used `with_arguments`.
+#   - Ability to compose when `delegate_to` is used `and_return_its_value`.
+#
+# TODO: Refactor to NOT use `expect` inside this matcher.
+# This way the matcher will return true or false, but never raise exceptions (descendant of Exception, not StandardError).
+# Then it will be easier to developer a fully comprehensive spec suite for `delegate_to`.
+#
 module ConvenientService
   module RSpec
     module Matchers
@@ -81,15 +94,7 @@ module ConvenientService
               # https://relishapp.com/rspec/rspec-mocks/docs/configuring-responses/wrapping-the-original-implementation
               #
               allow(object).to receive(method).and_wrap_original do |original, *actual_args, **actual_kwargs, &actual_block|
-                ##
-                # TODO: Provide customized error messages?
-                # https://relishapp.com/rspec/rspec-expectations/docs/customized-message
-                #
-                # NOTE: `delegate_to` expects that delegation is executed only once during `block_expectation`.
-                #
-                expect(actual_args).to eq(expected_args)
-                expect(actual_kwargs).to eq(expected_kwargs)
-                expect(actual_block).to eq(expected_block)
+                actual_arguments_collection << [actual_args, actual_kwargs, actual_block]
 
                 ##
                 # NOTE: Imitates `and_call_original`.
@@ -108,7 +113,7 @@ module ConvenientService
             ##
             # NOTE: If this expectation fails, it means `delegate_to` is NOT met.
             #
-            expect(object).to have_received(method)
+            expect(object).to have_received(method).at_least(1) unless used_with_arguments?
 
             ##
             # IMPORTANT: `and_return_its_value` works only when `delegate_to` checks a pure function.
@@ -166,7 +171,13 @@ module ConvenientService
             # NOTE: RSpec raises exception when any `expect` is NOT satisfied.
             # So, this `true` is returned only when all `expect` are successful.
             #
-            true
+            if used_with_arguments?
+              actual_arguments_collection.any? do |(actual_args, actual_kwargs, actual_block)|
+                actual_args == expected_args && actual_kwargs == expected_kwargs && actual_block == expected_block
+              end
+            else
+              true
+            end
           end
 
           ##
@@ -184,8 +195,16 @@ module ConvenientService
             "delegate to `#{printable_method}`"
           end
 
+          def failure_message
+            if used_with_arguments?
+              "expected `#{printable_block_expectation}` to delegate to `#{printable_method}` with expected arguments at least once, but it didn't."
+            else
+              "expected `#{printable_block_expectation}` to delegate to `#{printable_method}` at least once, but it didn't."
+            end
+          end
+
           ##
-          # IMPORTANT: `failure_message`, `failure_message_when_negated` are NOT implemented, since they are never called (since `matches?` always returns `true`).
+          # IMPORTANT: `failure_message_when_negated` is NOT supported yet.
           #
 
           def with_arguments(*args, **kwargs, &block)
@@ -248,6 +267,25 @@ module ConvenientService
           end
 
           alias_method :expected_block, :block
+
+          def actual_arguments_collection
+            @actual_arguments_collection ||= []
+          end
+
+          ##
+          # NOTE: An example of how RSpec extracts block source, but they marked it as private.
+          # https://github.com/rspec/rspec-expectations/blob/311aaf245f2c5493572bf683b8c441cb5f7e44c8/lib/rspec/matchers/built_in/change.rb#L437
+          #
+          # TODO: `printable_block_expectation` when `method_source` is available.
+          # https://github.com/banister/method_source
+          #
+          # def printable_block_expectation
+          #   @printable_block_expectation ||= block_expectation.source
+          # end
+          #
+          def printable_block_expectation
+            @printable_block_expectation ||= "{ ... }"
+          end
         end
       end
     end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveStubbedResult
+        module Concern
+          include Support::Concern
+
+          class_methods do
+            ##
+            # @return [ConvenientService::Support::Cache]
+            #
+            # @internal
+            #   `::RSpec.current_example` docs:
+            #   - https://www.rubydoc.info/github/rspec/rspec-core/RSpec.current_example
+            #   - https://github.com/rspec/rspec-core/blob/v3.12.0/lib/rspec/core.rb#L122
+            #   - https://relishapp.com/rspec/rspec-core/docs/metadata/current-example
+            #
+            #   TODO: Mutex for thread-safety when parallel steps will be supported.
+            #
+            def stubbed_results
+              cache = Utils::Object.instance_variable_fetch(::RSpec.current_example, :@__convenient_service_stubbed_results__) { Support::Cache.new }
+
+              cache.scope(self)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_stubbed_result/middleware.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveStubbedResult
+        class Middleware < Core::MethodChainMiddleware
+          ##
+          # @param args [Array]
+          # @param kwargs [Hash]
+          # @param block [Proc]
+          # @return [Object] Can be any type.
+          #
+          def next(*args, **kwargs, &block)
+            key_with_arguments = cache.keygen(*args, **kwargs, &block)
+            key_without_arguments = cache.keygen
+
+            return cache[key_with_arguments] if cache.exist?(key_with_arguments)
+            return cache[key_without_arguments] if cache.exist?(key_without_arguments)
+
+            chain.next(*args, **kwargs, &block)
+          end
+
+          private
+
+          ##
+          # @return [ConvenientService::Support::Cache]
+          #
+          def cache
+            entity.stubbed_results
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_stubbed_result.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "can_have_stubbed_result/concern"
+require_relative "can_have_stubbed_result/middleware"

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_jsend_status_and_attributes/concern/instance_methods.rb

@@ -49,36 +49,48 @@ module ConvenientService
                     ##
                     # @return [Class]
                     #
-                    def service
-                      internals.cache[:jsend_attributes].service
-                    end
+                    delegate :service, to: :jsend_attributes
 
                     ##
                     # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Entities::Status]
                     #
-                    def status
-                      internals.cache[:jsend_attributes].status
-                    end
+                    delegate :status, to: :jsend_attributes
 
                     ##
                     # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Entities::Data]
                     #
-                    def data
-                      internals.cache[:jsend_attributes].data
-                    end
+                    delegate :data, to: :jsend_attributes
+
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Entities::Data]
+                    #
+                    alias_method :unsafe_data, :data
 
                     ##
                     # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Entities::Message]
                     #
-                    def message
-                      internals.cache[:jsend_attributes].message
-                    end
+                    delegate :message, to: :jsend_attributes
+
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Entities::Message]
+                    #
+                    alias_method :unsafe_message, :message
 
                     ##
                     # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Entities::Code]
                     #
-                    def code
-                      internals.cache[:jsend_attributes].code
+                    delegate :code, to: :jsend_attributes
+
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Entities::Code]
+                    #
+                    alias_method :unsafe_code, :code
+
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Structs::JSendAttributes]
+                    #
+                    def jsend_attributes
+                      internals.cache[:jsend_attributes]
                     end
 
                     ##
@@ -90,9 +102,9 @@ module ConvenientService
 
                       return false if service.class != other.service.class
                       return false if status != other.status
-                      return false if data != other.data
-                      return false if message != other.message
-                      return false if code != other.code
+                      return false if unsafe_data != other.unsafe_data
+                      return false if unsafe_message != other.unsafe_message
+                      return false if unsafe_code != other.unsafe_code
 
                       true
                     end

data/lib/convenient_service/service/plugins/has_result_params_validations/using_dry_validation/middleware.rb

@@ -21,15 +21,25 @@ module ConvenientService
             # TODO: Return one or all errors?
             #
             def errors
-              @errors ||=
-                entity
-                  .class
-                  .contract
-                  .new
-                  .call(**entity.constructor_params.kwargs)
-                  .errors
-                  .to_h
-                  .transform_values(&:first)
+              @errors ||= resolve_errors
+            end
+
+            def constructor_kwargs
+              @constructor_kwargs ||= entity.constructor_params.kwargs
+            end
+
+            def contract
+              @contract ||= entity.class.contract
+            end
+
+            def resolve_errors
+              return {} unless contract.schema
+
+              contract.new
+                .call(constructor_kwargs)
+                .errors
+                .to_h
+                .transform_values(&:first)
             end
           end
         end

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

@@ -8,7 +8,7 @@ module ConvenientService
           def next(...)
             return chain.next(...) if entity.steps.none?
 
-            last_step.result
+            last_step.result.copy
           end
 
           private

data/lib/convenient_service/service/plugins.rb

@@ -4,6 +4,7 @@
 # NOTE: Order matters.
 #
 require_relative "plugins/can_recalculate_result"
+require_relative "plugins/can_have_stubbed_result"
 require_relative "plugins/has_inspect"
 require_relative "plugins/has_result"
 require_relative "plugins/has_result_method_steps"

data/lib/convenient_service/support/cache.rb

@@ -21,6 +21,16 @@ module ConvenientService
         end
       end
 
+      ##
+      # @return [Boolean]
+      #
+      # @internal
+      #   https://ruby-doc.org/core-2.7.0/Hash.html#method-i-empty-3F
+      #
+      def empty?
+        hash.empty?
+      end
+
       ##
       # @return [Boolean]
       #
@@ -100,6 +110,22 @@ module ConvenientService
         exist?(key) ? read(key) : write(key, block.call)
       end
 
+      ##
+      # @return [ConvenientService::Support::Cache]
+      #
+      def clear
+        hash.clear
+
+        self
+      end
+
+      ##
+      # @return [ConvenientService::Support::Cache]
+      #
+      def scope(key)
+        fetch(key) { Support::Cache.new }
+      end
+
       ##
       # @return [ConvenientService::Support::Cache::Key]
       #

data/lib/convenient_service/support/gems/active_model.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module Gems
+      ##
+      # @api private
+      #
+      class ActiveModel
+        class << self
+          ##
+          # @return [Boolean]
+          #
+          # @internal
+          #   `Style/TernaryParentheses` is disabled since `defined?` has too low priority without parentheses.
+          #
+          # rubocop:disable Style/TernaryParentheses
+          def loaded?
+            (defined? ::ActiveModel) ? true : false
+          end
+          # rubocop:enable Style/TernaryParentheses
+
+          ##
+          # @return [ConvenientService::Support::Version]
+          #
+          # @internal
+          #   https://github.com/rails/rails/blob/main/activemodel/lib/active_model/version.rb
+          #
+          def version
+            loaded? ? Support::Version.new(::ActiveModel.version) : Support::Version.null_version
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/gems/rspec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module Gems
+      ##
+      # @api private
+      #
+      class RSpec
+        class << self
+          ##
+          # @return [Boolean]
+          #
+          # @internal
+          #   `Style/TernaryParentheses` is disabled since `defined?` has too low priority without parentheses.
+          #
+          # rubocop:disable Style/TernaryParentheses
+          def loaded?
+            (defined? ::RSpec) ? true : false
+          end
+          # rubocop:enable Style/TernaryParentheses
+
+          ##
+          # @return [ConvenientService::Support::Version]
+          #
+          # @internal
+          #   https://github.com/rspec/rspec-core/blob/main/lib/rspec/core/version.rb
+          #
+          def version
+            loaded? ? Support::Version.new(::RSpec::Core::Version::STRING) : Support::Version.null_version
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/gems.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "gems/active_model"
+require_relative "gems/rspec"

data/lib/convenient_service/support/ruby.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    ##
+    # @api private
+    #
+    class Ruby
+      class << self
+        ##
+        # @return [ConvenientService::Support::Version]
+        #
+        # @internal
+        #   https://ruby-doc.org/core-2.7.2/doc/globals_rdoc.html
+        #
+        def version
+          @version ||= Support::Version.new(::RUBY_VERSION)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/version/null_version.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class Version
+      ##
+      # @api private
+      #
+      # @internal
+      #   - https://thoughtbot.com/blog/rails-refactoring-example-introduce-null-object
+      #   - https://avdi.codes/null-objects-and-falsiness/
+      #
+      class NullVersion
+        ##
+        # @return [nil]
+        #
+        def gem_version
+          nil
+        end
+
+        ##
+        # @param other [Object] Can be any type.
+        # @return [nil]
+        #
+        def <=>(other)
+          nil
+        end
+
+        ##
+        # @param other [Object] Can be any type.
+        # @return [nil]
+        #
+        def <(other)
+          nil
+        end
+
+        ##
+        # @param other [Object] Can be any type.
+        # @return [nil]
+        #
+        def <=(other)
+          nil
+        end
+
+        ##
+        # @param other [Object] Can be any type.
+        # @return [nil]
+        #
+        def ==(other)
+          nil
+        end
+
+        ##
+        # @param other [Object] Can be any type.
+        # @return [nil]
+        #
+        def >(other)
+          nil
+        end
+
+        ##
+        # @param other [Object] Can be any type.
+        # @return [nil]
+        #
+        def >=(other)
+          nil
+        end
+
+        ##
+        # @return [String]
+        #
+        def to_s
+          ""
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/version.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "version/null_version"
+
+module ConvenientService
+  module Support
+    class Version
+      include ::Comparable
+
+      undef_method :between?
+
+      undef_method :clamp
+
+      ##
+      # @param value [String]
+      # @return [void]
+      #
+      def initialize(value)
+        @value = value
+      end
+
+      class << self
+        ##
+        # @return [ConvenientService::Support::Version::NullVersion]
+        #
+        def null_version
+          @null_version ||= NullVersion.new
+        end
+      end
+
+      ##
+      # @return [Gem::Version, nil]
+      #
+      def gem_version
+        cast_gem_version(value)
+      end
+
+      ##
+      # @param other [Object] Can be any type.
+      # @return [Boolean, nil]
+      #
+      def <=>(other)
+        gem_version <=> cast_gem_version(other)
+      end
+
+      ##
+      # @return [String]
+      #
+      def to_s
+        gem_version.to_s
+      end
+
+      private
+
+      attr_reader :value
+
+      ##
+      # @return [Gem::Version, nil]
+      #
+      def cast_gem_version(value)
+        ::Gem::Version.create(value.to_s) if ::Gem::Version.correct?(value.to_s)
+      end
+    end
+  end
+end

data/lib/convenient_service/support.rb

@@ -9,4 +9,7 @@ require_relative "support/command"
 require_relative "support/copyable"
 require_relative "support/delegate"
 require_relative "support/finite_loop"
+require_relative "support/gems"
 require_relative "support/middleware"
+require_relative "support/ruby"
+require_relative "support/version"

data/lib/convenient_service/utils/object/instance_variable_fetch.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+##
+#
+#
+module ConvenientService
+  module Utils
+    module Object
+      class InstanceVariableFetch < Support::Command
+        ##
+        # @!attribute [r] object
+        #   @return [Object]
+        #
+        attr_reader :object
+
+        ##
+        # @!attribute [r] ivar_name
+        #   @return [Symbol, String]
+        #
+        attr_reader :ivar_name
+
+        ##
+        # @!attribute [r] fallback_block
+        #   @return [Proc, nil]
+        #
+        attr_reader :fallback_block
+
+        ##
+        # @param object [Object]
+        # @param ivar_name [Symbol]
+        # @param fallback_block [Proc]
+        # @return [void]
+        #
+        def initialize(object, ivar_name, &fallback_block)
+          @object = object
+          @ivar_name = ivar_name
+          @fallback_block = fallback_block
+        end
+
+        ##
+        # @return [Object] Value of ivar. Can be any type.
+        #
+        def call
+          return object.instance_variable_get(ivar_name) if object.instance_variable_defined?(ivar_name)
+
+          return object.instance_variable_set(ivar_name, fallback_block.call) if fallback_block
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/object.rb

@@ -1,11 +1,20 @@
 # frozen_string_literal: true
 
+require_relative "object/instance_variable_fetch"
 require_relative "object/resolve_type"
 
 module ConvenientService
   module Utils
     module Object
       class << self
+        ##
+        # @example
+        #   ConvenientService::Utils::Object.instance_variable_fetch("abc", :@foo) { :bar }
+        #
+        def instance_variable_fetch(...)
+          InstanceVariableFetch.call(...)
+        end
+
         ##
         # @example
         #   ConvenientService::Utils::Object.resolve_type("foo")

data/lib/convenient_service/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConvenientService
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end