convenient_service 0.19.1 → 0.20.0

data/lib/convenient_service/common/plugins/{has_callbacks → can_have_callbacks}/entities/type_collection.rb

@@ -1,23 +1,44 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Common
     module Plugins
-      module HasCallbacks
+      module CanHaveCallbacks
         module Entities
           class TypeCollection
+            ##
+            # @!attribute [r] types
+            #   @return [Array<Symbol>]
+            #
             attr_reader :types
 
+            ##
+            # @param types [Array<Symbol>]
+            # @return [void]
+            #
             def initialize(types:)
               @types = types.map(&Entities::Type.method(:cast!))
             end
 
+            ##
+            # @param other_types [Array<Object>]
+            # @return [Boolean]
+            #
             def contain_exactly?(other_types)
               other_types = other_types.map(&Entities::Type.method(:cast!))
 
               Utils::Array.contain_exactly?(types, other_types)
             end
 
+            ##
+            # @param other [Object] Can be any type.
+            # @return [Boolean, nil]
+            #
             def ==(other)
               return unless other.instance_of?(self.class)
 

data/lib/convenient_service/common/plugins/{has_callbacks → can_have_callbacks}/entities.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>
+##
+
 require_relative "entities/callback_collection"
 require_relative "entities/callback"
 require_relative "entities/type_collection"

data/lib/convenient_service/common/plugins/{has_around_callbacks → can_have_callbacks}/exceptions.rb

@@ -1,14 +1,26 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Common
     module Plugins
-      module HasAroundCallbacks
+      module CanHaveCallbacks
         module Exceptions
           class AroundCallbackChainIsNotContinued < ::ConvenientService::Exception
+            ##
+            # @param callback [ConvenientService::Common::Plugins::CanHaveCallbacks::Entities::Callback]
+            # @return [void]
+            #
+            # @internal
+            #   TODO: `around :#{method} do |chain|`.
+            #
             def initialize_with_kwargs(callback:)
               message = <<~TEXT
-                Around callback chain is NOT continued from `#{callback.block.source_location}`.
+                Around callback chain is NOT continued from `#{callback.source_location_joined_by_colon}`.
 
                 Did you forget to call `chain.yield`? For example:
 

