convenient_service 0.19.1 → 0.20.0

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanBeCalled
+        module Concern
+          include Support::Concern
+
+          class_methods do
+            ##
+            # When the result has the `success` status, it returns the result data as a hash.
+            # When the result has the `failure` status, it returns `nil`.
+            # When the result has the `error` status, it raises an `ErrorResultIsCalled` exception.
+            #
+            # @api public
+            #
+            # @return [Hash{Symbol => Object}, nil]
+            # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::CanBeCalled::Exceptions::ErrorResultIsCalled]
+            #
+            # @note `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::CanBeCalled::Exceptions::ErrorResultIsCalled` is aliased as `ConvenientService::Result::Exceptions::ErrorResultIsCalled`.
+            # @note `stub_service` RSpec helper affects `call`.
+            #
+            def call(...)
+              result(...).call
+            end
+          end
+
+          instance_methods do
+            ##
+            # When the result has the `success` status, it returns the result data as a hash.
+            # When the result has the `failure` status, it returns `nil`.
+            # When the result has the `error` status, it raises an `ErrorResultIsCalled` exception.
+            #
+            # @api public
+            #
+            # @return [Hash{Symbol => Object}, nil]
+            # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::CanBeCalled::Exceptions::ErrorResultIsCalled]
+            #
+            # @note `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::CanBeCalled::Exceptions::ErrorResultIsCalled` is aliased as `ConvenientService::Result::Exceptions::ErrorResultIsCalled`.
+            # @note `stub_service` RSpec helper affects `call`.
+            #
+            def call
+              result.call
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+require_relative "can_be_called/concern"

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveAfterStepCallbacks
+        class Middleware < MethodChainMiddleware
+          intended_for :after, scope: :class, entity: :service
+
+          ##
+          # @api public
+          #
+          # @param method [Symbol]
+          # @param block [Proc]
+          # @return [ConvenientService::Common::Plugins::CanHaveCallbacks::Entities::Callback]
+          #
+          # @example Before `CanHaveAfterStepCallbacks` usage.
+          #   class Service
+          #     include ::ConvenientService::Standard::Config
+          #
+          #     step :foo
+          #
+          #     entity :Step do
+          #       after :result do |step, arguments|
+          #         organizer.instance_exec(step, arguments) do |step, arguments|
+          #           log("after :step (#{step.index})")
+          #         end
+          #       end
+          #     end
+          #
+          #     def foo
+          #       success
+          #     end
+          #
+          #     private
+          #
+          #     def log(message)
+          #       puts message
+          #     end
+          #   end
+          #
+          # @example After `CanHaveAfterStepCallbacks` usage.
+          #   class Service
+          #     include ::ConvenientService::Standard::Config
+          #
+          #     step :foo
+          #
+          #     after :step do |step, arguments|
+          #       log("after :step (#{step.index})")
+          #     end
+          #
+          #     def foo
+          #       success
+          #     end
+          #
+          #     private
+          #
+          #     def log(message)
+          #       puts message
+          #     end
+          #   end
+          #
+          def next(method, **kwargs, &block)
+            return chain.next(method, **kwargs, &block) if method != :step
+
+            entity.step_class.class_exec(kwargs, block) do |kwargs, block|
+              after :result, **kwargs.merge(source_location: block.source_location) do |result|
+                organizer.instance_exec(
+                  result.step,
+                  params.to_callback_arguments,
+                  &block
+                )
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+require_relative "can_have_after_step_callbacks/middleware"

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveAroundStepCallbacks
+        class Middleware < MethodChainMiddleware
+          intended_for :around, scope: :class, entity: :service
+
+          ##
+          # @api public
+          #
+          # @param method [Symbol]
+          # @param block [Proc]
+          # @return [ConvenientService::Common::Plugins::CanHaveCallbacks::Entities::Callback]
+          #
+          # @example Before `CanHaveAroundStepCallbacks` usage.
+          #   class Service
+          #     include ::ConvenientService::Standard::Config
+          #
+          #     step :foo
+          #
+          #     entity :Step do
+          #       around :step do |chain, arguments|
+          #         organizer.instance_exec(chain, arguments) do |chain, arguments|
+          #           step = chain.yield
+          #
+          #           log("around :step (#{step.index})")
+          #         end
+          #       end
+          #     end
+          #
+          #     def foo
+          #       success
+          #     end
+          #
+          #     private
+          #
+          #     def log(message)
+          #       puts message
+          #     end
+          #   end
+          #
+          # @example After `CanHaveAroundStepCallbacks` usage.
+          #   class Service
+          #     include ::ConvenientService::Standard::Config
+          #
+          #     step :foo
+          #
+          #     around :step do |chain, arguments|
+          #       step = chain.yield
+          #
+          #       log("after :step (#{step.index})")
+          #     end
+          #
+          #     def foo
+          #       success
+          #     end
+          #
+          #     private
+          #
+          #     def log(message)
+          #       puts message
+          #     end
+          #   end
+          #
+          def next(method, **kwargs, &block)
+            return chain.next(method, **kwargs, &block) if method != :step
+
+            entity.step_class.class_exec(kwargs, block) do |kwargs, block|
+              around :result, **kwargs.merge(source_location: block.source_location) do |chain|
+                organizer.instance_exec(
+                  proc { chain.yield.step },
+                  params.to_callback_arguments,
+                  &block
+                )
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+require_relative "can_have_around_step_callbacks/middleware"

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveBeforeStepCallbacks
+        class Middleware < MethodChainMiddleware
+          intended_for :before, scope: :class, entity: :service
+
+          ##
+          # @api public
+          #
+          # @param method [Symbol]
+          # @param block [Proc]
+          # @return [ConvenientService::Common::Plugins::CanHaveCallbacks::Entities::Callback]
+          #
+          # @example Before `CanHaveBeforeStepCallbacks` usage.
+          #   class Service
+          #     include ::ConvenientService::Standard::Config
+          #
+          #     step :foo
+          #
+          #     entity :Step do
+          #       before :result do |arguments|
+          #         organizer.instance_exec(arguments) do |arguments|
+          #           log("before :step")
+          #         end
+          #       end
+          #     end
+          #
+          #     def foo
+          #       success
+          #     end
+          #
+          #     private
+          #
+          #     def log(message)
+          #       puts message
+          #     end
+          #   end
+          #
+          # @example After `CanHaveBeforeStepCallbacks` usage.
+          #   class Service
+          #     include ::ConvenientService::Standard::Config
+          #
+          #     step :foo
+          #
+          #     before :step do |arguments|
+          #       log("before :step")
+          #     end
+          #
+          #     def foo
+          #       success
+          #     end
+          #
+          #     private
+          #
+          #     def log(message)
+          #       puts message
+          #     end
+          #   end
+          #
+          def next(method, **kwargs, &block)
+            return chain.next(method, **kwargs, &block) if method != :step
+
+            entity.step_class.class_exec(kwargs, block) do |kwargs, block|
+              before :result, **kwargs.merge(source_location: block.source_location) do
+                organizer.instance_exec(
+                  params.to_callback_arguments,
+                  &block
+                )
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+require_relative "can_have_before_step_callbacks/middleware"

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -448,6 +453,219 @@ module ConvenientService
                 end
             end
 
