convenient_service 0.12.0 → 0.14.0

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module CanBeMethodStep
+                module CanBePrinted
+                  class Middleware < MethodChainMiddleware
+                    intended_for :printable_service, entity: :step
+
+                    ##
+                    # @return [String]
+                    #
+                    def next(...)
+                      return chain.next(...) unless entity.method_step?
+
+                      ":#{entity.method}"
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "can_be_printed/middleware"

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module CanBeMethodStep
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    ##
+                    # @return [Symbol, nil]
+                    #
+                    def method
+                      extra_kwargs[:method]
+                    end
+
+                    ##
+                    # @return [Boolean]
+                    #
+                    def method_step?
+                      Utils.to_bool(method)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "can_be_method_step/concern"
+
+require_relative "can_be_method_step/can_be_executed"
+require_relative "can_be_method_step/can_be_printed"

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/can_be_result_step/can_be_executed/exceptions.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module CanBeResultStep
+                module CanBeExecuted
+                  module Exceptions
+                    class MethodForStepIsNotDefined < ::ConvenientService::Exception
+                      ##
+                      # @param service_class [Class]
+                      # @param method_name [Symbol]
+                      # @return [void]
+                      #
+                      def initialize(service_class:, method_name:)
+                        message = <<~TEXT
+                          Service `#{service_class}` tries to use `:#{method_name}` method in a step, but it is NOT defined.
+
+                          Did you forget to define it?
+                        TEXT
+
+                        super(message)
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module CanBeResultStep
+                module CanBeExecuted
+                  class Middleware < MethodChainMiddleware
+                    intended_for :service_result, entity: :step
+
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                    # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Plugins::CanBeResultStep::CanBeExecuted::Exceptions::MethodForStepIsNotDefined]
+                    #
+                    # @internal
+                    #   NOTE: `kwargs` are intentionally NOT passed to `own_method.call`, since all the corresponding methods are available inside `own_method` body.
+                    #
+                    def next(...)
+                      return chain.next(...) unless entity.result_step?
+
+                      return own_method.call if own_method
+
+                      raise Exceptions::MethodForStepIsNotDefined.new(service_class: organizer.class, method_name: method_name)
+                    end
+
+                    private
+
+                    ##
+                    # @return [Method, nil]
+                    #
+                    # @internal
+                    #   TODO: A possible bottleneck. Should be removed if receives negative feedback.
+                    #
+                    #   NOTE: `own_method.bind(organizer).call` is logically the same as `own_method.bind_call(organizer)`.
+                    #   - https://ruby-doc.org/core-2.7.1/UnboundMethod.html#method-i-bind_call
+                    #   - https://blog.saeloun.com/2019/10/17/ruby-2-7-adds-unboundmethod-bind_call-method.html
+                    #
+                    def own_method
+                      method = Utils::Module.get_own_instance_method(organizer.class, method_name, private: true)
+
+                      return unless method
+
+                      method.bind(organizer)
+                    end
+
+                    ##
+                    # @return [ConvenientService::Service]
+                    #
+                    def organizer
+                      @organizer ||= entity.organizer
+                    end
+
+                    ##
+                    # @return [Symbol]
+                    #
+                    def method_name
+                      @method_name ||= entity.method
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module CanBeResultStep
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    ##
+                    # @return [Boolean]
+                    #
+                    def result_step?
+                      method_step? && method == :result
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "can_be_result_step/concern"
+
+require_relative "can_be_result_step/can_be_executed"

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module CanHaveFallbacks
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    ##
+                    # @return [Bool]
+                    #
+                    def fallback_true_step?
+                      params.extra_kwargs[:fallback] == true
+                    end
+
+                    ##
+                    # @return [Bool]
+                    #
+                    def fallback_failure_step?
+                      Utils::Array.wrap(params.extra_kwargs[:fallback]).include?(:failure)
+                    end
+
+                    ##
+                    # @return [Bool]
+                    #
+                    def fallback_error_step?
+                      Utils::Array.wrap(params.extra_kwargs[:fallback]).include?(:error)
+                    end
+
+                    ##
+                    # @return [Bool]
+                    #
+                    def fallback_step?
+                      fallback_true_step? || fallback_failure_step? || fallback_error_step?
+                    end
+
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                    # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                    #
+                    # @note `service_fallback_failure_result` has middlewares.
+                    #
+                    # @internal
+                    #   IMPORTANT: `service.klass.fallback_failure_result(**input_values)` is the reason, why services should have only kwargs as arguments.
+                    #   TODO: Extract `StepDefinition`. This way `has_organizer?` check can be avoided completely.
+                    #
+                    def service_fallback_failure_result
+                      service.klass.fallback_failure_result(**input_values)
+                    end
+
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                    # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                    # @note `fallback_failure_result` has middlewares.
+                    #
+                    def fallback_failure_result
+                      convert_to_step_result(service_fallback_failure_result)
+                    end
+
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                    # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                    #
+                    # @note `service_fallback_error_result` has middlewares.
+                    #
+                    # @internal
+                    #   IMPORTANT: `service.klass.fallback_error_result(**input_values)` is the reason, why services should have only kwargs as arguments.
+                    #   TODO: Extract `StepDefinition`. This way `has_organizer?` check can be avoided completely.
+                    #
+                    def service_fallback_error_result
+                      service.klass.fallback_error_result(**input_values)
+                    end
+
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                    # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                    # @note `fallback_error_result` has middlewares.
+                    #
+                    def fallback_error_result
+                      convert_to_step_result(service_fallback_error_result)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module CanHaveFallbacks
+                class Middleware < MethodChainMiddleware
+                  intended_for :result, entity: :step
+
+                  ##
+                  # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                  #
+                  def next(...)
+                    result = chain.next(...)
+
+                    case result.status.to_sym
+                    when :success
+                      result
+                    when :failure
+                      fallback_failure_step? ? entity.fallback_failure_result(...) : result
+                    when :error
+                      fallback_error_step? ? entity.fallback_error_result(...) : result
+                    end
+                  end
+
+                  private
+
+                  ##
+                  # @return [Boolean]
+                  #
+                  def fallback_failure_step?
+                    entity.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
+                  end
+
+                  ##
+                  # @return [Boolean]
+                  #
+                  def fallback_error_step?
+                    entity.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
+                  end
+
+                  ##
+                  # @return [Symbol]
+                  #
+                  def fallback_true_status
+                    middleware_arguments.kwargs.fetch(:fallback_true_status) { :failure }
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "result/middleware"

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

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

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

