convenient_service 0.17.0 → 0.19.0

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

@@ -0,0 +1,503 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveConnectedSteps
+        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::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            #
+            def step(*args, **kwargs)
+              previous_expression = steps.expression
+
+              new_step = steps.create(*args, **kwargs)
+
+              steps.expression =
+                if previous_expression.empty?
+                  Entities::Expressions::Scalar.new(new_step)
+                else
+                  Entities::Expressions::And.new(
+                    previous_expression,
+                    Entities::Expressions::Scalar.new(new_step)
+                  )
+                end
+            end
+
+            ##
+            # @api public
+            #
+            # Registers a negated step (step definition).
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `not` from `not_step` has a similar precedence as Ruby's `!`.
+            # @note `not_step` is a rought equivalent of `!step`.
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            def not_step(*args, **kwargs)
+              previous_expression = steps.expression
+
+              new_step = steps.create(*args, **kwargs)
+
+              steps.expression =
+                if previous_expression.empty?
+                  Entities::Expressions::Not.new(
+                    Entities::Expressions::Scalar.new(new_step)
+                  )
+                else
+                  Entities::Expressions::And.new(
+                    previous_expression,
+                    Entities::Expressions::Not.new(
+                      Entities::Expressions::Scalar.new(new_step)
+                    )
+                  )
+                end
+            end
+
+            ##
+            # @api public
+            #
+            # Registers a step (step definition).
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `and` from `and_step` has a similar precedence as Ruby's `&&`.
+            # @note `and_step` is a rought equivalent of `&& step`.
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            def and_step(*args, **kwargs)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+
+              new_step = steps.create(*args, **kwargs)
+
+              steps.expression =
+                Entities::Expressions::And.new(
+                  previous_expression,
+                  Entities::Expressions::Scalar.new(new_step)
+                )
+            end
+
+            ##
+            # @api public
+            #
+            # Registers a negated step (step definition).
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `and` from `and_step` has a similar precedence as Ruby's `&&`.
+            # @note `not` from `and_not_step` has a similar precedence as Ruby's `!`.
+            # @note `and_not_step` is a rought equivalent of `&& !step`.
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            def and_not_step(*args, **kwargs)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+
+              new_step = steps.create(*args, **kwargs)
+
+              steps.expression =
+                Entities::Expressions::And.new(
+                  previous_expression,
+                  Entities::Expressions::Not.new(
+                    Entities::Expressions::Scalar.new(new_step)
+                  )
+                )
+            end
+
+            ##
+            # @api public
+            #
+            # Registers an alternative step (step definition).
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `or` from `or_step` has a similar precedence as Ruby's `||`.
+            # @note `or_step` is a rought equivalent of `|| step`.
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            # @internal
+            #   NOTE: Decomposing of the `and` expression is needed to make its priority higher.
+            #
+            def or_step(*args, **kwargs)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+
+              new_step = steps.create(*args, **kwargs)
+
+              steps.expression =
+                if previous_expression.and?
+                  Entities::Expressions::And.new(
+                    previous_expression.left_expression,
+                    Entities::Expressions::Or.new(
+                      previous_expression.right_expression,
+                      Entities::Expressions::Scalar.new(new_step)
+                    )
+                  )
+                else
+                  Entities::Expressions::Or.new(
+                    previous_expression,
+                    Entities::Expressions::Scalar.new(new_step)
+                  )
+                end
+            end
+
+            ##
+            # @api public
+            #
+            # Registers a negated alternative step (step definition).
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `or` from `or_not_step` has a similar precedence as Ruby's `||`.
+            # @note `not` from `or_not_step` has a similar precedence as Ruby's `!`.
+            # @note `or_not_step` is a rought equivalent of `|| !step`.
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            # @internal
+            #   NOTE: Decomposing of the `and` expression is needed to make its priority higher.
+            #
+            def or_not_step(*args, **kwargs)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+
+              new_step = steps.create(*args, **kwargs)
+
+              steps.expression =
+                if previous_expression.and?
+                  Entities::Expressions::And.new(
+                    previous_expression.left_expression,
+                    Entities::Expressions::Or.new(
+                      previous_expression.right_expression,
+                      Entities::Expressions::Not.new(
+                        Entities::Expressions::Scalar.new(new_step)
+                      )
+                    )
+                  )
+                else
+                  Entities::Expressions::Or.new(
+                    previous_expression,
+                    Entities::Expressions::Not.new(
+                      Entities::Expressions::Scalar.new(new_step)
+                    )
+                  )
+                end
+            end
+
+            ##
+            # @api public
+            #
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `group` has a similar precedence as Ruby's `()`.
+            # @note `group` is a rought equivalent of `()`.
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            def group(&block)
+              previous_expression = steps.expression
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                if previous_expression.empty?
+                  Entities::Expressions::Group.new(current_expression)
+                else
+                  Entities::Expressions::And.new(
+                    previous_expression,
+                    Entities::Expressions::Group.new(current_expression)
+                  )
+                end
+            end
+
+            ##
+            # @api public
+            #
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `not` from `not_group` has a similar precedence as Ruby's `!`.
+            # @note `group` from `not_group` has a similar precedence as Ruby's `()`.
+            # @note `not_group` is a rought equivalent of `!()`.
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            def not_group(&block)
+              previous_expression = steps.expression
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                if previous_expression.empty?
+                  Entities::Expressions::Not.new(
+                    Entities::Expressions::Group.new(current_expression)
+                  )
+                else
+                  Entities::Expressions::And.new(
+                    previous_expression,
+                    Entities::Expressions::Not.new(
+                      Entities::Expressions::Group.new(current_expression)
+                    )
+                  )
+                end
+            end
+
+            ##
+            # @api public
+            #
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `and` from `and_group` has a similar precedence as Ruby's `&&`.
+            # @note `group` from `and_group` has a similar precedence as Ruby's `()`.
+            # @note `not_group` is a rought equivalent of `&& ()`.
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            def and_group(&block)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                Entities::Expressions::And.new(
+                  previous_expression,
+                  Entities::Expressions::Group.new(current_expression)
+                )
+            end
+
+            ##
+            # @api public
+            #
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `and` from `and_not_group` has a similar precedence as Ruby's `&&`.
+            # @note `not` from `and_not_group` has a similar precedence as Ruby's `!`.
+            # @note `group` from `and_not_group` has a similar precedence as Ruby's `()`.
+            # @note `and_not_group` is a rought equivalent of `&& !()`.
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            def and_not_group(&block)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                Entities::Expressions::And.new(
+                  previous_expression,
+                  Entities::Expressions::Not.new(
+                    Entities::Expressions::Group.new(current_expression)
+                  )
+                )
+            end
+
+            ##
+            # @api public
+            #
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `or` from `or_group` has a similar precedence as Ruby's `||`.
+            # @note `group` from `or_group` has a similar precedence as Ruby's `()`.
+            # @note `or_group` is a rought equivalent of `|| ()`
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            # @internal
+            #   NOTE: Decomposing of the `and` expression is needed to make its priority higher.
+            #
+            def or_group(&block)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                if previous_expression.and?
+                  Entities::Expressions::And.new(
+                    previous_expression.left_expression,
+                    Entities::Expressions::Or.new(
+                      previous_expression.right_expression,
+                      Entities::Expressions::Group.new(current_expression)
+                    )
+                  )
+                else
+                  Entities::Expressions::Or.new(
+                    previous_expression,
+                    Entities::Expressions::Group.new(current_expression)
+                  )
+                end
+            end
+
+            ##
+            # @api public
+            #
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @note `or` from `or_not_group` has a similar precedence as Ruby's `||`.
+            # @note `not` from `or_not_group` has a similar precedence as Ruby's `!`.
+            # @note `group` from `or_not_group` has a similar precedence as Ruby's `()`.
+            # @note `or_not_group` is a rought equivalent of `|| !()`
+            # @note It is NOT recommended to rely on the return value of this method, since it may differ across different `step` related plugins.
+            # @see https://ruby-doc.org/core-2.7.1/doc/syntax/precedence_rdoc.html
+            #
+            # @internal
+            #   NOTE: Decomposing of the `and` expression is needed to make its priority higher.
+            #
+            def or_not_group(&block)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                if previous_expression.and?
+                  Entities::Expressions::And.new(
+                    previous_expression.left_expression,
+                    Entities::Expressions::Or.new(
+                      previous_expression.right_expression,
+                      Entities::Expressions::Not.new(
+                        Entities::Expressions::Group.new(current_expression)
+                      )
+                    )
+                  )
+                else
+                  Entities::Expressions::Or.new(
+                    previous_expression,
+                    Entities::Expressions::Not.new(
+                      Entities::Expressions::Group.new(current_expression)
+                    )
+                  )
+                end
+            end
+
+            ##
+            # @api private
+            #
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::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::CanHaveConnectedSteps::Entities::StepCollection]
+            #
+            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::CanHaveConnectedSteps::Middleware#next
+            #
+            def step(index)
+              steps[index]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveConnectedSteps
+        module Entities
+          module Expressions
+            class And < 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? ? right_expression.result : left_expression.result
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              def success?
+                left_expression.success? && right_expression.success?
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              def failure?
+                return true if left_expression.failure?
+                return false if left_expression.error?
+
+                right_expression.failure?
+              end
+
+              ##
+              # @return [Boolean]
+              #
+              def error?
+                return false if left_expression.failure?
+                return true if 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)
+
+                right_expression.each_evaluated_step(&block) if left_expression.success?
+
+                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 and?
+                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