data/lib/convenient_service/common/plugins/can_have_callbacks/middleware.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Common
+    module Plugins
+      module CanHaveCallbacks
+        class Middleware < MethodChainMiddleware
+          ##
+          # @internal
+          #   TODO: Support of callbacks for class methods.
+          #
+          intended_for any_method, entity: any_entity
+
+          ##
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil]
+          # @return [Object] Can be any type.
+          #
+          # @internal
+          #   TODO: Move to command.
+          #
+          def next(*args, **kwargs, &block)
+            run_before_callbacks(*args, **kwargs, &block)
+
+            original_value = run_around_callbacks(*args, **kwargs, &block)
+
+            run_after_callbacks(original_value, *args, **kwargs, &block)
+
+            original_value
+          end
+
+          private
+
+          ##
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil]
+          # @return [void]
+          #
+          # @example Before callbacks.
+          #   class Service
+          #     before :result do
+          #     end
+          #
+          #     before :result do |arguments|
+          #     end
+          #   end
+          #
+          def run_before_callbacks(*args, **kwargs, &block)
+            callbacks.for([:before, method]).each { |callback| callback.call_in_context_with_arguments(entity, *args, **kwargs, &block) }
+          end
+
+          ##
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil]
+          # @return [Object] Can be any type.
+          #
+          # @example After callbacks.
+          #   class Service
+          #     after :result do
+          #     end
+          #
+          #     after :result do |result|
+          #     end
+          #
+          #     after :result do |result, arguments|
+          #     end
+          #   end
+          #
+          def run_after_callbacks(original_value, *args, **kwargs, &block)
+            callbacks.for([:after, method]).reverse_each { |callback| callback.call_in_context_with_value_and_arguments(entity, original_value, *args, **kwargs, &block) }
+          end
+
+          ##
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil]
+          # @return [Object] Can be any type.
+          #
+          # @example Around callbacks.
+          #   class Service
+          #     around :result do |chain|
+          #       # part before `chain.yield`
+          #       original_value = chain.yield
+          #       # part after `chain.yield`
+          #     end
+          #
+          #     around :result do |chain, arguments|
+          #       # part before `chain.yield`
+          #       original_value = chain.yield
+          #       # part after `chain.yield`
+          #     end
+          #   end
+          #
+          def run_around_callbacks(*args, **kwargs, &block)
+            ##
+            # A variable that stores return value of middleware `chain.next` aka `original_value`.
+            # It is reassigned later by the `initial_around_callback`.
+            #
+            original_value = nil
+
+            ##
+            # A list of around callbacks.
+            #
+            # class Service
+            #   around :result do |chain|
+            #     # part before `chain.yield`
+            #     original_value = chain.yield
+            #     # part after `chain.yield`
+            #   end
+            # end
+            #
+            # class Service
+            #   around :result do |chain, arguments|
+            #     # part before `chain.yield`
+            #     original_value = chain.yield
+            #     # part after `chain.yield`
+            #   end
+            # end
+            #
+            # They are wrapped by Ruby hashes in order to have a way to track whether they were called.
+            # That is needed to raise a self-explanatory exception when any around callback misses to call the next callback in a sequence.
+            # See specs for examples and more details.
+            #
+            around_callbacks = callbacks.for([:around, method]).map do |callback_object|
+              {
+                object: callback_object,
+                called: false
+              }
+            end
+
+            ##
+            # So-called initial callback is required to track whether the last around callback in a sequence is called.
+            # See specs for examples and more details.
+            #
+            initial_around_callback = {
+              object: Entities::Callback.new(
+                types: [:around, method],
+                block: proc do
+                  original_value = chain.next(*args, **kwargs, &block)
+
+                  initial_around_callback[:called] = true
+
+                  original_value
+                end
+              ),
+              called: false
+            }
+
+            ##
+            # Let's suppose that we have 3 `around` callbacks:
+            #
+            # class Service
+            #   # first
+            #   around :result do |chain|
+            #     # part before `chain.yield`
+            #     original_value = chain.yield
+            #     # part after `chain.yield`
+            #   end
+            #
+            #   # second
+            #   around :result do |chain|
+            #     # part before `chain.yield`
+            #     original_value = chain.yield
+            #     # part after `chain.yield`
+            #   end
+            #
+            #   # third
+            #   around :result do |chain|
+            #     # part before `chain.yield`
+            #     original_value = chain.yield
+            #     # part after `chain.yield`
+            #   end
+            # end
+            #
+            # NOTE: if a user forgets to call `chain.yield` - an exception is raised.
+            #
+            # Then `composed` may be built with the following preudocode (that is why `reverse` is needed):
+            #
+            #   composed = original
+            #   composed = proc { instance_exec(composed, &third) }
+            #   composed = proc { instance_exec(composed, &second) }
+            #   composed = proc { instance_exec(composed, &first) }
+            #
+            # Where `first`, `second`, `third` are taken from `entity.callbacks.for([:around, method])`.
+            #
+            # Original implementation is modified in order to return `original_value` from all `chain.yield` calls.
+            #
+            #   # Original implementation:
+            #   composed =
+            #     callbacks.for([:around, method]).reverse.reduce(original) do |composed, callback|
+            #       proc { instance_exec(composed, &callback) }
+            #     end
+            #
+            # Original implementation is modified for the second time in order to raise an exception
+            # if a user forgets to call `chain.yield` inside an around callback.
+            #
+            composed =
+              around_callbacks.reverse_each.reduce(initial_around_callback[:object]) do |composed, callback|
+                proc do
+                  callback[:object].call_in_context_with_value_and_arguments(entity, composed, *args, **kwargs, &block)
+
+                  callback[:called] = true
+
+                  original_value
+                end
+              end
+
+            ##
+            # Call sequence:
+            #
+            #   composed.call
+            #   proc { instance_exec(composed, &first) }.call  # part before `chain.yield`
+            #   proc { instance_exec(composed, &second) }.call # part before `chain.yield`
+            #   proc { instance_exec(composed, &third) }.call  # part before `chain.yield`
+            #   initial_around_callback
+            #   proc { instance_exec(composed, &third) }.call  # part after `chain.yield`
+            #   proc { instance_exec(composed, &second) }.call # part after `chain.yield`
+            #   proc { instance_exec(composed, &first) }.call  # part after `chain.yield`
+            #
+            composed.call
+
+            ##
+            # Raised when any intermediate around callback does NOT call `chain.yield`.
+            #
+            #   around :result do |chain|
+            #     puts "first around before result"
+            #
+            #     chain.yield
+            #
+            #     puts "first around after result"
+            #   end
+            #
+            #   around :result do |chain|
+            #     puts "second around before result"
+            #
+            #     puts "second around after result"
+            #   end
+            #
+            #   around :result do |chain|
+            #     puts "third around before result"
+            #
+            #     chain.yield
+            #
+            #     puts "third around after result"
+            #   end
+            #
+            if around_callbacks.any? { |callback| !callback[:called] }
+              last_called_callback = Utils::Array.find_last(around_callbacks) { |callback| callback[:called] }
+
+              ::ConvenientService.raise Exceptions::AroundCallbackChainIsNotContinued.new(callback: last_called_callback[:object])
+            end
+
+            ##
+            # Raised when the last around callback does NOT call `chain.yield`.
+            #
+            #   around :result do |chain|
+            #     puts "first around before result"
+            #
+            #     chain.yield
+            #
+            #     puts "first around after result"
+            #   end
+            #
+            #   around :result do |chain|
+            #     puts "second around before result"
+            #
+            #     puts "second around after result"
+            #   end
+            #
+            if !initial_around_callback[:called]
+              ::ConvenientService.raise Exceptions::AroundCallbackChainIsNotContinued.new(callback: around_callbacks.last[:object])
+            end
+
+            original_value
+          end
+
+          ##
+          # @return [ConvenientService::Common::Plugins::CanHaveCallbacks::Entities::CallbackCollection]
+          #
+          def callbacks
+            @callbacks ||= entity.class.callbacks
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/common/plugins/can_have_callbacks.rb

