convenient_service 0.16.0 → 0.18.0

data/lib/convenient_service/service/plugins/{can_have_steps → can_have_sequential_steps}/entities/step_collection.rb

@@ -3,11 +3,21 @@
 module ConvenientService
   module Service
     module Plugins
-      module CanHaveSteps
+      module CanHaveSequentialSteps
         module Entities
           class StepCollection
             include ::Enumerable
 
+            include Support::Copyable
+
+            ##
+            # @api private
+            #
+            # @!attribute [r] container
+            #   @return [ConvenientService::Service]
+            #
+            attr_reader :container
+
             ##
             # @api private
             #
@@ -19,13 +29,35 @@ module ConvenientService
             ##
             # @api private
             #
+            # @param container [ConvenientService::Service]
             # @param steps [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
             # @return [void]
             #
-            def initialize(steps: [])
+            def initialize(container:, steps: [])
+              @container = container
               @steps = steps
             end
 
+            ##
+            # @api private
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+            #
+            def create(*args, **kwargs)
+              step_class.new(*args, **kwargs.merge(container: container, index: next_available_index))
+                .tap { |step| steps << step }
+            end
+
+            ##
+            # @param organizer [ConvenientService::Service]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::StepCollection]
+            #
+            def with_organizer(organizer)
+              copy(overrides: {kwargs: {steps: steps.map { |step| step.with_organizer(organizer) }}})
+            end
+
             ##
             # @api public
             #
@@ -43,6 +75,8 @@ module ConvenientService
 
               steps.each(&:define!).freeze
 
+              freeze
+
               true
             end
 
@@ -81,15 +115,10 @@ module ConvenientService
             end
 
             ##
-            # @api private
+            # @return [String]
             #
-            # @param step [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
-            # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::StepCollection]
-            #
-            def <<(step)
-              steps << step.copy(overrides: {kwargs: {index: next_available_index}})
-
-              self
+            def inspect
+              steps.inspect
             end
 
             ##
@@ -101,11 +130,19 @@ module ConvenientService
             def ==(other)
               return unless other.instance_of?(self.class)
 
+              return false if container != other.container
               return false if steps != other.steps
 
               true
             end
 
+            ##
+            # @return [ConvenientService::Support::Arguments]
+            #
+            def to_arguments
+              Support::Arguments.new(container: container, steps: steps)
+            end
+
             private
 
             ##
@@ -114,6 +151,13 @@ module ConvenientService
             def next_available_index
               steps.size
             end
+
+            ##
+            # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+            #
+            def step_class
+              container.step_class
+            end
           end
         end
       end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "entities/step_collection"

data/lib/convenient_service/service/plugins/{can_have_steps → can_have_sequential_steps}/middleware.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Service
     module Plugins
-      module CanHaveSteps
+      module CanHaveSequentialSteps
         class Middleware < MethodChainMiddleware
           intended_for :result, entity: :service
 
@@ -50,7 +50,8 @@ module ConvenientService
           #
           def find_first_not_successful_step_with_side_effects_during_lookup
             entity.steps.find do |step|
-              step.not_success?(mark_status_as_checked: false)
+              step.status.unsafe_not_success?
+                .tap { step.save_outputs_in_organizer! }
                 .tap { step.mark_as_completed! }
                 .tap { step.trigger_callback }
             end
@@ -59,8 +60,11 @@ module ConvenientService
           ##
           # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
           #
+          # @internal
+          #   NOTE: Custom `Enumerable` objects do NOT implement the `last` method. It is available for `Array` instances.
+          #
           def just_take_last_step_since_all_steps_are_successful
-            entity.steps.last
+            entity.steps[-1]
           end
         end
       end

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

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "can_have_sequential_steps/concern"
+require_relative "can_have_sequential_steps/middleware"
+require_relative "can_have_sequential_steps/entities"

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

@@ -7,62 +7,12 @@ module ConvenientService
         module Concern
           include Support::Concern
 
-          instance_methods do
-            ##
-            # @api public
-            #
-            # @note May be useful for debugging purposes.
-            # @see https://marian13.github.io/convenient_service_docs/guides/how_to_debug_services_via_callbacks
-            #
-            # @note `steps` are frozen.
-            # @see https://marian13.github.io/convenient_service_docs/faq#is-it-possible-to-modify-the-step-collection-from-a-callback
-            #
-            # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
-            #
-            # @internal
-            #   IMPORTANT: `map` result is NOT wrapped by `StepCollection` in order to NOT expose too much internals to the end-user.
-            #
-            def steps
-              internals.cache.fetch(:steps) do
-                self.class
-                  .steps
-                  .tap(&:commit!)
-                  .map { |step| step.copy(overrides: {kwargs: {organizer: self}}) }
-                  .freeze
-              end
-            end
-
-            ##
-            # Returns step by index.
-            # Returns `nil` when index is out of range.
-            #
-            # @param index [Integer]
-            # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
-            #
-            # @note This method was initially designed as a hook (callback trigger).
-            # @see ConvenientService::Service::Plugins::CanHaveSteps::Middleware#next
-            #
-            def step(index)
-              steps[index]
-            end
-          end
-
           class_methods do
             ##
