convenient_service 0.6.0 → 0.7.0

data/lib/convenient_service/rspec/matchers/custom/results/base.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "base/commands"
+require_relative "base/errors"
+
 module ConvenientService
   module RSpec
     module Matchers
@@ -24,7 +27,8 @@ module ConvenientService
 
               rules << ->(result) { result.class.include?(Service::Plugins::HasResult::Entities::Result::Concern) }
               rules << ->(result) { result.status.in?(statuses) }
-              rules << ->(result) { result.service.instance_of?(service_class) } if used_of?
+              rules << ->(result) { result.service.instance_of?(service_class) } if used_of_service?
+              rules << ->(result) { Commands::MatchResultStep.call(result: result, step: step) } if used_of_step?
               rules << ->(result) { result.unsafe_data == data } if used_data?
               rules << ->(result) { result.unsafe_message == message } if used_message?
               rules << ->(result) { result.unsafe_code == code } if used_code?
@@ -38,14 +42,14 @@ module ConvenientService
             # @return [String]
             #
             def description
-              default_text
+              expected_parts
             end
 
             ##
             # @return [String]
             #
             def failure_message
-              "expected that `#{result}` would #{default_text}"
+              "expected that `#{result.service.class}` result would #{default_text}"
             end
 
             ##
@@ -55,7 +59,7 @@ module ConvenientService
             #   https://relishapp.com/rspec/rspec-expectations/v/3-11/docs/custom-matchers/define-a-custom-matcher#overriding-the-failure-message-when-negated
             #
             def failure_message_when_negated
-              "expected that #{result} would NOT #{default_text}"
+              "expected that `#{result.service.class}` result would NOT #{default_text}"
             end
 
             ##
@@ -131,12 +135,31 @@ module ConvenientService
             # @param service_class [Class]
             # @return [ConvenientService::RSpec::Matchers::Custom::Results::Base]
             #
-            def of(service_class)
+            def of_service(service_class)
               chain[:service_class] = service_class
 
               self
             end
 
+            ##
+            # @param step [Class, Symbol]
+            # @return [ConvenientService::RSpec::Matchers::Custom::Results::Base]
+            #
+            def of_step(step)
+              chain[:step] = step
+
+              self
+            end
+
+            ##
+            # @return [ConvenientService::RSpec::Matchers::Custom::Results::Base]
+            #
+            def without_step
+              chain[:step] = nil
+
+              self
+            end
+
             private
 
             ##
@@ -149,21 +172,45 @@ module ConvenientService
             # @return [String]
             #
             def default_text
+              expected_parts << "\n\n" << got_parts
+            end
+
+            ##
+            # @return [String]
+            #
+            # @internal
+            #   TODO: Align for easier visual comparison.
+            #   TODO: New line for each attribute.
+            #
+            def expected_parts
               parts = []
 
               parts << "be #{printable_statuses}"
-              parts << "of `#{service_class}`" if used_of?
+              parts << "of service `#{service_class}`" if used_of_service?
+              parts << Commands::GenerateExpectedStepPart.call(step: step) if used_of_step?
               parts << "with data `#{data}`" if used_data?
               parts << "with message `#{message}`" if used_message?
               parts << "with code `#{code}`" if used_code?
 
-              parts << "\n\n"
+              parts.join(" ")
+            end
+
+            ##
+            # @return [String]
+            #
+            # @internal
+            #   TODO: Align for easier visual comparison.
+            #   TODO: New line for each attribute.
+            #
+            def got_parts
+              parts = []
 
               parts << "got `#{result.status}`"
-              parts << "of `#{result.service.class}`" if used_of?
-              parts << "with data `#{result.data}`" if used_data?
-              parts << "with message `#{result.message}`" if used_message?
-              parts << "with code `#{result.code}`" if used_code?
+              parts << "of service `#{result.service.class}`" if used_of_service?
+              parts << Commands::GenerateGotStepPart.call(result: result) if used_of_step?
+              parts << "with data `#{result.unsafe_data}`" if used_data?
+              parts << "with message `#{result.unsafe_message}`" if used_message?
+              parts << "with code `#{result.unsafe_code}`" if used_code?
 
               parts.join(" ")
             end
@@ -192,10 +239,17 @@ module ConvenientService
             ##
             # @return [Boolean]
             #
-            def used_of?
+            def used_of_service?
               chain.key?(:service_class)
             end
 
+            ##
+            # @return [Boolean]
+            #
+            def used_of_step?
+              chain.key?(:step)
+            end
+
             ##
             # @return [Hash]
             #
@@ -224,6 +278,13 @@ module ConvenientService
               Utils::Object.instance_variable_fetch(self, :@service_class) { chain[:service_class] }
             end
 
