convenient_service 0.12.0 → 0.14.0

data/lib/convenient_service/rspec/matchers/results/be_failure.rb

@@ -5,6 +5,9 @@ module ConvenientService
     module Matchers
       module Results
         module BeFailure
+          ##
+          # @api public
+          #
           def be_failure(...)
             Custom::Results::BeFailure.new(...)
           end

data/lib/convenient_service/rspec/matchers/results/be_not_error.rb

@@ -5,6 +5,9 @@ module ConvenientService
     module Matchers
       module Results
         module BeNotError
+          ##
+          # @api public
+          #
           def be_not_error(...)
             Custom::Results::BeNotError.new(...)
           end

data/lib/convenient_service/rspec/matchers/results/be_not_failure.rb

@@ -5,6 +5,9 @@ module ConvenientService
     module Matchers
       module Results
         module BeNotFailure
+          ##
+          # @api public
+          #
           def be_not_failure(...)
             Custom::Results::BeNotFailure.new(...)
           end

data/lib/convenient_service/rspec/matchers/results/be_not_success.rb

@@ -5,6 +5,9 @@ module ConvenientService
     module Matchers
       module Results
         module BeNotSuccess
+          ##
+          # @api public
+          #
           def be_not_success(...)
             Custom::Results::BeNotSuccess.new(...)
           end

data/lib/convenient_service/rspec/matchers/results/be_result.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module Matchers
+      module Results
+        module BeResult
+          ##
+          # @api public
+          #
+          def be_result(status, *args, **kwargs, &block)
+            case status
+            when :success
+              Custom::Results::BeSuccess.new(*args, **kwargs, &block)
+            when :failure
+              Custom::Results::BeFailure.new(*args, **kwargs, &block)
+            when :error
+              Custom::Results::BeError.new(*args, **kwargs, &block)
+            when :not_success
+              Custom::Results::BeNotSuccess.new(*args, **kwargs, &block)
+            when :not_failure
+              Custom::Results::BeNotFailure.new(*args, **kwargs, &block)
+            when :not_error
+              Custom::Results::BeNotError.new(*args, **kwargs, &block)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/matchers/results/be_success.rb

@@ -5,6 +5,9 @@ module ConvenientService
     module Matchers
       module Results
         module BeSuccess
+          ##
+          # @api public
+          #
           def be_success(...)
             Custom::Results::BeSuccess.new(...)
           end

data/lib/convenient_service/rspec/matchers/results.rb

@@ -8,6 +8,8 @@ require_relative "results/be_not_error"
 require_relative "results/be_not_failure"
 require_relative "results/be_not_success"
 
+require_relative "results/be_result"
+
 module ConvenientService
   module RSpec
     module Matchers
@@ -22,6 +24,8 @@ module ConvenientService
           include Results::BeNotError
           include Results::BeNotFailure
           include Results::BeNotSuccess
+
+          include Results::BeResult
         end
       end
     end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveFallbacks
+        module Concern
+          include Support::Concern
+
+          instance_methods do
+            ##
+            # Returns `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result` when overridden.
+            #
+            # @raise [ConvenientService::Service::Plugins::CanHaveFallbacks::Exceptions::FallbackResultIsNotOverridden]
+            #
+            def fallback_failure_result
+              raise Exceptions::FallbackResultIsNotOverridden.new(service: self, status: :failure)
+            end
+
+            ##
+            # Returns `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result` when overridden.
+            #
+            # @raise [ConvenientService::Service::Plugins::CanHaveFallbacks::Exceptions::FallbackResultIsNotOverridden]
+            #
+            def fallback_error_result
+              raise Exceptions::FallbackResultIsNotOverridden.new(service: self, status: :error)
+            end
+          end
+
+          class_methods do
+            ##
+            # Returns `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result` when `#fallback_result` is overridden.
+            #
+            # @raise [ConvenientService::Service::Plugins::CanHaveFallbacks::Exceptions::FallbackResultIsNotOverridden]
+            #
+            def fallback_failure_result(...)
+              new(...).fallback_failure_result
+            end
+
+            ##
+            # Returns `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result` when `#fallback_result` is overridden.
+            #
+            # @raise [ConvenientService::Service::Plugins::CanHaveFallbacks::Exceptions::FallbackResultIsNotOverridden]
+            #
+            # @example `fallback_error_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_error_result` must also return a relation.
+            #
+            #     class SelectActiveUsers
+            #       include ConvenientService::Standard::Config
+            #
+            #       # ...
+            #
+            #       def fallback_error_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_error_result`
+            #
+            #   if result.success?
+            #     result.data[:users].count
+            #   end
+            #
+            #   It is safe to invoke `count` for both `result` and `fallback_error_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_error_result`?
+            #
+            def fallback_error_result(...)
+              new(...).fallback_error_result
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveFallbacks
+        class Middleware < MethodChainMiddleware
+          intended_for [:fallback_failure_result, :fallback_error_result], entity: :service
+
+          ##
+          # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+          #
+          # @note Both `fallback_failure_result` and `fallback_error_result` are always successful, that is why their statuses are pre-checked.
+          #
+          def next(...)
+            fallback_result = chain.next(...)
+
+            raise Exceptions::ServiceFallbackReturnValueNotSuccess.new(service: entity, result: fallback_result, status: status) unless fallback_result.success?
+
+            fallback_result.copy(overrides: {kwargs: {method => true}})
+              .tap { |result| result.success? }
+          end
+
+          private
+
+          ##
+          # @return [Symbol]
+          #
+          def status
+            middleware_arguments.kwargs.fetch(:status)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "can_have_fallbacks/concern"
+require_relative "can_have_fallbacks/exceptions"
+require_relative "can_have_fallbacks/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:)