+            ##
+            # @api public
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @internal
+            #   TODO: `or_if_step_group`.
+            #
+            def if_step_group(*args, **kwargs, &block)
+              previous_expression = steps.expression
+
+              new_step = steps.create(*args, **kwargs)
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstConditionalGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                if previous_expression.empty?
+                  Entities::Expressions::ComplexIf.new(
+                    Entities::Expressions::If.new(
+                      Entities::Expressions::Scalar.new(new_step),
+                      current_expression
+                    ),
+                    [],
+                    nil
+                  )
+                else
+                  Entities::Expressions::And.new(
+                    previous_expression,
+                    Entities::Expressions::ComplexIf.new(
+                      Entities::Expressions::If.new(
+                        Entities::Expressions::Scalar.new(new_step),
+                        current_expression
+                      ),
+                      [],
+                      nil
+                    )
+                  )
+                end
+            end
+
+            ##
+            # @api public
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            # @internal
+            #   TODO: `or_if_not_step_group`.
+            #
+            def if_not_step_group(*args, **kwargs, &block)
+              previous_expression = steps.expression
+
+              new_step = steps.create(*args, **kwargs)
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstConditionalGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                if previous_expression.empty?
+                  Entities::Expressions::ComplexIf.new(
+                    Entities::Expressions::If.new(
+                      Entities::Expressions::Not.new(
+                        Entities::Expressions::Scalar.new(new_step)
+                      ),
+                      current_expression
+                    ),
+                    [],
+                    nil
+                  )
+                else
+                  Entities::Expressions::And.new(
+                    previous_expression,
+                    Entities::Expressions::ComplexIf.new(
+                      Entities::Expressions::If.new(
+                        Entities::Expressions::Not.new(
+                          Entities::Expressions::Scalar.new(new_step)
+                        ),
+                        current_expression
+                      ),
+                      [],
+                      nil
+                    )
+                  )
+                end
+            end
+
+            ##
+            # @api public
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            def elsif_step_group(*args, **kwargs, &block)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+              ::ConvenientService.raise Exceptions::ElseWithoutIf.new(container: self, method: __method__) unless previous_expression.complex_if?
+              ::ConvenientService.raise Exceptions::ElseIfAfterElse.new(container: self, method: __method__) if previous_expression.else_expression
+
+              new_step = steps.create(*args, **kwargs)
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstConditionalGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                Entities::Expressions::ComplexIf.new(
+                  previous_expression.if_expression,
+                  [
+                    *previous_expression.elsif_expressions,
+                    Entities::Expressions::If.new(
+                      Entities::Expressions::Scalar.new(new_step),
+                      current_expression
+                    )
+                  ],
+                  nil
+                )
+            end
+
+            ##
+            # @api public
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            def elsif_not_step_group(*args, **kwargs, &block)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+              ::ConvenientService.raise Exceptions::ElseWithoutIf.new(container: self, method: __method__) unless previous_expression.complex_if?
+              ::ConvenientService.raise Exceptions::ElseIfAfterElse.new(container: self, method: __method__) if previous_expression.else_expression
+
+              new_step = steps.create(*args, **kwargs)
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstConditionalGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                Entities::Expressions::ComplexIf.new(
+                  previous_expression.if_expression,
+                  [
+                    *previous_expression.elsif_expressions,
+                    Entities::Expressions::If.new(
+                      Entities::Expressions::Not.new(
+                        Entities::Expressions::Scalar.new(new_step)
+                      ),
+                      current_expression
+                    )
+                  ],
+                  nil
+                )
+            end
+
+            ##
+            # @api public
+            #
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
+            #
+            def else_group(*args, **kwargs, &block)
+              previous_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstStepIsNotSet.new(container: self) if previous_expression.empty?
+              ::ConvenientService.raise Exceptions::ElseWithoutIf.new(container: self, method: __method__) unless previous_expression.complex_if?
+              ::ConvenientService.raise Exceptions::ElseIfAfterElse.new(container: self, method: __method__) if previous_expression.else_expression
+
+              steps.expression = Entities::Expressions::Empty.new
+
+              block&.call
+
+              current_expression = steps.expression
+
+              ::ConvenientService.raise Exceptions::FirstConditionalGroupStepIsNotSet.new(container: self, method: __method__) if current_expression.empty?
+
+              steps.expression =
+                Entities::Expressions::ComplexIf.new(
+                  previous_expression.if_expression,
+                  previous_expression.elsif_expressions,
+                  Entities::Expressions::Else.new(current_expression)
+                )
+            end
+
             ##
             # @api private
             #