@@ -0,0 +1,11 @@
+# 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_callbacks/concern"
+require_relative "can_have_callbacks/entities"
+require_relative "can_have_callbacks/exceptions"
+require_relative "can_have_callbacks/middleware"

data/lib/convenient_service/common/plugins/can_have_not_passed_arguments/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 Common
+    module Plugins
+      module CanHaveNotPassedArguments
+        module Concern
+          include Support::Concern
+
+          class_methods do
+            private
+
+            ##
+            # @return [ConvenientService::Support::NOT_PASSED]
+            #
+            def not_passed
+              Support::NOT_PASSED
+            end
+
+            ##
+            # @param argument [Object] Can be any type.
+            # @return [Boolean]
+            #
+            def not_passed?(argument)
+              Support::NOT_PASSED[argument]
+            end
+          end
+
+          instance_methods do
+            private
+
+            ##
+            # @return [ConvenientService::Support::NOT_PASSED]
+            #
+            def not_passed
+              Support::NOT_PASSED
+            end
+
+            ##
+            # @param argument [Object] Can be any type.
+            # @return [Boolean]
+            #
+            def not_passed?(argument)
+              Support::NOT_PASSED[argument]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/common/plugins/can_have_not_passed_arguments.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_not_passed_arguments/concern"

data/lib/convenient_service/common/plugins/can_have_user_provided_entity/commands/find_or_create_entity.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 Common
     module Plugins
