convenient_service 0.17.0 → 0.18.0

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSequentialSteps
+        module Concern
+          include Support::Concern
+
+          class_methods do
+            ##
+            # @api public
+            #
+            # Registers a step (step definition).
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+            #
+            def step(*args, **kwargs)
+              steps.create(*args, **kwargs)
+            end
+
+            ##
+            # @api private
+            #
+            # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::StepCollection]
+            #
+            def steps
+              internals_class.cache.fetch(:steps) { Entities::StepCollection.new(container: self) }
+            end
+          end
+
+          instance_methods do
+            ##
+            # @api public
+            #
+            # @note May be useful for debugging purposes.
+            # @see https://userdocs.convenientservice.org/guides/how_to_debug_services_via_callbacks
+            #
+            # @note `steps` are frozen.
+            # @see https://userdocs.convenientservice.org/faq#is-it-possible-to-modify-the-step-collection-from-a-callback
+            #
+            # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::StepСollection]
+            #
+            def steps
+              internals.cache.fetch(:steps) do
+                self.class
+                  .steps
+                  .tap(&:commit!)
+                  .with_organizer(self)
+                  .tap(&:commit!)
+              end
+            end
+
+            ##
+            # @api private
+            #
+            # 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::CanHaveSequentialSteps::Middleware#next
+            #
+            def step(index)
+              steps[index]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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,60 +7,10 @@ module ConvenientService
         module Concern
           include Support::Concern
 
-          instance_methods do
-            ##
-            # @api public
-            #
-            # @note May be useful for debugging purposes.
-            # @see https://userdocs.convenientservice.org/guides/how_to_debug_services_via_callbacks
-            #
-            # @note `steps` are frozen.
-            # @see https://userdocs.convenientservice.org/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://userdocs.convenientservice.org/basics/step_to_result_translation_table
             #
@@ -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}
-
-                      ::ConvenientService.raise #{not_completed_step_error}.new(step: step, method_name: method_name) unless step.completed?
-
-                      ::ConvenientService.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/entities/callers/reassignment.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "reassignment/commands"
-
 module ConvenientService
   module Service
     module Plugins

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

@@ -185,36 +185,16 @@ module ConvenientService
                 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_with_kwargs(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?
-                  TEXT
-
-                  initialize(message)
-                end
-              end
-
-              class NotExistingStepResultDataAttribute < ::ConvenientService::Exception
-                ##
-                # @param key [Symbol]
-                # @param step [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
-                # @return [void]
-                #
-                def initialize_with_kwargs(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?
+                    Maybe it makes sense to change steps order?
                   TEXT
 
                   initialize(message)