@@ -459,6 +677,19 @@ module ConvenientService
           end
 
           instance_methods do
+            ##
+            # @api private
+            #
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            #
+            # @internal
+            #   NOTE: Both `regular_result` and `result` do NOT have arguments in the real-world scenarios.
+            #   IMPORTANT: But in case `result` starts to accept arguments, `regular_result` MUST mimic that behavior automatically. That is why argument forwarding is used here.
+            #
+            def regular_result(...)
+              result_without_middlewares(...)
+            end
+
             ##
             # @api public
             #
@@ -476,24 +707,38 @@ module ConvenientService
                   .steps
                   .tap(&:commit!)
                   .with_organizer(self)
-                  .tap(&:commit!)
               end
             end
 
             ##
-            # @api private
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            # @raise [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Exceptions::ServiceHasNoSteps]
+            #
+            def steps_result
+              ::ConvenientService.raise Exceptions::ServiceHasNoSteps.new(service_class: self.class) if steps.none?
+
+              steps.each_evaluated_step do |step|
+                step.save_outputs_in_organizer!
+
+                step.mark_as_evaluated!
+              end
+
+              steps.result
+            end
+
+            ##
+            # @api public
             #
-            # Returns step by index.
-            # Returns `nil` when index is out of range.
+            # Registers a step (step definition).
             #
-            # @param index [Integer]
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
             # @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
+            # TODO: Dynamic expressions.
             #
-            def step(index)
-              steps[index]
+            def step(*args, **kwargs)
+              self.class.step_class.new(*args, **kwargs.merge(container: self.class, organizer: self, index: nil))
             end
           end
         end

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Service
     module Plugins
@@ -21,7 +26,7 @@ module ConvenientService
 
               ##
               # @param left_expression [ConvenientService::Service::Plugins::CanHaveConnectedSteps::Entities::Expressions::Base]
-              # @param right_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)
@@ -36,6 +41,13 @@ module ConvenientService
                 left_expression.success? ? right_expression.result : left_expression.result
               end
 
+              ##
+              # @return [ConvenientService::Service]
+              #
+              def organizer
+                left_expression.organizer
+              end
+
               ##
               # @return [Boolean]
               #
@@ -110,7 +122,7 @@ module ConvenientService
 
               ##
               # @param other [Object] Can be any type.
-              # @return [Boolean]
+              # @return [Boolean, nil]
               #
               def ==(other)
                 return unless other.instance_of?(self.class)