convenient_service 0.17.0 → 0.19.0

data/lib/convenient_service/service/plugins/can_have_connected_steps/entities/expressions/scalar.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveConnectedSteps
+        module Entities
+          module Expressions
+            class Scalar < Entities::Expressions::Base
+              ##
+              # @!attribute [r] step
+              #   @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+              #
+              attr_reader :step
+
+              ##
+              # @param step [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+              # @return [void]
+              #
+              def initialize(step)
+                @step = step
+              end
+
+              ##
+              # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+              #
+              def result
+                step.result
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              # @internal
+              #   IMPORTANT: `success?` calls `result` to be able to use the same RSpec spy for both `success?` and `result?`.
+              #
+              def success?
+                result.status.unsafe_success?
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              # @internal
+              #   IMPORTANT: `failure?` calls `result` to be able to use the same RSpec spy for both `failure?` and `result?`.
+              #
+              def failure?
+                result.status.unsafe_failure?
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              # @internal
+              #   IMPORTANT: `error?` calls `result` to be able to use the same RSpec spy for both `error?` and `result?`.
+              #
+              def error?
+                result.status.unsafe_error?
+              end
+
+              ##
+              # @param block [Proc]
+              # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Scalar]
+              #
+              def each_step(&block)
+                yield(step)
+
+                self
+              end
+
+              ##
+              # @param block [Proc]
+              # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Scalar]
+              #
+              # @internal
+              #   NOTE: `result` is called to evaluate step.
+              #   IMPORTANT: `each_evaluated_step` calls `result` to be able to use the same RSpec spy for both `each_evaluated_step` and `result?`.
+              #
+              def each_evaluated_step(&block)
+                result
+
+                yield(step)
+
+                self
+              end
+
+              ##
+              # @param organizer [ConvenientService::Service]
+              # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Scalar]
+              #
+              def with_organizer(organizer)
+                copy(overrides: {args: {0 => step.with_organizer(organizer)}})
+              end
+
+              ##
+              # @return [String]
+              #
+              def inspect
+                "steps[#{step.index}]"
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              def scalar?
+                true
+              end
+
+              ##
+              # @param other [Object] Can be any type.
+              # @return [Boolean]
+              #
+              def ==(other)
+                return unless other.instance_of?(self.class)
+
+                return false if step != other.step
+
+                true
+              end
+
+              ##
+              # @return [ConvenientService::Support::Arguments]
+              #
+              def to_arguments
+                Support::Arguments.new(step)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_connected_steps/entities/expressions.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "expressions/base"
+
+require_relative "expressions/empty"
+require_relative "expressions/scalar"
+require_relative "expressions/not"
+require_relative "expressions/and"
+require_relative "expressions/or"
+require_relative "expressions/group"

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

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveConnectedSteps
+        module Entities
+          ##
+          # @internal
+          #   NOTE:
+          #     This class is a modernization of `StepCollection` from `HasSequentialSteps`.
+          #     Compared to the original implementation, this one is based on `expression` objects.
+          #     `steps` array is not mandatory since each `step` can be retrieved from `expression`, but it is left for better performance.
+          #     `expression` objects are trees. Search by index in the tree is O(n), while the same lookup in the array is O(1).
+          #
+          class StepCollection
+            include ::Enumerable
+
+            include Support::Copyable
+
+            ##
+            # @api private
+            #
+            # @!attribute [r] container
+            #   @return [Class<ConvenientService::Service>]
+            #
+            attr_reader :container
+
+            ##
+            # @api private
+            #
+            # @!attribute [r] expression
+            #   @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            attr_accessor :expression
+
+            ##
+            # @api private
+            #
+            # @!attribute [r] steps
+            #   @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
+            #
+            attr_reader :steps
+
+            ##
+            # @api private
+            #
+            # @param container [Class<ConvenientService::Service>]
+            # @param expression [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            # @param steps [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
+            # @return [void]
+            #
+            def initialize(container:, expression: Entities::Expressions::Empty.new, steps: [])
+              @container = container
+              @expression = expression
+              @steps = steps
+            end
+
+            ##
+            # @return [Integer]
+            #
+            def size
+              steps.size
+            end
+
+            ##
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            # @raise [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Exceptions::EmptyExpressionHasNoResult]
+            #
+            def result
+              expression.result
+            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)
+              expression_with_organizer = expression.with_organizer(organizer)
+
+              copy(overrides: {kwargs: {expression: expression_with_organizer, steps: expression_with_organizer.steps}})
+            end
+
+            ##
+            # @api public
+            #
+            # @return [Boolean] true if called for the first time, false otherwise (similarly as Kernel#require).
+            #
+            # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-require
+            #
+            # @internal
+            #   IMPORTANT: `step.validate!` is intentionally removed from `steps.each { |step| step.validate! && step.define! }.freeze` since it is NOT idempotent.
+            #
+            #   NOTE: `step.validate!` is still useful as a `doctor` command.
+            #
+            def commit!
+              return false if committed?
+
+              expression.each_step(&:define!).freeze
+
+              steps.freeze
+
+              freeze
+
+              true
+            end
+
+            ##
+            # @api public
+            #
+            # @return [Boolean]
+            #
+            def committed?
+              expression.frozen?
+            end
+
+            ##
+            # @api public
+            #
+            # @param block [Proc, nil]
+            # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>, Enumerator]
+            #
+            def each(&block)
+              expression.each_step(&block)
+            end
+
+            ##
+            # @api public
+            #
+            # @param block [Proc, nil]
+            # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>, Enumerator]
+            #
+            def each_step(&block)
+              expression.each_step(&block)
+            end
+
+            ##
+            # @api public
+            #
+            # @param block [Proc, nil]
+            # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>, Enumerator]
+            #
+            def each_evaluated_step(&block)
+              expression.each_evaluated_step(&block)
+            end
+
+            ##
+            # @api public
+            #
+            # Returns step by index.
+            #
+            # @param index [Integer]
+            # @return [ConvenientService::Service::Plugins::CanHaveSteps::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
+
+            ##
+            # @return [String]
+            #
+            def inspect
+              expression.inspect
+            end
+
+            ##
+            # @api public
+            #
+            # @param other [Object] Can be any type.
+            # @return [Boolean, nil]
+            #
+            def ==(other)
+              return unless other.instance_of?(self.class)
+
+              return false if container != other.container
+              return false if expression != other.expression
+              return false if steps != other.steps
+
+              true
+            end
+
+            ##
+            # @return [ConvenientService::Support::Arguments]
+            #
+            def to_arguments
+              Support::Arguments.new(container: container, expression: expression, steps: steps)
+            end
+
+            private
+
+            ##
+            # @return [Integer]
+            #
+            def next_available_index
+              steps.size
+            end
+
+            ##
+            # @return [Class<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
+            #
+            def step_class
+              container.step_class
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/convenient_service/service/plugins/can_have_connected_steps/exceptions.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveConnectedSteps
+        module Exceptions
+          class FirstStepIsNotSet < ::ConvenientService::Exception
+            ##
+            # @param container [Class<ConvenientService::Service>]
+            # @return [void]
+            #
+            # @internal
+            #   TODO: Use `display_name`.
+            #
+            def initialize_with_kwargs(container:)
+              message = <<~TEXT
+                First step of `#{container}` is NOT set.
+
+                Did you forget to use `step`? For example:
+
+                class #{container}
+                  # ...
+
+                  step SomeService
+
+                  # ...
+                end
+              TEXT
+
+              initialize(message)
+            end
+          end
+
+          class FirstGroupStepIsNotSet < ::ConvenientService::Exception
+            ##
+            # @param container [Class<ConvenientService::Service>]
+            # @return [void]
+            #
+            # @internal
+            #   TODO: Use `display_name`.
+            #
+            def initialize_with_kwargs(container:, method:)
+              message = <<~TEXT
+                First step of `#{method}` from `#{container}` is NOT set.
+
+                Did you forget to use `step`? For example:
+
+                class #{container}
+                  # ...
+
+                  #{method} do
+                    step SomeService
+
+                    # ...
+                  end
+
+                  # ...
+                end
+              TEXT
+
+              initialize(message)
+            end
+          end
+
+          class EmptyExpressionHasNoResult < ::ConvenientService::Exception
+            ##
+            # @return [void]
+            #
+            def initialize_without_arguments
+              message = <<~TEXT
+                Empty expression has NO result.
+              TEXT
+
+              initialize(message)
+            end
+          end
+
+          class EmptyExpressionHasNoStatus < ::ConvenientService::Exception
+            ##
+            # @return [void]
+            #
+            def initialize_without_arguments
+              message = <<~TEXT
+                Empty expression has NO status.
+              TEXT
+
+              initialize(message)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveConnectedSteps
+        class Middleware < MethodChainMiddleware
+          intended_for :result, entity: :service
+
+          ##
+          # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+          #
+          def next(...)
+            return chain.next(...) if entity.steps.none?
+
+            entity.steps.each_evaluated_step do |step|
+              step.save_outputs_in_organizer!
+
+              step.trigger_callback
+
+              step.mark_as_completed!
+            end
+
+            entity.steps.result
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "can_have_connected_steps/concern"
+require_relative "can_have_connected_steps/entities"
+require_relative "can_have_connected_steps/exceptions"
+require_relative "can_have_connected_steps/middleware"

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

