convenient_service 0.17.0 → 0.18.0

data/lib/convenient_service/service/configs/standard.rb

@@ -34,7 +34,6 @@ module ConvenientService
             use ConvenientService::Plugins::Common::HasCallbacks::Concern
             use ConvenientService::Plugins::Common::HasAroundCallbacks::Concern
 
-            use ConvenientService::Plugins::Service::CanHaveFallbacks::Concern
             use ConvenientService::Plugins::Service::HasMermaidFlowchart::Concern
           end
 
@@ -92,6 +91,28 @@ module ConvenientService
             use ConvenientService::Plugins::Service::CanHaveFallbacks::Middleware.with(status: :error)
           end
 
+          ##
+          # @internal
+          #   NOTE: Check `Minimal` docs to understand why `use ConvenientService::Plugins::Common::NormalizesEnv::Middleware` for `:negated_result` is used in `Standard`, not in `Minimal` config.
+          #
+          middlewares :negated_result do
+            use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
+            use ConvenientService::Plugins::Service::CollectsServicesInException::Middleware
+            use ConvenientService::Plugins::Common::CachesReturnValue::Middleware
+
+            use ConvenientService::Plugins::Common::EnsuresNegatedJSendResult::Middleware
+          end
+
+          ##
+          # TODO:
+          #   `after :step do |step|` is executed after step result is calculated.
+          #    This completely makes sence and is useful for debugging for example.
+          #
+          #   But `before :step do` is alos executed after step result is calculated.
+          #   That confuses the end-users a lot.
+          #   Probably a dedicated plugin is needed?
+          #   Or to forbid `before :step do`?
+          #
           middlewares :step do
             use ConvenientService::Plugins::Common::HasCallbacks::Middleware
             use ConvenientService::Plugins::Common::HasAroundCallbacks::Middleware
@@ -114,47 +135,59 @@ module ConvenientService
               use ConvenientService::Plugins::Common::HasJSendResultDuckShortSyntax::Concern
               use ConvenientService::Plugins::Result::CanRecalculateResult::Concern
 
-              use ConvenientService::Plugins::Result::CanHaveStep::Concern
+              use ConvenientService::Plugins::Result::HasNegatedResult::Concern
               use ConvenientService::Plugins::Result::CanBeOwnResult::Concern
               use ConvenientService::Plugins::Result::CanHaveFallbacks::Concern
               use ConvenientService::Plugins::Result::CanHaveParentResult::Concern
               use ConvenientService::Plugins::Result::CanHaveCheckedStatus::Concern
             end
 
-            middlewares :success? do
-              use ConvenientService::Plugins::Result::CanHaveCheckedStatus::Middleware
+            middlewares :data do
+              use ConvenientService::Plugins::Result::RaisesOnNotCheckedResultStatus::Middleware
             end
 
-            middlewares :failure? do
-              use ConvenientService::Plugins::Result::CanHaveCheckedStatus::Middleware
+            middlewares :message do
+              use ConvenientService::Plugins::Result::RaisesOnNotCheckedResultStatus::Middleware
             end
 
-            middlewares :error? do
-              use ConvenientService::Plugins::Result::CanHaveCheckedStatus::Middleware
+            middlewares :code do
+              use ConvenientService::Plugins::Result::RaisesOnNotCheckedResultStatus::Middleware
             end
 
-            middlewares :not_success? do
-              use ConvenientService::Plugins::Result::CanHaveCheckedStatus::Middleware
-            end
+            middlewares :negated_result do
+              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
 
-            middlewares :not_failure? do
-              use ConvenientService::Plugins::Result::CanHaveCheckedStatus::Middleware
+              use ConvenientService::Plugins::Common::EnsuresNegatedJSendResult::Middleware
             end
 
-            middlewares :not_error? do
-              use ConvenientService::Plugins::Result::CanHaveCheckedStatus::Middleware
-            end
+            class self::Status
+              concerns do
+                use ConvenientService::Plugins::Status::CanBeChecked::Concern
+              end
 
-            middlewares :data do
-              use ConvenientService::Plugins::Result::RaisesOnNotCheckedResultStatus::Middleware
-            end
+              middlewares :success? do
+                use ConvenientService::Plugins::Status::CanBeChecked::Middleware
+              end
 
-            middlewares :message do
-              use ConvenientService::Plugins::Result::RaisesOnNotCheckedResultStatus::Middleware
-            end
+              middlewares :failure? do
+                use ConvenientService::Plugins::Status::CanBeChecked::Middleware
+              end
 
-            middlewares :code do
-              use ConvenientService::Plugins::Result::RaisesOnNotCheckedResultStatus::Middleware
+              middlewares :error? do
+                use ConvenientService::Plugins::Status::CanBeChecked::Middleware
+              end
+
+              middlewares :not_success? do
+                use ConvenientService::Plugins::Status::CanBeChecked::Middleware
+              end
+
+              middlewares :not_failure? do
+                use ConvenientService::Plugins::Status::CanBeChecked::Middleware
+              end
+
+              middlewares :not_error? do
+                use ConvenientService::Plugins::Status::CanBeChecked::Middleware
+              end
             end
           end
 
@@ -166,29 +199,10 @@ module ConvenientService
 
             middlewares :result do
               use ConvenientService::Plugins::Step::CanHaveFallbacks::Middleware.with(fallback_true_status: :failure)
-              use ConvenientService::Plugins::Step::CanHaveParentResult::Middleware
-            end
 
-            middlewares :service_fallback_failure_result do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-              use ConvenientService::Plugins::Common::CachesReturnValue::Middleware
-              use ConvenientService::Plugins::Step::RaisesOnNotResultReturnValue::Middleware
-            end
-
-            middlewares :fallback_failure_result do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-              use ConvenientService::Plugins::Common::CachesReturnValue::Middleware
-            end
-
-            middlewares :service_fallback_error_result do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-              use ConvenientService::Plugins::Common::CachesReturnValue::Middleware
-              use ConvenientService::Plugins::Step::RaisesOnNotResultReturnValue::Middleware
-            end
-
-            middlewares :fallback_error_result do
-              use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
-              use ConvenientService::Plugins::Common::CachesReturnValue::Middleware
+              insert_after \
+                ConvenientService::Plugins::Step::HasResult::Middleware,
+                ConvenientService::Plugins::Step::CanHaveParentResult::Middleware
             end
           end
 

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