convenient_service 0.17.0 → 0.19.0

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/can_have_fallbacks/middleware.rb

@@ -11,6 +11,11 @@ module ConvenientService
                 class Middleware < MethodChainMiddleware
                   intended_for :result, entity: :step
 
+                  ##
+                  # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+                  #
+                  alias_method :step, :entity
+
                   ##
                   # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
                   #
@@ -21,9 +26,9 @@ module ConvenientService
                     when :success
                       result
                     when :failure
-                      fallback_failure_step? ? entity.fallback_failure_result(...) : result
+                      fallback_failure_step? ? fallback_failure_result(...) : result
                     when :error
-                      fallback_error_step? ? entity.fallback_error_result(...) : result
+                      fallback_error_step? ? fallback_error_result(...) : result
                     end
                   end
 
@@ -33,28 +38,28 @@ module ConvenientService
                   # @return [Boolean]
                   #
                   def fallback_failure_step?
-                    entity.fallback_failure_step? || fallback_true_step_as_failure_step?
+                    step.fallback_failure_step? || fallback_true_step_as_failure_step?
                   end
 
                   ##
                   # @return [Boolean]
                   #
                   def fallback_true_step_as_failure_step?
-                    entity.fallback_true_step? && fallback_true_status == :failure
+                    step.fallback_true_step? && fallback_true_status == :failure
                   end
 
                   ##
                   # @return [Boolean]
                   #
                   def fallback_error_step?
-                    entity.fallback_error_step? || fallback_true_step_as_error_step?
+                    step.fallback_error_step? || fallback_true_step_as_error_step?
                   end
 
                   ##
                   # @return [Boolean]
                   #
                   def fallback_true_step_as_error_step?
-                    entity.fallback_true_step? && fallback_true_status == :error
+                    step.fallback_true_step? && fallback_true_status == :error
                   end
 
                   ##
@@ -63,6 +68,70 @@ module ConvenientService
                   def fallback_true_status
                     middleware_arguments.kwargs.fetch(:fallback_true_status) { :failure }
                   end
+
+                  ##
+                  # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                  # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Plugins::CanHaveFallbacks::Exceptions::FallbackResultIsNotOverridden, ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Plugins::CanHaveFallbacks::Exceptions::MethodStepCanNotHaveFallback]
+                  #
+                  def fallback_failure_result
+                    refute_method_step!
+
+                    fallback_failure_result_own_method&.call || fallback_result_own_method&.call || ::ConvenientService.raise(Exceptions::FallbackResultIsNotOverridden.new(step: step, service: service, status: :failure))
+                  end
+
+                  ##
+                  # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                  # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Plugins::CanHaveFallbacks::Exceptions::FallbackResultIsNotOverridden, ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Plugins::CanHaveFallbacks::Exceptions::MethodStepCanNotHaveFallback]
+                  #
+                  def fallback_error_result
+                    refute_method_step!
+
+                    fallback_error_result_own_method&.call || fallback_result_own_method&.call || ::ConvenientService.raise(Exceptions::FallbackResultIsNotOverridden.new(step: step, service: service, status: :error))
+                  end
+
+                  ##
+                  # @return [Method, nil]
+                  #
+                  def fallback_failure_result_own_method
+                    Utils::Object.own_method(service, :fallback_failure_result, private: true)
+                  end
+
+                  ##
+                  # @return [Method, nil]
+                  #
+                  def fallback_error_result_own_method
+                    Utils::Object.own_method(service, :fallback_error_result, private: true)
+                  end
+
+                  ##
+                  # @return [Method, nil]
+                  #
+                  def fallback_result_own_method
+                    Utils::Object.own_method(service, :fallback_result, private: true)
+                  end
+
+                  ##
+                  # @return [ConvenientService::Service]
+                  #
+                  # @internal
+                  #   IMPORTANT: `step.service.klass.new(**input_values)` is the reason, why services should have only kwargs as arguments.
+                  #
+                  def service
+                    @service ||= step.service.klass.new(**step.input_values)
+                  end
+
+                  ##
+                  # @return [void]
+                  # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Plugins::CanHaveFallbacks::Exceptions::MethodStepCanNotHaveFallback]
+                  #
+                  # @internal
+                  #   TODO: Consider to move this assertion to the build time.
+                  #
+                  def refute_method_step!
+                    return unless step.method_step?
+
+                    ::ConvenientService.raise Exceptions::MethodStepCanNotHaveFallback.new(step: step)
+                  end
                 end
               end
             end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/can_have_fallbacks.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 
 require_relative "can_have_fallbacks/concern"