@@ -25,6 +25,15 @@ module ConvenientService
             def fallback_error_result
               ::ConvenientService.raise Exceptions::FallbackResultIsNotOverridden.new(service: self, status: :error)
             end
+
+            ##
+            # Returns `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result` when overridden.
+            #
+            # @raise [ConvenientService::Service::Plugins::CanHaveFallbacks::Exceptions::FallbackResultIsNotOverridden]
+            #
+            def fallback_result
+              ::ConvenientService.raise Exceptions::FallbackResultIsNotOverridden.new(service: self, status: nil)
+            end
           end
 
           class_methods do
@@ -97,6 +106,15 @@ module ConvenientService
             def fallback_error_result(...)
               new(...).fallback_error_result
             end
+
+            ##
+            # Returns `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result` when `#fallback_result` is overridden.
+            #
+            # @raise [ConvenientService::Service::Plugins::CanHaveFallbacks::Exceptions::FallbackResultIsNotOverridden]
+            #
+            def fallback_result(...)
+              new(...).fallback_result
+            end
           end
         end
       end

data/lib/convenient_service/service/plugins/can_have_fallbacks/exceptions.rb

@@ -8,26 +8,44 @@ module ConvenientService
           class FallbackResultIsNotOverridden < ::ConvenientService::Exception
             def initialize_with_kwargs(service:, status:)
               message = <<~TEXT