+            ##
+            # @return [Class]
+            #
+            def step
+              Utils::Object.instance_variable_fetch(self, :@step) { chain[:step] }
+            end
+
             ##
             # @return [Hash]
             #

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/can_have_parent_result/concern.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module CanHaveParentResult
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result, nil]
+                    #
+                    def parent
+                      @parent ||= internals.cache[:parent]
+                    end
+
+                    ##
+                    # @param include_self [Boolean]
+                    # @return [Array<ConvenientService::Service::Plugins::HasResult::Entities::Result>]
+                    #
+                    # @internal
+                    #   Without enumerator `parents` method is roughly equivalent to the following code:
+                    #
+                    #   def parents(include_self: false)
+                    #     parents = []
+                    #
+                    #     parents << self if include_self
+                    #
+                    #     ##
+                    #     # NOTE: Empty parentheses are used to force a method call
+                    #     # https://docs.ruby-lang.org/en/2.7.0/syntax/assignment_rdoc.html#label-Local+Variables+and+Methods
+                    #     #
+                    #     parent = parent()
+                    #
+                    #     while parent
+                    #       parents << parent
+                    #
+                    #       parent = parent.parent
+                    #     end
+                    #
+                    #     parents
+                    #   end
+                    #
+                    def parents(include_self: false)
+                      parents_enum(include_self: include_self).to_a
+                    end
+
+                    ##
+                    # @param include_self [Boolean]
+                    # @return [Enumerator<ConvenientService::Service::Plugins::HasResult::Entities::Result>]
+                    #
+                    # @see https://ruby-doc.org/core-2.7.0/Enumerator.html
+                    #
+                    def parents_enum(include_self: false)
+                      ::Enumerator.new do |yielder|
+                        yielder.yield(self) if include_self
+
+                        ##
+                        # NOTE: Empty parentheses are used to force a method call
+                        # https://docs.ruby-lang.org/en/2.7.0/syntax/assignment_rdoc.html#label-Local+Variables+and+Methods
+                        #
+                        parent = parent()
+
+                        while parent
+                          yielder.yield(parent)
+
+                          parent = parent.parent
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/can_have_parent_result/initialize/middleware.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module CanHaveParentResult
+                module Initialize
+                  class Middleware < Core::MethodChainMiddleware
+                    def next(*args, **kwargs, &block)
+                      entity.internals.cache[:parent] = kwargs[:parent]
+
+                      chain.next(*args, **kwargs, &block)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/can_have_parent_result/initialize.rb

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

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/can_have_parent_result/to_kwargs/middleware.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module CanHaveParentResult
+                module ToKwargs
+                  class Middleware < Core::MethodChainMiddleware
+                    def next(...)
+                      chain.next(...).merge(parent: entity.parent)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/can_have_parent_result/to_kwargs.rb

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

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/can_have_parent_result.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "can_have_parent_result/concern"
+require_relative "can_have_parent_result/initialize"
+require_relative "can_have_parent_result/to_kwargs"

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_jsend_status_and_attributes/concern/instance_methods.rb

@@ -113,7 +113,13 @@ module ConvenientService
                     # @return [Hash]
                     #
                     def to_kwargs
-                      {service: service, status: status, data: data, message: message, code: code}
+                      {
+                        service: service,
+                        status: status,
+                        data: unsafe_data,
+                        message: unsafe_message,
+                        code: unsafe_code
+                      }
                     end
                   end
                 end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_jsend_status_and_attributes/entities/data.rb

@@ -45,6 +45,10 @@ module ConvenientService
                     def to_h
                       @to_h ||= value.to_h
                     end
+
+                    def to_s
+                      @to_s ||= to_h.to_s
+                    end
                   end
                 end
               end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_step/concern.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasStep
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    def step
+                      @step ||= internals.cache[:step]
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_step/initialize/middleware.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasStep
+                module Initialize
+                  class Middleware < Core::MethodChainMiddleware
+                    def next(*args, **kwargs, &block)
+                      entity.internals.cache[:step] = kwargs[:step]
+
+                      chain.next(*args, **kwargs, &block)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_step/initialize.rb

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

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_step/to_kwargs/middleware.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasStep
+                module ToKwargs
+                  class Middleware < Core::MethodChainMiddleware
+                    def next(...)
+                      chain.next(...).merge(step: entity.step)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_step/to_kwargs.rb

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

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_step.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "has_step/concern"
+require_relative "has_step/initialize"
+require_relative "has_step/to_kwargs"

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins.rb

@@ -3,6 +3,8 @@
 require_relative "plugins/can_recalculate_result"
 require_relative "plugins/has_jsend_status_and_attributes"
 require_relative "plugins/has_inspect"
+require_relative "plugins/has_step"
+require_relative "plugins/can_have_parent_result"
 require_relative "plugins/has_result_short_syntax"
 require_relative "plugins/marks_result_status_as_checked"
 require_relative "plugins/raises_on_not_checked_result_status"

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

@@ -1,5 +1,3 @@
 # frozen_string_literal: true
 
