convenient_service 0.12.0 → 0.13.0

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveFallback
+        module Concern
+          include Support::Concern
+
+          instance_methods do
+            ##
+            # Returns `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result` when overridden.
+            #
+            # @raise [ConvenientService::Service::Plugins::CanHaveFallback::Exceptions::FallbackResultIsNotOverridden]
+            #
+            # @internal
+            #   NOTE: name is inspired by Ruby's `fallback_convert` methods.
+            #   - https://blog.saeloun.com/2021/08/03/ruby-adds-integer-try-convert
+            #
+            #   TODO: A plugin that checks that a `success` is returned from `fallback_result`.
+            #
+            def fallback_result
+              raise Exceptions::FallbackResultIsNotOverridden.new(service: self)
+            end
+          end
+
+          class_methods do
+            ##
+            # Returns `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result` when `#fallback_result` is overridden.
+            #
+            # @raise [ConvenientService::Service::Plugins::CanHaveFallback::Exceptions::FallbackResultIsNotOverridden]
+            #
+            # @example `fallback_result` method MUST always return `success` with reasonable "null" data.
+            #
+            #   For example, check the following service:
+            #
+            #     class SelectActiveUsers
+            #       include ConvenientService::Standard::Config
+            #
+            #       # ...
+            #
+            #       def result
+            #         # ...
+            #
+            #         success(users: ::User.where(active: true))
+            #       end
+            #
+            #       # ...
+            #     end
+            #
+            #   Since `result` returns relation for `users` when it is successful, its corresponding `fallback_result` must also return a relation.
+            #
+            #     class SelectActiveUsers
+            #       include ConvenientService::Standard::Config
+            #
+            #       # ...
+            #
+            #       def fallback_result
+            #         # ...
+            #
+            #         success(users: ::User.none)
+            #       end
+            #
+            #       # ...
+            #     end
+            #
+            #   This way a significant amount of extra `if` statements can be avoided.
+            #
+            #   result = SelectActiveUsers.result # or `result = SelectActiveUsers.fallback_result`
+            #
+            #   if result.success?
+            #     result.data[:users].count
+            #   end
+            #
+            #   It is safe to invoke `count` for both `result` and `fallback_result` since `result.data[:users]` return same class.
+            #
+            #   This idea can be applied in a broader sense by utilizing the Null object pattern.
+            #
+            # @see https://thoughtbot.com/blog/rails-refactoring-example-introduce-null-object
+            # @see https://en.wikipedia.org/wiki/Null_object_pattern
+            #
+            # @internal
+            #   TODO: Is it necessary to use `SetsParentToForeignResult` for `fallback_result`?
+            #
+            def fallback_result(...)
+              new(...).fallback_result
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_fallback/exceptions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveFallback
+        module Exceptions
+          class FallbackResultIsNotOverridden < ::ConvenientService::Exception
+            def initialize(service:)
+              message = <<~TEXT
+                Fallback result method (#fallback_result) of `#{service.class}` is NOT overridden.
+
+                NOTE: Make sure overridden `fallback_result` returns `success` with reasonable "null" data.
+              TEXT
+
+              super(message)
+            end
+          end
+
+          class ServiceFallbackReturnValueNotSuccess < ::ConvenientService::Exception
+            def initialize(service:, result:)
+              message = <<~TEXT
+                Return value of service `#{service.class}` try is NOT a `success`.
+                It is `#{result.status}`.
+
+                Did you accidentally call `failure` or `error` instead of `success` from the `fallback_result` method?
+              TEXT
+
+              super(message)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveFallback
+        class Middleware < MethodChainMiddleware
+          intended_for :fallback_result, entity: :service
+
+          ##
+          # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+          #
+          # @note `fallback_result` is always successful, that is why its status is pre-checked.
+          #
+          # @internal
+          #   NOTE: Copy is returned to have a fresh status.
+          #
+          def next(...)
+            fallback_result = chain.next(...)
+
+            raise Exceptions::ServiceFallbackReturnValueNotSuccess.new(service: entity, result: fallback_result) unless fallback_result.success?
+
+            fallback_result.copy(overrides: {kwargs: {fallback_result: true}})
+              .tap { |result| result.success? }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "can_have_fallback/concern"
+require_relative "can_have_fallback/exceptions"
+require_relative "can_have_fallback/middleware"

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

@@ -4,38 +4,19 @@ module ConvenientService
   module Service
     module Plugins
       module CanHaveMethodSteps
-        class Middleware < Core::MethodChainMiddleware
+        class Middleware < MethodChainMiddleware
+          intended_for :step, scope: :class, entity: :service
+
           ##
           # @param args [Array<Object>]
           # @param kwargs [Hash{Symbol => Object}]
           # @param block [Proc, nil]
-          # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
-          #
-          # @internal
-          #   NOTE: It is okish to assign to next method arguments here,
-          #   since splat for `args` and double splat for `kwargs`
-          #   always create new arrays and hashes respectively.
-          #   https://github.com/ruby/spec/blob/c7ed8478a031d0df346d222495f4b4bbb298523b/language/keyword_arguments_spec.rb#L100
+          # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
           #
           def next(*args, **kwargs, &block)
             return chain.next(*args, **kwargs, &block) unless args.first.instance_of?(::Symbol)
-            return chain.next(*args, **kwargs, &block) if args.first == :result
-
-            kwargs[:in] = Utils::Array.wrap(kwargs[:in]) + [{method_name: raw(args.first)}, {organizer: :itself}]
 
-            args[0] = Services::RunMethodInOrganizer
-
-            chain.next(*args, **kwargs, &block)
-          end
-
-          private
-
-          ##
-          # @param object [Object] Can be any type.
-          # @return [ConvenientService::Support::RawValue]
-          #
-          def raw(object)
-            Support::RawValue.wrap(object)
+            chain.next(entity, *args[1..], **kwargs.merge(method: args.first), &block)
           end
         end
       end

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

@@ -11,6 +11,9 @@ module ConvenientService
             ##
             # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
             #
+            # @internal
+            #   IMPORTANT: `map` result is NOT wrapped by `StepCollection` in order to NOT expose too much internals to the end-user.
+            #
             def steps
               internals.cache.fetch(:steps) do
                 self.class

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/commands/cast_method.rb

@@ -52,35 +52,35 @@ module ConvenientService
                 # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Factories::Base]
                 #
                 def factory
-                  Utils::Object.memoize_including_falsy_values(self, :@factory) { Commands::CastMethodFactory.call(other: other) }
+                  Utils.memoize_including_falsy_values(self, :@factory) { Commands::CastMethodFactory.call(other: other) }
                 end
 
                 ##
                 # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Key]
                 #
                 def key
-                  Utils::Object.memoize_including_falsy_values(self, :@key) { factory&.create_key }
+                  Utils.memoize_including_falsy_values(self, :@key) { factory&.create_key }
                 end
 
                 ##
                 # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Name]
                 #
                 def name
-                  Utils::Object.memoize_including_falsy_values(self, :@name) { factory&.create_name }
+                  Utils.memoize_including_falsy_values(self, :@name) { factory&.create_name }
                 end
 
                 ##
                 # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Callers::Base]
                 #
                 def caller
-                  Utils::Object.memoize_including_falsy_values(self, :@caller) { factory&.create_caller }
+                  Utils.memoize_including_falsy_values(self, :@caller) { factory&.create_caller }
                 end
 
                 ##
                 # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Direction::Base]
                 #
                 def direction
-                  Utils::Object.memoize_including_falsy_values(self, :@direction) { Commands::CastMethodDirection.call(other: other, options: options) }
+                  Utils.memoize_including_falsy_values(self, :@direction) { Commands::CastMethodDirection.call(other: other, options: options) }
                 end
               end
             end

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/commands/cast_method_factory.rb

@@ -36,7 +36,7 @@ module ConvenientService
                 # @return [Class, nil]
                 #
                 def factory_class
-                  Utils::Object.memoize_including_falsy_values(self, :@factory_class) do
+                  Utils.memoize_including_falsy_values(self, :@factory_class) do
                     case other
                     when ::Symbol then cast_symbol
                     when ::String then cast_string

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/commands/define_method_in_container.rb

@@ -43,13 +43,13 @@ module ConvenientService
 
                 def not_completed_step_error
                   <<~RUBY.chomp
-                    ::ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Errors::NotCompletedStep
+                    ::ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Exceptions::NotCompletedStep
                   RUBY
                 end
 
                 def not_existing_step_result_data_attribute_error
                   <<~RUBY.chomp
-                    ::ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Errors::NotExistingStepResultDataAttribute
+                    ::ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Exceptions::NotExistingStepResultDataAttribute
                   RUBY
                 end
               end

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/concern/instance_methods.rb

@@ -10,10 +10,43 @@ module ConvenientService
               module InstanceMethods
                 include Support::Delegate
 
-                attr_reader :key, :name, :caller, :direction, :organizer
+                ##
+                # @!attribute [r] key
+                #   @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Key]
+                #
+                attr_reader :key
+
+                ##
+                # @!attribute [r] name
+                #   @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Name]
+                #
+                attr_reader :name
+
+                ##
+                # @!attribute [r] caller
+                #   @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Callers::Base]
+                #
+                attr_reader :caller
 
+                ##
+                # @!attribute [r] direction
+                #   @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Directions::Base]
+                #
+                attr_reader :direction
+
+                ##
+                # @return [String]
+                #
                 delegate :to_s, to: :name
 
+                ##
+                # @param key [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Key]
+                # @param name [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Name]
+                # @param caller [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Callers::Base]
+                # @param direction [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Directions::Base]
+                # @param organizer [ConvenientService::Service, nil]
+                # @return [void]
+                #
                 def initialize(key:, name:, caller:, direction:, organizer: nil)
                   @key = key
                   @name = name
@@ -22,26 +55,43 @@ module ConvenientService
                   @organizer = organizer
                 end
 
-                def ==(other)
-                  return unless other.instance_of?(self.class)
+                ##
+                # @param raise_when_missing [Boolean]
+                # @return [ConvenientService::Service, nil]
+                # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Exceptions::MethodHasNoOrganizer]
+                #
+                def organizer(raise_when_missing: true)
+                  raise Exceptions::MethodHasNoOrganizer.new(method: self) if @organizer.nil? && raise_when_missing
 
-                  return false if key != other.key
-                  return false if name != other.name
-                  return false if caller != other.caller
-                  return false if direction != other.direction
-                  return false if organizer != other.organizer
+                  @organizer
+                end
 
-                  true
+                ##
+                # @return [Object] Can be any type.
+                #
+                def value
+                  @value ||= caller.calculate_value(self)
                 end
 
+                ##
+                # @return [Boolean]
+                #
                 def has_organizer?
-                  Utils::Bool.to_bool(organizer)
+                  Utils.to_bool(organizer(raise_when_missing: false))
                 end
 
+                ##
+                # @param name [Symbol, String]
+                # @return [Boolean]
+                #
                 def reassignment?(name)
                   caller.reassignment?(name)
                 end
 
+                ##
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def validate_as_input_for_container!(container)
                   direction.validate_as_input_for_container!(container, method: self)
 
@@ -50,6 +100,10 @@ module ConvenientService
                   true
                 end
 
+                ##
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def validate_as_output_for_container!(container)
                   direction.validate_as_output_for_container!(container, method: self)
 
@@ -58,6 +112,11 @@ module ConvenientService
                   true
                 end
 
+                ##
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @param index [Integer]
+                # @return [void]
+                #
                 def define_output_in_container!(container, index:)
                   direction.define_output_in_container!(container, index: index, method: self)
 
@@ -66,29 +125,40 @@ module ConvenientService
                   true
                 end
 
-                def value
-                  @value ||= calculate_value
-                end
-
-                def to_kwargs
-                  {key: key, name: name, caller: caller, direction: direction, organizer: organizer}
-                end
-
-                private
+                ##
+                # @param other [Object] Can be any object.
+                # @return [Boolean, nil]
+                #
+                def ==(other)
+                  return unless other.instance_of?(self.class)
 
-                def calculate_value
-                  assert_has_organizer!
+                  return false if key != other.key
+                  return false if name != other.name
+                  return false if caller != other.caller
+                  return false if direction != other.direction
+                  return false if organizer(raise_when_missing: false) != other.organizer(raise_when_missing: false)
 
-                  caller.calculate_value(self)
+                  true
                 end
 
                 ##
-                # TODO: Return `true` for valid assertions.
+                # @return [Hash{Symbol => Object}]
                 #
-                def assert_has_organizer!
-                  return if has_organizer?
+                def to_kwargs
+                  to_arguments.kwargs
+                end
 
-                  raise Errors::MethodHasNoOrganizer.new(method: self)
+                ##
+                # @return [ConvenientService::Support::Arguments]
+                #
+                def to_arguments
+                  Support::Arguments.new(
+                    key: key,
+                    name: name,
+                    caller: caller,
+                    direction: direction,
+                    organizer: organizer(raise_when_missing: false)
+                  )
                 end
               end
             end

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/alias.rb

@@ -16,13 +16,13 @@ module ConvenientService
                   def validate_as_input_for_container!(container, method:)
                     return true if container.has_defined_method?(method)
 
-                    raise Errors::AliasInputMethodIsNotDefinedInContainer.new(method: method, container: container)
+                    raise Exceptions::AliasInputMethodIsNotDefinedInContainer.new(method: method, container: container)
                   end
 
                   def validate_as_output_for_container!(container, method:)
                     return true unless container.has_defined_method?(method)
 
-                    raise Errors::AliasOutputMethodIsDefinedInContainer.new(method: method, container: container)
+                    raise Exceptions::AliasOutputMethodIsDefinedInContainer.new(method: method, container: container)
                   end
 
                   def define_output_in_container!(container, index:, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/base.rb

@@ -13,24 +13,56 @@ module ConvenientService
                   include Support::Copyable
 
                   ##
-                  # TODO: A better name for `object`. Wrapped object, `target`?
+                  # @!attribute [r] object
+                  #   @return [Object] Can be any type.
+                  #
+                  # @internal
+                  #   TODO: A better name for `object`. Wrapped object, `target`?
                   #
                   attr_reader :object
 
-                  abstract_method \
-                    :calculate_value,
-                    :validate_as_input_for_container!,
-                    :validate_as_output_for_container!,
-                    :define_output_in_container!
+                  ##
+                  # @return [Object] Can be any type.
+                  #
+                  abstract_method :calculate_value
+
+                  ##
+                  # @return [Boolean]
+                  # @raise [ConvenientService::Error]
+                  #
+                  abstract_method :validate_as_input_for_container!
+
+                  ##
+                  # @return [Boolean]
+                  # @raise [ConvenientService::Error]
+                  #
+                  abstract_method :validate_as_output_for_container!
+
+                  ##
+                  # @return [Boolean]
+                  #
+                  abstract_method :define_output_in_container!
 
+                  ##
+                  # @param object [Object] Can be any type.
+                  # @return [void]
+                  #
                   def initialize(object)
                     @object = object
                   end
 
+                  ##
+                  # @param name [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method::Entities::Name]
+                  # @return [Boolean]
+                  #
                   def reassignment?(name)
                     false
                   end
 
+                  ##
+                  # @param other [Object] Can be any type.
+                  # @return [Boolean, nil]
+                  #
                   def ==(other)
                     return unless other.instance_of?(self.class)
 
@@ -39,8 +71,18 @@ module ConvenientService
                     true
                   end
 
+                  ##
+                  # @return [Array<Object>]
+                  #
                   def to_args
-                    [object]
+                    to_arguments.args
+                  end
+
+                  ##
+                  # @return [ConveninentService::Support::Arguments]
+                  #
+                  def to_arguments
+                    Support::Arguments.new(object)
                   end
                 end
               end

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/proc.rb

@@ -21,7 +21,7 @@ module ConvenientService
                     ##
                     # TODO: Better error message.
                     #
-                    raise Errors::OutputMethodProc.new(method: method, container: container)
+                    raise Exceptions::OutputMethodProc.new(method: method, container: container)
                   end
 
                   def define_output_in_container!(container, index:, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/raw.rb

@@ -21,7 +21,7 @@ module ConvenientService
                     ##
                     # TODO: Better error message.
                     #
-                    raise Errors::OutputMethodRawValue.new(container: container, method: method)
+                    raise Exceptions::OutputMethodRawValue.new(container: container, method: method)
                   end
 
                   def define_output_in_container!(container, index:, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/reassignment.rb

@@ -22,11 +22,11 @@ module ConvenientService
                   # TODO: Separate `in` and `out` methods?
                   #
                   def calculate_value(method)
-                    raise Errors::CallerCanNotCalculateReassignment.new(method: method)
+                    raise Exceptions::CallerCanNotCalculateReassignment.new(method: method)
                   end
 
                   def validate_as_input_for_container!(container, method:)
-                    raise Errors::InputMethodReassignment.new(method: method, container: container)
+                    raise Exceptions::InputMethodReassignment.new(method: method, container: container)
                   end
 
                   def validate_as_output_for_container!(container, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/callers/usual.rb

@@ -16,13 +16,13 @@ module ConvenientService
                   def validate_as_input_for_container!(container, method:)
                     return true if container.has_defined_method?(method)
 
-                    raise Errors::InputMethodIsNotDefinedInContainer.new(method: method, container: container)
+                    raise Exceptions::InputMethodIsNotDefinedInContainer.new(method: method, container: container)
                   end
 
                   def validate_as_output_for_container!(container, method:)
                     return true unless container.has_defined_method?(method)
 
-                    raise Errors::OutputMethodIsDefinedInContainer.new(method: method, container: container)
+                    raise Exceptions::OutputMethodIsDefinedInContainer.new(method: method, container: container)
                   end
 
                   def define_output_in_container!(container, index:, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/directions/base.rb

@@ -12,16 +12,39 @@ module ConvenientService
                   include Support::AbstractMethod
                   include Support::Copyable
 
-                  abstract_method \
-                    :validate_as_input_for_container!,
-                    :validate_as_output_for_container!,
-                    :define_output_in_container!
+                  ##
+                  # @return [Boolean]
+                  # @raise [ConvenientService::Error]
+                  #
+                  abstract_method :validate_as_input_for_container!
 
+                  ##
+                  # @return [Boolean]
+                  # @raise [ConvenientService::Error]
+                  #
+                  abstract_method :validate_as_output_for_container!
+
+                  ##
+                  # @return [Boolean]
+                  #
+                  abstract_method :define_output_in_container!
+
+                  ##
+                  # @param other [Object] Can be any type.
+                  # @return [Boolean, nil]
+                  #
                   def ==(other)
                     return unless other.instance_of?(self.class)
 
                     true
                   end
+
+                  ##
+                  # @return [ConvenientService::Support::Arguments]
+                  #
+                  def to_arguments
+                    Support::Arguments.new
+                  end
                 end
               end
             end