-                Fallback #{status} result method (#fallback_#{status}_result) of `#{service.class}` is NOT overridden.
+                Fallback#{enclose(status, " ")}result method (#fallback#{enclose(status, "_")}result) of `#{service.class}` is NOT overridden.
 
-                NOTE: Make sure overridden `fallback_#{status}_result` returns `success` with reasonable "null" data.
+                NOTE: Make sure overridden `fallback#{enclose(status, "_")}result` returns `success` with reasonable "null" data.
               TEXT
 
               initialize(message)
             end
+
+            private
+
+            ##
+            # @return [String]
+            #
+            def enclose(...)
+              ConvenientService::Utils::String.enclose(...)
+            end
           end
 
           class ServiceFallbackReturnValueNotSuccess < ::ConvenientService::Exception
             def initialize_with_kwargs(service:, result:, status:)
               message = <<~TEXT
-                Return value of service `#{service.class}` `#{status}` fallback is NOT a `success`.
+                Return value of service `#{service.class}`#{enclose(status, " ")}fallback is NOT a `success`.
                 It is `#{result.status}`.
 
-                Did you accidentally call `failure` or `error` instead of `success` from the `fallback_#{status}_result` method?
+                Did you accidentally call `failure` or `error` instead of `success` from the `fallback#{enclose(status, "_")}result` method?
               TEXT
 
               initialize(message)
             end
+
+            private
+
+            ##
+            # @return [String]
+            #
+            def enclose(...)
+              ConvenientService::Utils::String.enclose(...)
+            end
           end
         end
       end

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

@@ -5,12 +5,12 @@ module ConvenientService
     module Plugins
       module CanHaveFallbacks
         class Middleware < MethodChainMiddleware
-          intended_for [:fallback_failure_result, :fallback_error_result], entity: :service
+          intended_for [:fallback_failure_result, :fallback_error_result, :fallback_result], entity: :service
 
           ##
           # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
           #
-          # @note Both `fallback_failure_result` and `fallback_error_result` are always successful, that is why their statuses are pre-checked.
+          # @note Both `fallback_failure_result`, `fallback_error_result` and `fallback_result` are always successful, that is why their statuses are pre-checked.
           #
           def next(...)
             fallback_result = chain.next(...)
@@ -24,7 +24,7 @@ module ConvenientService
           private
 
           ##
-          # @return [Symbol]
+          # @return [Symbol, nil]
           #
           def status
             middleware_arguments.kwargs.fetch(:status)

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveRollbacks
+        class Middleware < MethodChainMiddleware
+          intended_for :result, entity: :service
+
+          ##
+          # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+          #
+          def next(...)
+            result = chain.next(...)
+
+            rollback_result(result) if result.status.unsafe_not_success?
+
+            result
+          end
+
+          private
+
+          ##
+          # @param result [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+          # @return [void]
+          #
+          # @internal
+          #   IMPORTANT: Uses recursion inside `rollback_organizer`. Recursion has two exit conditions. When service has no steps. When service has only method steps.
+          #
+          def rollback_result(result)
+            result.from_step? ? rollback_organizer(result.service) : rollback_service(result.service)
+          end
+
+          ##
+          # Calls service own rollback.
+          #
+          # @param service [ConvenientService::Service]
+          # @return [void]
+          #
+          # @internal
+          #   TODO: Compare what is faster `respond_to?` or `own_method`.
+          #
+          def rollback_service(service)
+            Utils::Object.safe_send(service, :rollback_result)
+          end
+
+          ##
+          # Calls organizer own rollback.
+          # Then calls organizer steps rollbacks with nestings in the reverse order.
+          #
+          # @param organizer [ConvenientService::Service]
+          # @return [void]
+          #
+          def rollback_organizer(organizer)
+            rollback_service(organizer)
+
+            organizer.steps
+              .select(&:completed?)
+              .reject(&:method_step?)
+              .reverse_each { |step| rollback_result(step.service_result) }
+          end
+        end
+      end
+    end
+  end
+end

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

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