convenient_service 0.6.0 → 0.8.0

data/lib/convenient_service/service/plugins/has_result/concern/class_methods.rb

@@ -22,7 +22,7 @@ module ConvenientService
             #   NOTE: This method is internally used by custom RSpec helper `stub_service`. It should NOT be used in the client code.
             #
             def success(
-              service: Constants::DEFAULT_SERVICE_INSTANCE,
+              service: create_without_initialize,
               data: Constants::DEFAULT_SUCCESS_DATA
             )
               result_class.create(
@@ -42,7 +42,7 @@ module ConvenientService
             #   NOTE: This method is internally used by custom RSpec helper `stub_service`. It should NOT be used in the client code.
             #
             def failure(
-              service: Constants::DEFAULT_SERVICE_INSTANCE,
+              service: create_without_initialize,
               data: Constants::DEFAULT_FAILURE_DATA,
               message: data.any? ? data.first.join(" ") : Constants::DEFAULT_FAILURE_MESSAGE
             )
@@ -63,7 +63,7 @@ module ConvenientService
             #   NOTE: This method is internally used by custom RSpec helper `stub_service`. It should NOT be used in the client code.
             #
             def error(
-              service: Constants::DEFAULT_SERVICE_INSTANCE,
+              service: create_without_initialize,
               message: Constants::DEFAULT_ERROR_MESSAGE,
               code: Constants::DEFAULT_ERROR_CODE
             )

data/lib/convenient_service/service/plugins/has_result/constants.rb

@@ -5,9 +5,6 @@ module ConvenientService
     module Plugins
       module HasResult
         module Constants
-          DEFAULT_SERVICE_CLASS = ::Class.new { include ::ConvenientService::Service::Plugins::HasResult::Concern }
-          DEFAULT_SERVICE_INSTANCE = DEFAULT_SERVICE_CLASS.new
-
           SUCCESS_STATUS = :success
           FAILURE_STATUS = :failure
           ERROR_STATUS = :error

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

@@ -18,6 +18,19 @@ module ConvenientService
 
                     attr_reader :value
 
+                    ##
+                    # @internal
+                    #   NOTE: Ruby hashes enumerate their values in the order that the corresponding keys were inserted.
+                    #   That is why the end-user can be 100% sure that the failure message is always generated from the first key/value pair.
+                    #   - https://ruby-doc.org/core-2.7.0/Hash.html
+                    #
+                    #   TODO: A test that crashes when such behaviour is broken.
+                    #
+                    #   NOTE: As a result, there is NO need to use any custom `OrderedHash` implementations.
+                    #   - https://api.rubyonrails.org/v5.1/classes/ActiveSupport/OrderedHash.html
+                    #   - https://github.com/rails/rails/issues/22681
+                    #   - https://api.rubyonrails.org/classes/ActiveSupport/OrderedOptions.html
+                    #
                     def initialize(value:)
                       @value = value
                     end
@@ -45,6 +58,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

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

@@ -5,6 +5,9 @@ module ConvenientService
     module Plugins
       module HasResultSteps
         class Middleware < Core::MethodChainMiddleware
+          ##
+          # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
+          #
           def next(...)
             return chain.next(...) if entity.steps.none?
 
@@ -13,11 +16,22 @@ module ConvenientService
 
           private
 
+          ##
+          # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
+          #
           def last_step
-            ##
-            # TODO: Use `entity.steps.find { |step| step.result.tap { |result| entity.step(result) }.not_success? }` for callbacks.
-            #
-            @last_step ||= entity.steps.find(&:not_success?) || entity.steps.last
+            @last_step ||= entity.steps.find.with_index { |step, index| not_success?(step, index) } || entity.steps.last
+          end
+
+          ##
+          # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
+          #
+          # @internal
+          #   NOTE: `entity.step(index)` is used as a hook (callbacks trigger).
+          #   IMPORTANT: `step` status MUST be checked before triggering callbacks.
+          #
+          def not_success?(step, index)
+            step.not_success?.tap { entity.step(index) }
           end
         end
       end

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

@@ -5,6 +5,26 @@ module ConvenientService
     module Plugins
       module RaisesOnDoubleResult
         class Middleware < Core::MethodChainMiddleware
+          ##
+          # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+          #
+          # @internal
+          #   TODO: Rewrite `RaisesOnDoubleResult` to make it thread-safe.
+          #
+          #   NOTE: Minimal reproducible example.
+          #
+          #     class Service
+          #       include ConvenientService::Standard::Config
+          #
+          #       def result
+          #         success
+          #       end
+          #     end
+          #
+          #     service = Service.new
+          #
+          #     10.times.reduce([]) { |threads| threads << Thread.new { service.result } }.join
+          #
           def next(...)
             refute_has_result! || mark_as_has_result!
 
@@ -14,8 +34,14 @@ module ConvenientService
           private
 
           ##
-          # NOTE: `refute` is `!assert`.
-          # https://docs.seattlerb.org/minitest
+          # @return [Boolean]
+          # @raise [ConvenientService::Service::Plugins::RaisesOnDoubleResult::Errors::DoubleResult]
+          #
+          # @internal
+          #   NOTE: `refute` is `!assert`.
+          #   - https://docs.seattlerb.org/minitest
+          #
+          #   NOTE: This method contains a trailing exclamation mark in its name since it is mutable.
           #
           def refute_has_result!
             return unless entity.internals.cache.exist?(:has_result)
@@ -23,6 +49,15 @@ module ConvenientService
             raise Errors::DoubleResult.new(service: entity)
           end
 
+          ##
+          # @return [Boolean]
+          #
+          # @internal
+          #   NOTE: Name is inspired by `mark_as_read`.
+          #   - https://github.com/ledermann/unread
+          #
+          #   NOTE: This method contains a trailing exclamation mark in its name since it is mutable.
+          #
           def mark_as_has_result!
             entity.internals.cache.write(:has_result, true)
           end