-            # Registers a step (step definition).
-            #
-            # @param args [Array<Object>]
-            # @param kwargs [Hash{Symbol => Object}]
-            # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+            # @api public
             #
-            def step(*args, **kwargs)
-              step_class.new(*args, **kwargs.merge(container: self))
-                .tap { |step_instance| steps << step_instance }
-            end
-
-            ##
             # Allows to pass a value to `in` method without its intermediate processing.
-            # @see https://marian13.github.io/convenient_service_docs/basics/step_to_result_translation_table
+            # @see https://userdocs.convenientservice.org/basics/step_to_result_translation_table
             #
             # @example `:chat_v2` is passed to `AssertFeatureEnabled` as it is.
             #   step AssertFeatureEnabled, in: {name: raw(:chat_v2)}
@@ -77,6 +27,8 @@ module ConvenientService
             end
 
             ##
+            # @api public
+            #
             # @param method_name [String, Symbol]
             # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Values::Reassignment]
             #
@@ -85,13 +37,8 @@ module ConvenientService
             end
 
             ##
-            # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::StepCollection]
+            # @api private
             #
-            def steps
-              @steps ||= Entities::StepCollection.new
-            end
-
-            ##
             # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
             #
             def step_class

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/commands/define_method_in_container.rb

@@ -10,48 +10,67 @@ module ConvenientService
               class DefineMethodInContainer < Support::Command
                 include Support::Delegate
 
-                attr_reader :method, :container, :index
+                ##
+                # @!attribute [r] method
+                #   @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                #
+                attr_reader :method
 
-                delegate :key, :name, to: :method
+                ##
+                # @!attribute [r] container
+                #   @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                #
+                attr_reader :container
 
+                ##
+                # @!attribute [r] index
+                #   @return [Integer]
+                #
+                attr_reader :index
+
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Key]
+                #
+                delegate :key, to: :method
+
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Name]
+                #
+                delegate :name, to: :method
+
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @param index [Integer]
+                # @return [void]
+                #
                 def initialize(method:, container:, index:)
                   @method = method
                   @container = container
                   @index = index
                 end
 
+                ##
+                # @return [Boolean]
+                #
+                # @internal
+                #   IMPORTANT: Do NOT depend on `index` inside generated method. It breaks reassignments.
+                #
                 def call
-                  ##
-                  # NOTE: Assignement in the beginning for easier debugging.
-                  #
                   <<~RUBY.tap { |code| container.klass.class_eval(code, __FILE__, __LINE__ + 1) }
+                    ##
+                    # @return [Object] Can be any type.
+                    # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Exceptions::OutMethodStepIsNotCompleted]
+                    #
                     def #{name}