@@ -70,9 +75,15 @@ module ConvenientService
               #   # end
               #
               entity.class_exec(proto_entity) do |proto_entity|
+                ##
+                # @return [Class]
+                #
                 define_singleton_method(:proto_entity) { proto_entity }
 
                 ##
+                # @param other [Object] Can by any type.
+                # @return [Boolean, nil]
+                #
                 # @internal
                 #   TODO: Try `self.proto_entity == other.proto_entity if self < proto_entity_concern`.
                 #

data/lib/convenient_service/common/plugins/can_have_user_provided_entity/commands.rb

@@ -1,3 +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 "commands/find_or_create_entity"

data/lib/convenient_service/common/plugins/can_have_user_provided_entity/exceptions.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 Common
     module Plugins

data/lib/convenient_service/common/plugins/can_have_user_provided_entity.rb

@@ -1,5 +1,23 @@
 # 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_user_provided_entity/commands"
-require_relative "can_have_user_provided_entity/container"
 require_relative "can_have_user_provided_entity/exceptions"
+
+module ConvenientService
+  module Common
+    module Plugins
+      module CanHaveUserProvidedEntity
+        class << self
+          def find_or_create_entity(namespace, proto_entity)
+            Commands::FindOrCreateEntity[namespace: namespace, proto_entity: proto_entity]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/common/plugins/can_utilize_finite_loop/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 Common
     module Plugins

data/lib/convenient_service/common/plugins/can_utilize_finite_loop/constants.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 Common
     module Plugins

data/lib/convenient_service/common/plugins/can_utilize_finite_loop.rb

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

data/lib/convenient_service/common/plugins/cleans_exception_backtrace/middleware.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Common
+    module Plugins
+      module CleansExceptionBacktrace
+        class Middleware < MethodChainMiddleware
+          intended_for any_method, scope: any_scope, entity: any_entity
+
+          ##
+          # @return [Object] Can be any type.
+          #
+          # @raise [StandardError]
+          #
+          def next(...)
+            chain.next(...)
+          rescue => exception
+            clean_backtrace!(exception)
+            clean_backtrace!(exception.cause) if exception.cause
+
+            raise
+          end
+
+          private
+
+          ##
+          # @return [Array<String>]
+          #
+          # @internal
+          #   NOTE: Sometimes exceptions may have no backtrace, especially when they are created by developers manually, NOT by Ruby internals.
+          #   - https://blog.kalina.tech/2019/04/exception-without-backtrace-in-ruby.html
+          #   - https://github.com/jruby/jruby/issues/4467
+          #
+          #   NOTE: Check the following tricky behaviour, it explains why an empty array is passed.
+          #     `raise ZeroDivisionError, "exception message", nil` ignores `nil` and still generates full backtrace.
+          #     `raise ZeroDivisionError, "exception message", []` generates no backtrace, but `exception.backtrace` returns `nil`.
+          #
+          def clean_backtrace!(exception)
+            return unless exception.backtrace
+
+            exception.backtrace.replace(backtrace_cleaner.clean(exception.backtrace))
+          end
+
+          ##
+          # @return [ConvenientService::Support::BacktraceCleaner]
+          #
+          def backtrace_cleaner
+            @backtrace_cleaner ||= middleware_arguments.kwargs.fetch(:backtrace_cleaner) { ::ConvenientService.backtrace_cleaner }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/common/plugins/cleans_exception_backtrace.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 "cleans_exception_backtrace/middleware"

data/lib/convenient_service/common/plugins/ensures_negated_j_send_result/middleware.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 Common
     module Plugins

data/lib/convenient_service/common/plugins/ensures_negated_j_send_result.rb

@@ -1,3 +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 "ensures_negated_j_send_result/middleware"

data/lib/convenient_service/common/plugins/has_attributes/using_active_model_attributes/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 Common
     module Plugins

data/lib/convenient_service/common/plugins/has_attributes/using_active_model_attributes/patches/active_model_attributes.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 Common
     module Plugins