convenient_service 0.19.0 → 0.20.0

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -26,9 +31,9 @@ module ConvenientService
                     when :success
                       result
                     when :failure
-                      fallback_failure_step? ? fallback_failure_result(...) : result
-                    when :error
-                      fallback_error_step? ? fallback_error_result(...) : result
+                      fallback_failure_step? ? fallback_failure_result(result) : result
+                    else # :error
+                      fallback_error_step? ? fallback_error_result(result) : result
                     end
                   end
 
@@ -73,51 +78,22 @@ module ConvenientService
                   # @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))
+                  # @internal
+                  #   IMPORTANT: `fallback` MUST NOT create new service instance, otherwise memoized instance variables will NOT be reused.
+                  #
+                  def fallback_failure_result(result)
+                    refute_method_step! || result.with_failure_fallback(raise_when_missing: false) || ::ConvenientService.raise(Exceptions::FallbackResultIsNotOverridden.new(step: step, service: result.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.
+                  #   IMPORTANT: `fallback` MUST NOT create new service instance, otherwise memoized instance variables will NOT be reused.
                   #
-                  def service
-                    @service ||= step.service.klass.new(**step.input_values)
+                  def fallback_error_result(result)
+                    refute_method_step! || result.with_error_fallback(raise_when_missing: false) || ::ConvenientService.raise(Exceptions::FallbackResultIsNotOverridden.new(step: step, service: result.service, status: :error))
                   end
 
                   ##
@@ -128,9 +104,7 @@ module ConvenientService
                   #   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)
+                    ::ConvenientService.raise Exceptions::MethodStepCanNotHaveFallback.new(step: step) if step.method_step?
                   end
                 end
               end

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins

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

@@ -1,3 +1,8 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "can_have_parent_result/middleware"

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -20,17 +25,16 @@ module ConvenientService
                     #   - 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
+                          container: Utils::Class.display_name(container.klass)
                         }
                       }
 
-                      metadata[:ConvenientService].merge!(method_step? ? {method: ":#{method}"} : {service: service.klass.name})
+                      metadata[:ConvenientService][:method] = ":#{method}" if method_step?
+                      metadata[:ConvenientService][:service] = Utils::Class.display_name(service_class) if service_step?
 
                       metadata.ai
                     end

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

@@ -1,3 +1,8 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -20,17 +25,16 @@ module ConvenientService
                     #   - 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
+                          container: Utils::Class.display_name(container.klass)
                         }
                       }
 
-                      metadata[:ConvenientService].merge!(method_step? ? {method: ":#{method}"} : {service: service.klass.name})
+                      metadata[:ConvenientService][:method] = ":#{method}" if method_step?
+                      metadata[:ConvenientService][:service] = Utils::Class.display_name(service_class) if service_step?
 
                       metadata.ai
                     end

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

@@ -1,3 +1,8 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "has_awesome_print_inspect/concern"

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -15,13 +20,11 @@ module ConvenientService
                     ##
                     # @return [String]
                     #
-                    # @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?
+                      return "<#{Utils::Class.display_name(container.klass)}::Step method: :#{method}>" if method_step?
+                      return "<#{Utils::Class.display_name(container.klass)}::Step service: #{Utils::Class.display_name(service_class)}>" if service_step?
 
-                      "<#{container.klass.name}::Step service: #{service.klass.name}>"
+                      "<#{Utils::Class.display_name(container.klass)}::Step>"
                     end
                   end
                 end

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

@@ -1,3 +1,8 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "has_inspect/concern"

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -13,14 +18,10 @@ module ConvenientService
 
                   instance_methods do
                     ##
-                    # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
-                    # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
-                    #
-                    # @internal
-                    #   TODO: `service.result`.
+                    # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Plugins::HasResult::Exceptions::StepHasUnknownType]
                     #
                     def result
-                      service_result
+                      ::ConvenientService.raise Exceptions::StepHasUnknownType.new(step: self)
                     end
                   end
                 end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module HasResult
+                module Exceptions
+                  class StepHasUnknownType < ::ConvenientService::Exception
+                    ##
+                    # @param step [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+                    # @return [void]
+                    #
+                    def initialize_with_kwargs(step:)
+                      message = <<~TEXT
+                        Step `#{step.printable_action}` has unknown type.
+
+                        Please, ensure the first `step` argument has NO typos.
+                      TEXT
+
+                      initialize(message)
+                    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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -7,6 +12,9 @@ module ConvenientService
         module Entities
           class Step
             module Plugins
+              ##
+              # TODO: Rename.
+              #
               module HasResult
                 class Middleware < MethodChainMiddleware
                   intended_for :result, entity: :step
@@ -27,7 +35,18 @@ module ConvenientService
                   def next(...)
                     result = chain.next(...)
 
-                    result.copy(overrides: {kwargs: {data: extract_data(result), step: step, service: step.organizer}})
+                    result = result.strict if step.strict?
+
+                    result.copy(
+                      overrides: {
+                        kwargs: {
+                          data: extract_data(result),
+                          step: step,
+                          service: step.organizer,
+                          original_service: result.original_service
+                        }
+                      }
+                    )
                   end
 
                   private
@@ -38,14 +57,26 @@ module ConvenientService
                   #
                   # @internal
                   #   TODO: Remove `step.outputs.none?` to enforce users to specify outputs for all steps. Will be a breaking change.