-                      step, key, method_name = steps[#{index}], :#{key}, :#{name}
-
-                      raise #{not_completed_step_error}.new(step: step, method_name: method_name) unless step.completed?
-
-                      raise #{not_existing_step_result_data_attribute_error}.new(step: step, key: key) unless step.result.unsafe_data.has_attribute?(key)
-
-                      step.result.unsafe_data[key]
+                      internals.cache.scope(:step_output_values).fetch(__method__) do
+                        ::ConvenientService.raise ::ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Exceptions::OutMethodStepIsNotCompleted.new(method_name: __method__)
+                      end
                     end
                   RUBY
 
                   true
                 end
-
-                private
-
-                def not_completed_step_error
-                  <<~RUBY.chomp
-                    ::ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Exceptions::NotCompletedStep
-                  RUBY
-                end
-
-                def not_existing_step_result_data_attribute_error
-                  <<~RUBY.chomp
-                    ::ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Exceptions::NotExistingStepResultDataAttribute
-                  RUBY
-                end
               end
             end
           end

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

@@ -61,7 +61,7 @@ module ConvenientService
                 # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Exceptions::MethodHasNoOrganizer]
                 #
                 def organizer(raise_when_missing: true)
-                  raise Exceptions::MethodHasNoOrganizer.new(method: self) if @organizer.nil? && raise_when_missing
+                  ::ConvenientService.raise Exceptions::MethodHasNoOrganizer.new(method: self) if @organizer.nil? && raise_when_missing
 
                   @organizer
                 end

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/alias.rb

@@ -16,13 +16,13 @@ module ConvenientService
                   def validate_as_input_for_container!(container, method:)
                     return true if container.has_defined_method?(method)
 
-                    raise Exceptions::AliasInputMethodIsNotDefinedInContainer.new(method: method, container: container)
+                    ::ConvenientService.raise Exceptions::AliasInputMethodIsNotDefinedInContainer.new(method: method, container: container)
                   end
 
                   def validate_as_output_for_container!(container, method:)
                     return true unless container.has_defined_method?(method)
 
-                    raise Exceptions::AliasOutputMethodIsDefinedInContainer.new(method: method, container: container)
+                    ::ConvenientService.raise Exceptions::AliasOutputMethodIsDefinedInContainer.new(method: method, container: container)
                   end
 
                   def define_output_in_container!(container, index:, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/proc.rb

@@ -21,7 +21,7 @@ module ConvenientService
                     ##
                     # TODO: Better error message.
                     #
-                    raise Exceptions::OutputMethodProc.new(method: method, container: container)
+                    ::ConvenientService.raise Exceptions::OutputMethodProc.new(method: method, container: container)
                   end
 
                   def define_output_in_container!(container, index:, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/raw.rb

@@ -21,7 +21,7 @@ module ConvenientService
                     ##
                     # TODO: Better error message.
                     #
-                    raise Exceptions::OutputMethodRawValue.new(container: container, method: method)
+                    ::ConvenientService.raise Exceptions::OutputMethodRawValue.new(container: container, method: method)
                   end
 
                   def define_output_in_container!(container, index:, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/reassignment.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "reassignment/commands"
-
 module ConvenientService
   module Service
     module Plugins
@@ -22,11 +20,11 @@ module ConvenientService
                   # TODO: Separate `in` and `out` methods?
                   #
                   def calculate_value(method)
-                    raise Exceptions::CallerCanNotCalculateReassignment.new(method: method)
+                    ::ConvenientService.raise Exceptions::CallerCanNotCalculateReassignment.new(method: method)
                   end
 
                   def validate_as_input_for_container!(container, method:)
-                    raise Exceptions::InputMethodReassignment.new(method: method, container: container)
+                    ::ConvenientService.raise Exceptions::InputMethodReassignment.new(method: method, container: container)
                   end
 
                   def validate_as_output_for_container!(container, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/usual.rb

@@ -16,13 +16,13 @@ module ConvenientService
                   def validate_as_input_for_container!(container, method:)
                     return true if container.has_defined_method?(method)
 
-                    raise Exceptions::InputMethodIsNotDefinedInContainer.new(method: method, container: container)
+                    ::ConvenientService.raise Exceptions::InputMethodIsNotDefinedInContainer.new(method: method, container: container)
                   end
 
                   def validate_as_output_for_container!(container, method:)
                     return true unless container.has_defined_method?(method)
 
-                    raise Exceptions::OutputMethodIsDefinedInContainer.new(method: method, container: container)
+                    ::ConvenientService.raise Exceptions::OutputMethodIsDefinedInContainer.new(method: method, container: container)
                   end
 
                   def define_output_in_container!(container, index:, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/directions/input.rb

@@ -14,11 +14,11 @@ module ConvenientService
                   end
 
                   def validate_as_output_for_container!(container, method:)
-                    raise Exceptions::MethodIsNotOutputMethod.new(method: method, container: container)
+                    ::ConvenientService.raise Exceptions::MethodIsNotOutputMethod.new(method: method, container: container)
                   end
 
                   def define_output_in_container!(container, index:, method:)
-                    raise Exceptions::MethodIsNotOutputMethod.new(method: method, container: container)
+                    ::ConvenientService.raise Exceptions::MethodIsNotOutputMethod.new(method: method, container: container)
                   end
                 end
               end

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/directions/output.rb

@@ -10,7 +10,7 @@ module ConvenientService
               module Directions
                 class Output < Base
                   def validate_as_input_for_container!(container, method:)
-                    raise Exceptions::MethodIsNotInputMethod.new(method: method, container: container)
+                    ::ConvenientService.raise Exceptions::MethodIsNotInputMethod.new(method: method, container: container)
                   end
 
                   def validate_as_output_for_container!(container, method:)

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

@@ -15,14 +15,14 @@ module ConvenientService
                 # @internal
                 #   TODO: Introduce `Method#step` for more verbose message?
                 #
-                def initialize(method:)
+                def initialize_with_kwargs(method:)
                   message = <<~TEXT
                     Organizer for method `:#{method.name}` is NOT assigned yet.
 
                     Did you forget to set it?
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
@@ -32,14 +32,14 @@ module ConvenientService
                 # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
                 # @return [void]
                 #
-                def initialize(method:, container:)
+                def initialize_with_kwargs(method:, container:)
                   message = <<~TEXT
                     `in` method `#{method.name}` is NOT defined in `#{container.klass}`.
 
                     Did you forget to define it?
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
@@ -49,14 +49,14 @@ module ConvenientService
                 # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
                 # @return [void]
                 #
-                def initialize(method:, container:)
+                def initialize_with_kwargs(method:, container:)
                   message = <<~TEXT
                     `out` method `#{method.name}` is already defined in `#{container.klass}`.
 
                     Did you forget to remove it?
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
@@ -66,14 +66,14 @@ module ConvenientService
                 # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
                 # @return [void]
                 #
-                def initialize(method:, container:)
+                def initialize_with_kwargs(method:, container:)
                   message = <<~TEXT
                     Alias `in` method `#{method.name}` is NOT defined in `#{container.klass}`.
 
                     Did you forget to define it?
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
@@ -83,14 +83,14 @@ module ConvenientService
                 # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
                 # @return [void]
                 #
-                def initialize(method:, container:)
+                def initialize_with_kwargs(method:, container:)
                   message = <<~TEXT
                     Alias `out` method `#{method.name}` is already defined in `#{container.klass}`.
 
                     Did you forget to remove it?
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
@@ -100,12 +100,12 @@ module ConvenientService
                 # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
                 # @return [void]
                 #
-                def initialize(method:, container:)
+                def initialize_with_kwargs(method:, container:)
                   message = <<~TEXT
                     Procs are not allowed for `out` methods.
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
@@ -115,12 +115,12 @@ module ConvenientService
                 # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
                 # @return [void]
                 #
-                def initialize(method:, container:)
+                def initialize_with_kwargs(method:, container:)
                   message = <<~TEXT
                     Raw values are not allowed for `out` methods.
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
@@ -129,14 +129,14 @@ module ConvenientService
                 # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
                 # @return [void]
                 #
-                def initialize(method:)
+                def initialize_with_kwargs(method:)
                   message = <<~TEXT
                     Method caller failed to calculate reassignment for `#{method.name}`.
 
                     Method callers can calculate only `in` methods, while reassignments are always `out` methods.
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
@@ -146,12 +146,12 @@ module ConvenientService
                 # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
                 # @return [void]
                 #
-                def initialize(method:, container:)
+                def initialize_with_kwargs(method:, container:)
                   message = <<~TEXT
                     Reassignments are not allowed for `in` methods.
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
@@ -161,12 +161,12 @@ module ConvenientService
                 # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
                 # @return [void]
                 #
-                def initialize(method:, container:)
+                def initialize_with_kwargs(method:, container:)
                   message = <<~TEXT
                     Method `#{method.name}` is NOT an `in` method.
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
@@ -176,48 +176,28 @@ module ConvenientService
                 # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
                 # @return [void]
                 #
-                def initialize(method:, container:)
+                def initialize_with_kwargs(method:, container:)
                   message = <<~TEXT
                     Method `#{method.name}` is NOT an `out` method.
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
 
-              class NotCompletedStep < ::ConvenientService::Exception
+              class OutMethodStepIsNotCompleted < ::ConvenientService::Exception
                 ##
                 # @param method_name [Symbol]
-                # @param step [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
                 # @return [void]
                 #
-                def initialize(method_name:, step:)
+                def initialize_with_kwargs(method_name:)
                   message = <<~TEXT
-                    `out` method `#{method_name}` is called before its corresponding step `#{step.printable_service}` is completed.
+                    `out` method `#{method_name}` is called before its corresponding step is completed.
 
-                    Maybe it makes sense to change the steps order?
+                    Maybe it makes sense to change steps order?
                   TEXT
 
-                  super(message)
-                end
-              end
-
-              class NotExistingStepResultDataAttribute < ::ConvenientService::Exception
-                ##
-                # @param key [Symbol]
-                # @param step [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
-                # @return [void]
-                #
-                def initialize(key:, step:)
-                  message = <<~TEXT
-                    Step `#{step.printable_service}` result does NOT return `#{key}` data attribute.
-
-                    Maybe there is a typo in `out` definition?
-
-                    Or `success` of `#{step.printable_service}` accepts a wrong key?
-                  TEXT
-
-                  super(message)
+                  initialize(message)
                 end
               end
             end