+require_relative "can_have_fallbacks/exceptions"
 require_relative "can_have_fallbacks/middleware"

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/can_have_parent_result/middleware.rb

@@ -11,8 +11,20 @@ module ConvenientService
                 class Middleware < MethodChainMiddleware
                   intended_for :result, entity: :step
 
+                  ##
+                  # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                  # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                  #
+                  # @internal
+                  #   IMPORTANT: `CanHaveParentResult` middleware MUST be placed after `HasResult` middleware.
+                  #
+                  #   NOTE: `result` at the moment of this middleware is still a `service_result` (or `method_result`). It is only later converted to `step_result` by `HasResult` middleware.
+                  #   That is why `result` is used as `parent` here.
+                  #
                   def next(...)
-                    chain.next(...).copy(overrides: {kwargs: {parent: entity.service_result}})
+                    result = chain.next(...)
+
+                    result.copy(overrides: {kwargs: {parent: result}})
                   end
                 end
               end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/has_amazing_print_inspect/concern.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module HasAmazingPrintInspect
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    ##
+                    # @return [String]
+                    #
+                    # @internal
+                    #   NOTE: `ai` is a part of public interface of `amazing_print`.
+                    #   - https://github.com/amazing-print/amazing_print?tab=readme-ov-file#usage
+                    #   - https://github.com/amazing-print/amazing_print/blob/master/lib/amazing_print/core_ext/kernel.rb
+                    #
+                    #   TODO: `inspect_values` for class. This way `service_class.name || ...` can be shared.
+                    #
+                    def inspect
+                      metadata = {
+                        ConvenientService: {
+                          entity: "Step",
+                          container: container.klass.name
+                        }
+                      }
+
+                      metadata[:ConvenientService].merge!(method_step? ? {method: ":#{method}"} : {service: service.klass.name})
+
+                      metadata.ai
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/has_amazing_print_inspect.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "has_amazing_print_inspect/concern"

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/has_awesome_print_inspect/concern.rb

@@ -26,11 +26,12 @@ module ConvenientService
                       metadata = {
                         ConvenientService: {
                           entity: "Step",
-                          container: container.klass.name,
-                          **(method_step? ? {method: ":#{method}"} : {service: service.klass.name})
+                          container: container.klass.name
                         }
                       }
 
+                      metadata[:ConvenientService].merge!(method_step? ? {method: ":#{method}"} : {service: service.klass.name})
+
                       metadata.ai
                     end
                   end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/has_result/concern.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module HasResult
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                    # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                    #
+                    # @internal
+                    #   TODO: `service.result`.
+                    #
+                    def result
+                      service_result
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/has_result/middleware.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module HasResult
+                class Middleware < MethodChainMiddleware
+                  intended_for :result, entity: :step
+
+                  ##
+                  # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+                  #
+                  alias_method :step, :entity
+
+                  ##
+                  # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                  # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                  #
+                  # @internal
+                  #   NOTE: Convents a foreign result received from `service_result` to own result.
+                  #   TODO: `service.result`.
+                  #
+                  def next(...)
+                    result = chain.next(...)
+
+                    result.copy(overrides: {kwargs: {data: extract_data(result), step: step, service: step.organizer}})
+                  end
+
+                  private
+
+                  ##
+                  # @param result [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                  # @return [Hash]
+                  #
+                  # @internal
+                  #   TODO: Remove `step.outputs.none?` to enforce users to specify outputs for all steps. Will be a breaking change.
+                  #
+                  def extract_data(result)
+                    return result.unsafe_data.to_h if result.status.unsafe_not_success?
+                    return result.unsafe_data.to_h if step.outputs.none?
+
+                    step.outputs.each { |output| ::ConvenientService.raise Exceptions::StepResultDataNotExistingAttribute.new(step: step, key: output.key.to_sym) unless result.unsafe_data.has_attribute?(output.key.to_sym) }
+
+                    step.outputs.reduce({}) { |values, output| values.merge(output.name.to_sym => result.unsafe_data[output.key.to_sym]) }
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/has_result.rb

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

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "plugins/has_result"
+
 require_relative "plugins/can_be_completed"
 require_relative "plugins/can_be_method_step"
