convenient_service 0.17.0 → 0.18.0

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveConnectedSteps
+        module Entities
+          module Expressions
+            class Or < Entities::Expressions::Base
+              ##
+              # @!attribute [r] left_expression
+              #   @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+              #
+              attr_reader :left_expression
+
+              ##
+              # @!attribute [r] right_expression
+              #   @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+              #
+              attr_reader :right_expression
+
+              ##
+              # @param left_expression [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+              # @param right_expression [[ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+              # @return [void]
+              #
+              def initialize(left_expression, right_expression)
+                @left_expression = left_expression
+                @right_expression = right_expression
+              end
+
+              ##
+              # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+              #
+              def result
+                left_expression.success? ? left_expression.result : right_expression.result
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              # @internal
+              #   NOTE: `error` is like an exception, so it always stops the flow.
+              #
+              def success?
+                return true if left_expression.success?
+                return false if left_expression.error?
+
+                right_expression.success?
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              # @internal
+              #   NOTE: `error` is like an exception, so it always stops the flow.
+              #
+              def failure?
+                return false if left_expression.success?
+                return false if left_expression.error?
+
+                right_expression.failure?
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              def error?
+                left_expression.error? || right_expression.error?
+              end
+
+              ##
+              # @param block [Proc]
+              # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+              #
+              def each_step(&block)
+                left_expression.each_step(&block)
+                right_expression.each_step(&block)
+
+                self
+              end
+
+              ##
+              # @param block [Proc]
+              # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+              #
+              def each_evaluated_step(&block)
+                left_expression.each_evaluated_step(&block)
+
+                return self if left_expression.success?
+                return self if left_expression.error?
+
+                right_expression.each_evaluated_step(&block)
+
+                self
+              end
+
+              ##
+              # @param organizer [ConvenientService::Service]
+              # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Not]
+              #
+              def with_organizer(organizer)
+                copy(overrides: {args: {0 => left_expression.with_organizer(organizer), 1 => right_expression.with_organizer(organizer)}})
+              end
+
+              ##
+              # @return [String]
+              #
+              def inspect
+                "#{left_expression.inspect} || #{right_expression.inspect}"
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              def or?
+                true
+              end
+
+              ##
+              # @param other [Object] Can be any type.
+              # @return [Boolean]
+              #
+              def ==(other)
+                return unless other.instance_of?(self.class)
+
+                return false if left_expression != other.left_expression
+                return false if right_expression != other.right_expression
+
+                true
+              end
+
+              ##
+              # @return [ConvenientService::Support::Arguments]
+              #
+              def to_arguments
+                Support::Arguments.new(left_expression, right_expression)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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,217 @@
+# 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 [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"