convenient_service 0.12.0 → 0.13.0

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

@@ -5,40 +5,124 @@ module ConvenientService
     module Plugins
       module CanHaveSteps
         module Entities
+          ##
+          # @internal
+          #   TODO: Extract `StepDefinition`. This way `has_organizer?` check can be avoided completely.
+          #
           class Step
             module Concern
               module InstanceMethods
                 include Support::Copyable
                 include Support::Delegate
 
-                delegate \
-                  :success?,
-                  :failure?,
-                  :error?,
-                  :not_success?,
-                  :not_failure?,
-                  :not_error?,
-                  :data,
-                  :message,
-                  :code,
-                  :unsafe_data,
-                  :unsafe_message,
-                  :unsafe_code,
-                  to: :result
-
-                delegate \
-                  :service,
-                  :outputs,
-                  :index,
-                  :container,
-                  :organizer,
-                  to: :params
+                ##
+                # @return [Boolean]
+                #
+                delegate :success?, to: :result
+
+                ##
+                # @return [Boolean]
+                #
+                delegate :failure?, to: :result
+
+                ##
+                # @return [Boolean]
+                #
+                delegate :error?, to: :result
+
+                ##
+                # @return [Boolean]
+                #
+                delegate :not_success?, to: :result
+
+                ##
+                # @return [Boolean]
+                #
+                delegate :not_failure?, to: :result
+
+                ##
+                # @return [Boolean]
+                #
+                delegate :not_error?, to: :result
+
+                ##
+                # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Data]
+                #
+                delegate :data, to: :result
+
+                ##
+                # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Message]
+                #
+                delegate :message, to: :result
+
+                ##
+                # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Code]
+                #
+                delegate :code, to: :result
+
+                ##
+                # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Data]
+                #
+                delegate :unsafe_data, to: :result
+
+                ##
+                # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Message]
+                #
+                delegate :unsafe_message, to: :result
+
+                ##
+                # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Code]
+                #
+                delegate :unsafe_code, to: :result
 
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                #
+                # @internal
+                #   TODO: Return service instance to be compatible with result.
+                #
+                delegate :service, to: :params
+
+                ##
+                # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method>]
+                #
+                # @internal
+                #   TODO: Create dedicated classes for input and output methods.
+                #
+                delegate :outputs, to: :params
+
+                ##
+                # @return [Integer]
+                #
+                delegate :index, to: :params
+
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                #
+                delegate :container, to: :params
+
+                ##
+                # @return [Hash{Symbol => Object}]
+                #
+                delegate :extra_kwargs, to: :params
+
+                ##
+                # @param args [Array<Object>]
+                # @param kwargs [Hash{Symbol => Object}]
+                # @return [void]
+                #
                 def initialize(*args, **kwargs)
                   @args = args
                   @kwargs = kwargs
                 end
 
+                ##
+                # @param other [Object] Can be any type.
+                # @return [Boolean, nil]
+                #
+                # @internal
+                #   TODO: Currently `==` does NOT compare `extra_kwargs`. Is it OK?
+                #
                 def ==(other)
                   return unless other.instance_of?(self.class)
 
@@ -47,52 +131,111 @@ module ConvenientService
                   return false if outputs != other.outputs
                   return false if index != other.index
                   return false if container != other.container
-                  return false if organizer != other.organizer
+                  return false if organizer(raise_when_missing: false) != other.organizer(raise_when_missing: false)
 
                   true
                 end
 
+                ##
+                # @return [Boolean]
+                #
                 def has_organizer?
-                  Utils::Bool.to_bool(organizer)
+                  Utils.to_bool(organizer(raise_when_missing: false))
                 end
 
+                ##
+                # @return [Boolean]
+                # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                #
                 def has_reassignment?(name)
                   outputs.any? { |output| output.reassignment?(name) }
                 end
 
-                def completed?
-                  Utils::Bool.to_bool(@completed)
-                end
-
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method, nil]
+                # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                #
                 def reassignment(name)
                   outputs.find { |output| output.reassignment?(name) }
                 end
 
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Structs::Params]
+                #
                 def params
                   @params ||= resolve_params
                 end
 
+                ##
+                # @return [ConvenientService::Service]
+                # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                #
+                # @internal
+                #   NOTE: `raise_when_missing` option is inspired by `where.missing` in Rails.
+                #   - https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods/WhereChain.html#method-i-missing
+                #   - https://boringrails.com/tips/activerecord-where-missing-associations
+                #
+                def organizer(raise_when_missing: true)
+                  @organizer ||= params.organizer
+
+                  raise Exceptions::StepHasNoOrganizer.new(step: self) if @organizer.nil? && raise_when_missing
+
+                  @organizer
+                end
+
+                ##
+                # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method>]
+                #
                 def inputs
-                  @inputs ||= params.inputs.map { |input| input.copy(overrides: {kwargs: {organizer: organizer}}) }
+                  @inputs ||= params.inputs.map { |input| input.copy(overrides: {kwargs: {organizer: organizer(raise_when_missing: false)}}) }
                 end
 
+                ##
+                # @return [Hash{Symbol => Object}]
+                # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                #
                 def input_values
                   @input_values ||= calculate_input_values
                 end
 