-require_relative "plugins/can_be_result_step"
 require_relative "plugins/can_have_fallbacks"
 require_relative "plugins/can_have_parent_result"
 require_relative "plugins/has_inspect"

data/lib/convenient_service/service/plugins/can_have_steps/entities.rb

@@ -2,5 +2,4 @@
 
 require_relative "entities/service"
 require_relative "entities/method"
-require_relative "entities/step_collection"
 require_relative "entities/step"

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

@@ -2,5 +2,45 @@
 
 require_relative "can_have_steps/commands"
 require_relative "can_have_steps/concern"
-require_relative "can_have_steps/middleware"
 require_relative "can_have_steps/entities"
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        class << self
+          ##
+          # Checks whether an object is a step instance.
+          #
+          # @api public
+          #
+          # @param step [Object] Can be any type.
+          # @return [Boolean]
+          #
+          # @example Simple usage.
+          #   class Service
+          #     include ConvenientService::Standard::Config
+          #
+          #     step :result
+          #
+          #     def result
+          #       success
+          #     end
+          #   end
+          #
+          #   step = Service.new.steps.first
+          #
+          #   ConvenientService::Plugins::Service::CanHaveSteps.step?(step)
+          #   # => true
+          #
+          #   ConvenientService::Plugins::Service::CanHaveSteps.step?(42)
+          #   # => false
+          #
+          def step?(step)
+            Commands::IsStep[step: step]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_stubbed_results/commands/fetch_all_services_stubbed_results_cache.rb

@@ -16,8 +16,8 @@ module ConvenientService
             #   - https://relishapp.com/rspec/rspec-core/docs/metadata/current-example
             #
             def call
-              if Support::Gems::RSpec.current_example
-                Utils::Object.memoize_including_falsy_values(Support::Gems::RSpec.current_example, :@__convenient_service_stubbed_results__) { Support::Cache.create(backend: :thread_safe_array) }
+              if Dependencies.rspec.current_example
+                Utils::Object.memoize_including_falsy_values(Dependencies.rspec.current_example, :@__convenient_service_stubbed_results__) { Support::Cache.create(backend: :thread_safe_array) }
               else
                 Support::Cache.create(backend: :thread_safe_array)
               end