@@ -8,9 +8,11 @@ module ConvenientService
           class Step
             module Plugins
               module CanHaveParentResult
-                class Middleware < Core::MethodChainMiddleware
+                class Middleware < MethodChainMiddleware
+                  intended_for :result, entity: :step
+
                   def next(...)
-                    chain.next(...).copy(overrides: {kwargs: {parent: entity.original_result}})
+                    chain.next(...).copy(overrides: {kwargs: {parent: entity.service_result}})
                   end
                 end
               end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module HasAwesomePrintInspect
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    ##
+                    # @return [String]
+                    #
+                    # @internal
+                    #   NOTE: `ai` is a part of public interface of `awesome_print`.
+                    #   - https://github.com/awesome-print/awesome_print#usage
+                    #   - https://github.com/awesome-print/awesome_print/blob/master/lib/awesome_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,
+                          **(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_awesome_print_inspect.rb

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

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

@@ -14,9 +14,13 @@ module ConvenientService
                   instance_methods do
                     ##
                     # @return [String]
-                    # @since 0.2.0
+                    #
+                    # @internal
+                    #   TODO: `inspect_values` for class. This way `service_class.name || ...` can be shared.
                     #
                     def inspect
+                      return "<#{container.klass.name}::Step method: :#{method}>" if method_step?
+
                       "<#{container.klass.name}::Step service: #{service.klass.name}>"
                     end
                   end

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

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+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/step/structs/params.rb

@@ -7,7 +7,7 @@ module ConvenientService
         module Entities
           class Step
             module Structs
-              Params = ::Struct.new(:service, :inputs, :outputs, :index, :container, :organizer, keyword_init: true)
+              Params = ::Struct.new(:service, :inputs, :outputs, :index, :container, :organizer, :extra_kwargs, keyword_init: true)
             end
           end
         end

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

@@ -2,7 +2,7 @@
 
 require_relative "step/commands"
 require_relative "step/concern"
-require_relative "step/errors"
+require_relative "step/exceptions"
 require_relative "step/plugins"
 require_relative "step/structs"
 

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

@@ -4,34 +4,63 @@ module ConvenientService
   module Service
     module Plugins
       module CanHaveSteps
-        class Middleware < Core::MethodChainMiddleware
+        class Middleware < MethodChainMiddleware
+          intended_for :result, entity: :service
+
           ##
           # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
           #
           def next(...)
             return chain.next(...) if entity.steps.none?
 
-            last_step.result.copy
+            last_completed_step.result
           end
 
           private
 
           ##
+          # Steps are executed in the same order as they were defined by the end user.
+          # A step is considered completed right after its status is checked.
+          # If a NOT successful step is encountered, all the remaining steps are NOT evaluated.
+          # As a result, the `last_completed_step` is either the first NOT successful step or the last step from all steps.
+          #
           # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
           #
-          def last_step
-            @last_step ||= entity.steps.find.with_index { |step, index| not_success?(step, index) } || entity.steps.last
+          def last_completed_step
+            @last_completed_step ||= find_first_not_successful_step_with_side_effects_during_lookup || just_take_last_step_since_all_steps_are_successful
           end
 
           ##
-          # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+          # Finds first not successful step.
+          # Runs (intentional) side effects during the lookup.
+          # The lookup is made by Ruby's `Enumerable#find`.
+          # As a result, side effects are executed only for evaluated steps.
+          #
+          # Each iteration marks step as completed.
+          # Each iteration triggers callback.
+          #
+          # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step, nil]
           #
           # @internal
-          #   NOTE: `entity.step(index)` is used as a hook (callbacks trigger).
-          #   IMPORTANT: `step` status MUST be checked before triggering callbacks.
+          #   IMPORTANT: `step` status MUST be checked before marking it as completed.
+          #   IMPORTANT: `step` status MUST be checked before triggering callback.
+          #
+          #   NOTE: @marian13 you already tried to come up with a better name to express the idea that this method has side effects numerous amount of times.
+          #   Do NOT spend too much time on that again, you have a lot of other tasks to do.
+          #
+          def find_first_not_successful_step_with_side_effects_during_lookup
+            entity.steps.find do |step|
+              step.not_success?(mark_status_as_checked: false)
+                .tap { step.mark_as_completed! }
+                .tap { step.trigger_callback }
+            end
+          end
+
+          ##
+          # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
           #
-          def not_success?(step, index)
-            step.not_success?.tap { entity.step(index) }
+          def just_take_last_step_since_all_steps_are_successful
+            entity.steps.last
           end
         end
       end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveStubbedResults
+        module Commands
+          class FetchAllServicesStubbedResultsCache < Support::Command
+            ##
+            # @return [ConvenientService::Support::Cache]
+            #
+            # @internal
+            #   NOTE: `::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
+            #
+            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) }
+              else
+                Support::Cache.create(backend: :thread_safe_array)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end