-                def original_result
-                  @original_result ||= calculate_original_result
+                ##
+                # @return [Hash{Symbol => Object}]
+                # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                #
+                def output_values
+                  @output_values ||= result.unsafe_data.to_h.slice(*outputs.map(&:key).map(&:to_sym))
                 end
 
-                def result
-                  @result ||= calculate_result
+                ##
+                # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                #
+                # @note `service_result` has middlewares.
+                #
+                # @internal
+                #   IMPORTANT: `service.result(**input_values)` is the reason, why services should have only kwargs as arguments.
+                #
+                #   NOTE: `service_result` returns a foreign result that is later converted to own result by `convert_to_step_result` in `result`.
+                #
+                def service_result
+                  service.klass.result(**input_values)
                 end
 
                 ##
-                # @return [String]
+                # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                #
+                # @note `result` has middlewares.
                 #
                 # @internal
-                #   TODO: printable service for methods steps.
+                #   NOTE: Convents a foreign result received from `service_result` to own result.
+                #
+                def result
+                  convert_to_step_result(service_result)
+                end
+
+                ##
+                # @return [String]
                 #
                 def printable_service
                   service.klass.to_s
@@ -105,6 +248,18 @@ module ConvenientService
                   service.klass
                 end
 
+                ##
+                # @return [void]
+                # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                #
+                def trigger_callback
+                  organizer.step(index)
+                end
+
+                ##
+                # @return [void]
+                # @raise [ConvenientService::Error]
+                #
                 def validate!
                   inputs.each { |input| input.validate_as_input_for_container!(container) }
 
@@ -113,67 +268,77 @@ module ConvenientService
                   true
                 end
 
+                ##
+                # @return [void]
+                #
                 def define!
                   outputs.each { |output| output.define_output_in_container!(container, index: index) }
 
                   true
                 end
 
+                ##
+                # @return [Array<Object>]
+                #
                 def to_args
-                  [service]
+                  to_arguments.args
                 end
 
+                ##
+                # @return [Hash{Symbol => Object}]
+                #
                 def to_kwargs
-                  {in: inputs, out: outputs, index: index, container: container, organizer: organizer}
+                  to_arguments.kwargs
+                end
+
+                ##
+                # @return [ConveninentService::Support::Arguments]
+                #
+                def to_arguments
+                  Support::Arguments.new(service, **kwargs.merge(in: inputs, out: outputs, index: index, container: container, organizer: organizer(raise_when_missing: false)))
                 end
 
                 private
 
-                attr_reader :args, :kwargs
+                ##
+                # @!attribute [r] args
+                #   @return [Array]
+                #
+                attr_reader :args
+
+                ##
+                # @!attribute [r] kwargs
+                #   @return [Hash]
+                #
+                attr_reader :kwargs
 
                 ##
+                # @return [Hash{Symbol => Object}]
+                # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                #
                 # @internal
                 #   TODO: Commands instead of private methods.
                 #
                 def calculate_input_values
-                  assert_has_organizer!
-
                   inputs.reduce({}) { |values, input| values.merge(input.key.to_sym => input.value) }
                 end
 
                 ##
-                # @internal
-                #   IMPORTANT: `service.result(**input_values)` is the reason, why services should have only kwargs as arguments.
+                # @param result [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
                 #
-                def calculate_original_result
-                  assert_has_organizer!
-
-                  result = service.result(**input_values)
-
-                  mark_as_completed!
-
-                  result
-                end
-
-                def calculate_result
-                  original_result.copy(overrides: {kwargs: {step: self, service: organizer}})
+                def convert_to_step_result(result)
+                  result.copy(overrides: {kwargs: {step: self, service: organizer}})
                 end
 
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Structs::Params]
+                #
                 def resolve_params
                   original_params = Commands::ExtractParams.call(args: args, kwargs: kwargs)
 
                   Commands::CastParams.call(original_params: original_params)
                 end
-
-                def assert_has_organizer!
-                  return if has_organizer?
-
-                  raise Errors::StepHasNoOrganizer.new(step: self)
-                end
-
-                def mark_as_completed!
-                  @completed = true
-                end
               end
             end
           end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/{errors.rb → exceptions.rb}

@@ -6,11 +6,11 @@ module ConvenientService
       module CanHaveSteps
         module Entities
           class Step
-            module Errors
-              class StepHasNoOrganizer < ::ConvenientService::Error
+            module Exceptions
+              class StepHasNoOrganizer < ::ConvenientService::Exception
                 def initialize(step:)
                   message = <<~TEXT
-                    Step `#{step.service}` has not assigned organizer.
+                    Step `#{step.printable_service}` has not assigned organizer.
 
                     Did you forget to set it?
                   TEXT

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module CanBeCompleted
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    ##
+                    # @return [Bool]
+                    #
+                    def completed?
+                      Utils.to_bool(internals.cache[:completed])
+                    end
+
+                    ##
+                    # @return [Bool]
+                    #
+                    def not_completed?
+                      !completed?
+                    end
+
+                    ##
+                    # @return [void]
+                    #
+                    def mark_as_completed!
+                      internals.cache[:completed] = true
+                    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_completed.rb

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

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module CanBeMethodStep
+                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 `object.__send__(method)`, since all the corresponding methods are available inside `entity.organizer.__send__(entity.method)` body.
+                    #
+                    def next(...)
+                      return chain.next(...) unless entity.method_step?
+
+                      entity.organizer.__send__(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_executed.rb

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

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