data/lib/convenient_service/service/plugins/forbids_convenient_service_entities_as_constructor_arguments/exceptions.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module ForbidsConvenientServiceEntitiesAsConstructorArguments
+        module Exceptions
+          class ServicePassedAsConstructorArgument < ::ConvenientService::Exception
+            def initialize_with_kwargs(selector:, service:, other_service:)
+              message = <<~TEXT
+                Other service `#{Utils::Class.display_name(other_service.class)}` is passed as constructor argument `#{selector}` to `#{Utils::Class.display_name(service.class)}`.
+
+                It is an antipattern. It neglects the idea of steps.
+
+                Please, try to reorganize `#{Utils::Class.display_name(service.class)}` service.
+              TEXT
+
+              initialize(message)
+            end
+          end
+
+          class ResultPassedAsConstructorArgument < ::ConvenientService::Exception
+            def initialize_with_kwargs(selector:, service:, result:)
+              message = <<~TEXT
+                Result of `#{Utils::Class.display_name(result.service.class)}` is passed as constructor argument `#{selector}` to `#{Utils::Class.display_name(service.class)}`.
+
+                It is an antipattern. It neglects the idea of steps.
+
+                Please, try to reorganize `#{Utils::Class.display_name(service.class)}` service.
+              TEXT
+
+              initialize(message)
+            end
+          end
+
+          class StepPassedAsConstructorArgument < ::ConvenientService::Exception
+            def initialize_with_kwargs(selector:, service:, step:)
+              message = <<~TEXT
+                Step of `#{step.printable_container}` is passed as constructor argument `#{selector}` to `#{Utils::Class.display_name(service.class)}`.
+
+                It is an antipattern. It neglects the idea of steps.
+
+                Please, try to reorganize `#{Utils::Class.display_name(service.class)}` service.
+              TEXT
+
+              initialize(message)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module ForbidsConvenientServiceEntitiesAsConstructorArguments
+        class Middleware < MethodChainMiddleware
+          intended_for :initialize, entity: :service
+
+          ##
+          # @return [ConvenientService::Service]
+          #
+          alias_method :service, :entity
+
+          ##
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil] Can be any type.
+          # @raise [ConvenientService::Service::Plugins::ForbidsConvenientServiceEntitiesAsConstructorArguments::Exceptions::ServicePassedAsConstructorArgument, ConvenientService::Service::Plugins::ForbidsConvenientServiceEntitiesAsConstructorArguments::Exceptions::ResultPassedAsConstructorArgument, ConvenientService::Service::Plugins::ForbidsConvenientServiceEntitiesAsConstructorArguments::Exceptions::StepPassedAsConstructorArgument]
+          # @return [void]
+          #
+          def next(*args, **kwargs, &block)
+            args.each_with_index { |value, index| validate!(:args, index, value) }
+
+            kwargs.each_pair { |key, value| validate!(:kwargs, key, value) }
+
+            chain.next(*args, **kwargs, &block)
+          end
+
+          private
+
+          ##
+          # @param collection_type [Symbol]
+          # @param key [Integer, Symbol]
+          # @param value [Object] Can be any type.
+          # @raise [ConvenientService::Service::Plugins::ForbidsConvenientServiceEntitiesAsConstructorArguments::Exceptions::ServicePassedAsConstructorArgument, ConvenientService::Service::Plugins::ForbidsConvenientServiceEntitiesAsConstructorArguments::Exceptions::ResultPassedAsConstructorArgument, ConvenientService::Service::Plugins::ForbidsConvenientServiceEntitiesAsConstructorArguments::Exceptions::StepPassedAsConstructorArgument]
+          # @return [void]
+          #
+          def validate!(collection_type, key, value)
+            refute_service!(collection_type, key, value)
+            refute_result!(collection_type, key, value)
+            refute_step!(collection_type, key, value)
+          end
+
+          ##
+          # @param collection_type [Symbol]
+          # @param key [Integer, Symbol]
+          # @param value [Object] Can be any type.
+          # @raise [ConvenientService::Service::Plugins::ForbidsConvenientServiceEntitiesAsConstructorArguments::Exceptions::ServicePassedAsConstructorArgument]
+          # @return [void]
+          #
+          # @internal
+          #   NOTE: `refute` is `!assert`.
+          #   - https://docs.seattlerb.org/minitest
+          #
+          def refute_service!(collection_type, key, value)
+            return unless ::ConvenientService.service?(value)
+
+            ::ConvenientService.raise Exceptions::ServicePassedAsConstructorArgument.new(selector: selector_from(collection_type, key), service: service, other_service: value)
+          end
+
+          ##
+          # @param collection_type [Symbol]
+          # @param key [Integer, Symbol]
+          # @param value [Object] Can be any type.
+          # @raise [ConvenientService::Service::Plugins::ForbidsConvenientServiceEntitiesAsConstructorArguments::Exceptions::ResultPassedAsConstructorArgument]
+          # @return [void]
+          #
+          # @internal
+          #   NOTE: `refute` is `!assert`.
+          #   - https://docs.seattlerb.org/minitest
+          #
+          def refute_result!(collection_type, key, value)
+            return unless ::ConvenientService::Plugins::Service::HasJSendResult.result?(value)
+
+            ::ConvenientService.raise Exceptions::ResultPassedAsConstructorArgument.new(selector: selector_from(collection_type, key), service: service, result: value)
+          end
+
+          ##
+          # @param collection_type [Symbol]
+          # @param key [Integer, Symbol]
+          # @param value [Object] Can be any type.
+          # @raise [ConvenientService::Service::Plugins::ForbidsConvenientServiceEntitiesAsConstructorArguments::Exceptions::StepPassedAsConstructorArgument]
+          # @return [void]
+          #
+          # @internal
+          #   NOTE: `refute` is `!assert`.
+          #   - https://docs.seattlerb.org/minitest
+          #
+          def refute_step!(collection_type, key, value)
+            return unless ::ConvenientService::Plugins::Service::CanHaveSteps.step?(value)
+
+            ::ConvenientService.raise Exceptions::StepPassedAsConstructorArgument.new(selector: selector_from(collection_type, key), service: service, step: value)
+          end
+
+          ##
+          # @param collection_type [Symbol]
+          # @param key [Integer, Symbol]
+          # @return [String]
+          #
+          def selector_from(collection_type, key)
+            "#{collection_type}[#{key.inspect}]"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "forbids_convenient_service_entities_as_constructor_arguments/exceptions"
+require_relative "forbids_convenient_service_entities_as_constructor_arguments/middleware"

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasAmazingPrintInspect
+        module Concern
+          include Support::Concern
+
+          instance_methods do
+            ##
+            # @return [String]
+            #
+            def inspect
+              metadata = {
+                ConvenientService: {
+                  entity: "Service",
+                  name: inspect_values[:name]
+                }
+              }
+
+              metadata.ai
+            end
+
+            ##
+            # @return [Hash{Symbol => Object}]
+            #
+            # @internal
+            #   NOTE: It is a coincidence that `HasInspect#inspect_values` has exactly the same implementation. There is NO intention to keep them in sync.
+            #
+            def inspect_values
+              {name: Utils::Class.display_name(self.class)}
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "has_amazing_print_inspect/concern"