-require_relative "has_result_method_steps/errors"
 require_relative "has_result_method_steps/middleware"
-require_relative "has_result_method_steps/services"

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

@@ -9,7 +9,7 @@ module ConvenientService
 
           instance_methods do
             ##
-            # @return [Array]
+            # @return [Array<ConvenientService::Service::Plugins::HasResultSteps::Entities::Step>]
             #
             def steps
               internals.cache.fetch(:steps) do
@@ -21,18 +21,26 @@ module ConvenientService
             end
 
             ##
-            # TODO: Create for callbacks.
+            # Returns step by index.
+            # Returns `nil` when index is out of range.
             #
-            #   def step(step_result)
-            #     step_result
-            #   end
+            # @param index [Integer]
+            # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
+            #
+            # @note This method was initially designed as a hook (callback trigger).
+            # @see ConvenientService::Service::Plugins::HasResultSteps::Middleware#next
             #
+            def step(index)
+              steps[index]
+            end
           end
 
           class_methods do
             ##
-            # @params args [Array]
-            # @params kwargs [Hash]
+            # Registers a step (step definition).
+            #
+            # @param args [Array]
+            # @param kwargs [Hash]
             # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
             #
             def step(*args, **kwargs)
@@ -41,6 +49,9 @@ module ConvenientService
             end
 
             ##
+            # @param value [Object] Can be any type.
+            # @return [ConvenientService::Support::RawValue]
+            #
             # 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
             #

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

@@ -30,9 +30,9 @@ module ConvenientService
 
                       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.data.has_attribute?(key)
+                      raise #{not_existing_step_result_data_attribute_error}.new(step: step, key: key) unless step.result.unsafe_data.has_attribute?(key)
 
-                      step.result.data[key]
+                      step.result.unsafe_data[key]
                     end
                   RUBY
 

data/lib/convenient_service/service/plugins/has_result_steps/entities/method/entities/callers/reassignment/commands/define_method_in_container.rb

@@ -46,7 +46,7 @@ module ConvenientService
 
                             key = step.reassignment(__method__).key.to_sym
 
-                            step.result.data[key]
+                            step.result.unsafe_data[key]
                           end
                         RUBY
 

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

@@ -18,6 +18,12 @@ module ConvenientService
                   :not_success?,
                   :not_failure?,
                   :not_error?,
+                  :data,
+                  :message,
+                  :code,
+                  :unsafe_data,
+                  :unsafe_message,
+                  :unsafe_code,
                   to: :result
 
                 delegate \
@@ -74,6 +80,10 @@ module ConvenientService
                   @input_values ||= calculate_input_values
                 end
 
+                def original_result
+                  @original_result ||= calculate_original_result
+                end
+
                 def result
                   @result ||= calculate_result
                 end
@@ -88,6 +98,13 @@ module ConvenientService
                   service.klass.to_s
                 end
 
+                ##
+                # @return [Class]
+                #
+                def service_class
+                  service.klass
+                end
+
                 def validate!
                   inputs.each { |input| input.validate_as_input_for_container!(container) }
 
@@ -114,6 +131,10 @@ module ConvenientService
 
                 attr_reader :args, :kwargs
 
+                ##
+                # @internal
+                #   TODO: Commands instead of private methods.
+                #
                 def calculate_input_values
                   assert_has_organizer!
 
@@ -124,7 +145,7 @@ module ConvenientService
                 # @internal
                 #   IMPORTANT: `service.result(**input_values)` is the reason, why services should have only kwargs as arguments.
                 #
-                def calculate_result
+                def calculate_original_result
                   assert_has_organizer!
 
                   result = service.result(**input_values)
@@ -134,6 +155,10 @@ module ConvenientService
                   result
                 end
 
+                def calculate_result
+                  original_result.copy(overrides: {kwargs: {step: self, service: organizer}})
+                end
+
                 def resolve_params
                   original_params = Commands::ExtractParams.call(args: args, kwargs: kwargs)
 

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResultSteps
+        module Entities
+          class Step
+            module Plugins
+              module CanHaveParentResult
+                class Middleware < Core::MethodChainMiddleware
+                  def next(...)
+                    chain.next(...).copy(overrides: {kwargs: {parent: entity.original_result}})
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
+require_relative "plugins/can_have_parent_result"
 require_relative "plugins/has_inspect"

data/lib/convenient_service/service/plugins/has_result_steps/entities/step_collection.rb

@@ -36,6 +36,19 @@ module ConvenientService
               steps.each(&block)
             end
 
+            ##
+            # Returns step by index.
+            #
+            # @param index [Integer]
+            # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
+            #
+            # @note Works in a similar way as `Array#[]`.
+            # @see https://ruby-doc.org/core-2.7.0/Array.html#method-i-5B-5D
+            #
+            def [](index)
+              steps[index]
+            end
+
             def <<(step)
               steps << step.copy(overrides: {kwargs: {index: next_available_index}})
             end