+                  #   NOTE: `result_outputs` are usual and alias outputs.
+                  #   NOTE: `custom_outputs` are proc and raw outputs.
                   #
                   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) }
+                    result_outputs, custom_outputs = step.outputs.partition { |output| output.usual? || output.alias? }
+
+                    result_outputs.each do |output|
+                      next if result.unsafe_data.__has_attribute__?(output.key.to_sym)
+
+                      ::ConvenientService.raise Step::Exceptions::StepResultDataNotExistingAttribute.new(step: step, key: output.key.to_sym)
+                    end
+
+                    result_values = result_outputs.reduce({}) { |values, output| values.merge(output.name.to_sym => result.unsafe_data[output.key.to_sym]) }
+
+                    custom_values = custom_outputs.reduce({}) { |values, output| values.merge(output.name.to_sym => output.value) }
 
-                    step.outputs.reduce({}) { |values, output| values.merge(output.name.to_sym => result.unsafe_data[output.key.to_sym]) }
+                    result_values.merge(custom_values)
                   end
                 end
               end

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

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "has_result/concern"
+require_relative "has_result/exceptions"
 require_relative "has_result/middleware"

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -12,7 +17,7 @@ module ConvenientService
                   class ReturnValueNotKindOfResult < ::ConvenientService::Exception
                     def initialize_with_kwargs(step:, result:)
                       message = <<~TEXT
-                        Return value of step `#{step.printable_service}` is NOT a `Result`.
+                        Return value of step `#{step.printable_action}` is NOT a `Result`.
                         It is `#{result.class}`.
 
                         Did you forget to call `success`, `failure`, or `error`?

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -9,16 +14,12 @@ module ConvenientService
             module Plugins
               module RaisesOnNotResultReturnValue
                 class Middleware < MethodChainMiddleware
-                  include Support::DependencyContainer::Import
-
-                  import :"commands.is_result?", from: ::ConvenientService::Service::Plugins::HasJSendResult::Container
-
                   intended_for any_method, entity: :step
 
                   def next(...)
                     original_result = chain.next(...)
 
-                    return original_result if commands.is_result?(original_result)
+                    return original_result if ConvenientService::Service::Plugins::HasJSendResult.result?(original_result)
 
                     ::ConvenientService.raise Exceptions::ReturnValueNotKindOfResult.new(step: entity, result: original_result)
                   end

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

@@ -1,4 +1,9 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "raises_on_not_result_return_value/exceptions"
 require_relative "raises_on_not_result_return_value/middleware"

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

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "plugins/has_result"
 
 require_relative "plugins/can_be_completed"
+require_relative "plugins/can_be_service_step"
 require_relative "plugins/can_be_method_step"
 require_relative "plugins/can_have_fallbacks"
 require_relative "plugins/can_have_parent_result"

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -7,7 +12,11 @@ module ConvenientService
         module Entities
           class Step
             module Structs
-              Params = ::Struct.new(:service, :inputs, :outputs, :index, :container, :organizer, :extra_kwargs, keyword_init: true)
+              Params = ::Struct.new(:action, :inputs, :outputs, :strict, :index, :container, :organizer, :extra_kwargs, keyword_init: true) do
+                def to_callback_arguments
+                  Support::Arguments.new(action, in: inputs, out: outputs, strict: strict, index: index, **extra_kwargs)
+                end
+              end
             end
           end
         end

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

@@ -1,3 +1,8 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "structs/params"

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "step/commands"
 require_relative "step/concern"
 require_relative "step/exceptions"

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "entities/service"
 require_relative "entities/method"
 require_relative "entities/step"

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        class Middleware < MethodChainMiddleware
+          intended_for :initialize, entity: :service
+
+          ##
+          # @return [void]
+          #
+          # @internal
+          #   NOTE:
+          #     Initializes service steps.
+          #     That is done to commit(define) steps output methods before the first service instance created.
+          #     This way `respond_to?` becomes consistent.
+          #
+          def next(...)
+            entity.steps
+
+            chain.next(...)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,14 +1,55 @@
 # frozen_string_literal: true
 
-require_relative "can_have_steps/commands"
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "can_have_steps/concern"
 require_relative "can_have_steps/entities"
+require_relative "can_have_steps/middleware"
 
 module ConvenientService
   module Service
     module Plugins
       module CanHaveSteps
         class << self
+          ##
+          # Checks whether an object is a step class.
+          #
+          # @api public
+          #
+          # @param step_class [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_class?(step.class)
+          #   # => true
+          #
+          #   ConvenientService::Plugins::Service::CanHaveSteps.step_class?(step)
+          #   # => false
+          #
+          #   ConvenientService::Plugins::Service::CanHaveSteps.step_class?(42)
+          #   # => false
+          #
+          def step_class?(step_class)
+            return false unless step_class.instance_of?(::Class)
+
+            step_class.include?(Entities::Step::Concern)
+          end
+
           ##
           # Checks whether an object is a step instance.
           #
@@ -33,11 +74,14 @@ module ConvenientService
           #   ConvenientService::Plugins::Service::CanHaveSteps.step?(step)
           #   # => true
           #
+          #   ConvenientService::Plugins::Service::CanHaveSteps.step?(step.class)
+          #   # => false
+          #
           #   ConvenientService::Plugins::Service::CanHaveSteps.step?(42)
           #   # => false
           #
           def step?(step)
-            Commands::IsStep[step: step]
+            step_class?(step.class)
           end
         end
       end