data/lib/convenient_service/service/plugins/{can_have_steps/entities/step/plugins/can_be_result_step → has_j_send_result/entities/result/plugins/can_be_from_exception}/concern.rb

@@ -3,20 +3,22 @@
 module ConvenientService
   module Service
     module Plugins
-      module CanHaveSteps
+      module HasJSendResult
         module Entities
-          class Step
+          class Result
             module Plugins
-              module CanBeResultStep
+              module CanBeFromException
                 module Concern
                   include Support::Concern
 
                   instance_methods do
                     ##
+                    # @api public
+                    #
                     # @return [Boolean]
                     #
-                    def result_step?
-                      method_step? && method == :result
+                    def from_exception?
+                      Utils.to_bool(extra_kwargs[:from_exception])
                     end
                   end
                 end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/can_be_from_exception.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "can_be_from_exception/concern"

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/can_have_checked_status/concern.rb

@@ -15,8 +15,8 @@ module ConvenientService
                     ##
                     # @return [Boolean]
                     #
-                    def has_checked_status?
-                      Utils.to_bool(internals.cache[:has_checked_status])
+                    def checked?
+                      status.checked?
                     end
                   end
                 end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/can_have_checked_status.rb

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
 
 require_relative "can_have_checked_status/concern"
-require_relative "can_have_checked_status/middleware"