convenient_service 0.17.0 → 0.18.0

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/has_result/middleware.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module HasResult
+                class Middleware < MethodChainMiddleware
+                  intended_for :result, entity: :step
+
+                  ##
+                  # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                  # @raise [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Exceptions::StepHasNoOrganizer]
+                  #
+                  # @internal
+                  #   NOTE: Convents a foreign result received from `service_result` to own result.
+                  #   TODO: `service.result`.
+                  #
+                  def next(...)
+                    chain.next(...).copy(overrides: {kwargs: {step: entity, service: entity.organizer}})
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/has_result.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "has_result/concern"
+require_relative "has_result/middleware"

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "plugins/has_result"
+
 require_relative "plugins/can_be_completed"
 require_relative "plugins/can_be_method_step"
-require_relative "plugins/can_be_result_step"
 require_relative "plugins/can_have_fallbacks"
 require_relative "plugins/can_have_parent_result"
 require_relative "plugins/has_inspect"

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

@@ -2,5 +2,4 @@
 
 require_relative "entities/service"
 require_relative "entities/method"
-require_relative "entities/step_collection"
 require_relative "entities/step"

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

@@ -2,5 +2,4 @@
 
 require_relative "can_have_steps/commands"
 require_relative "can_have_steps/concern"
-require_relative "can_have_steps/middleware"
 require_relative "can_have_steps/entities"

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/can_have_checked_status/concern.rb

@@ -15,8 +15,8 @@ module ConvenientService
                     ##
                     # @return [Boolean]
                     #
-                    def has_checked_status?
-                      Utils.to_bool(internals.cache[:has_checked_status])
+                    def checked?
+                      status.checked?
                     end
                   end
                 end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/can_have_checked_status.rb

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
 
 require_relative "can_have_checked_status/concern"
-require_relative "can_have_checked_status/middleware"

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/concern/instance_methods.rb

@@ -167,10 +167,143 @@ module ConvenientService
                     end
 
                     ##
-                    # @return [Boolean, nil]
+                    # Returns a boolean representation of `result`.
+                    # `success` may be considered as `true`.
+                    # `failure` may be considered as `false`.
+                    # `error` may be considered as `raise exception`.
+                    #
+                    # @api public
+                    # @return [Boolean]
+                    # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Status::Exceptions::ErrorHasNoOtherTypeRepresentation]
+                    #
+                    # @note This method is useful for learning purposes, to show similarities with Ruby's booleans. Please, do NOT depend on it in production.
+                    #
+                    # @internal
+                    #   NOTE: When `value` is NOT `:success`, `:failure` or `:error`, then something fatal has happened.
                     #
                     def to_bool
-                      status.to_bool
+                      case status.value
+                      when :success
+                        true
+                      when :failure
+                        false
+                      when :error
+                        raise ::ConvenientService.raise Exceptions::ErrorHasNoOtherTypeRepresentation.new(type: :boolean)
+                      else
+                        raise ::ConvenientService.raise Support::NeverReachHere.new(extra_message: "Unknown result status `#{status.value}`.")
+                      end
+                    end
+
+                    ##
+                    # Returns a boolean representation of `result`.
+                    # `success` may be considered as `object`.
+                    # `failure` may be considered as `nil` (or null object).
+                    # `error` may be considered as `raise exception`.
+                    #
+                    # @api public
+                    # @return [ConvenientService::Support::Value]
+                    # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Status::Exceptions::ErrorHasNoOtherTypeRepresentation]
+                    #
+                    # @note This method is useful for learning purposes, to show similarities with Ruby's objects. Please, do NOT depend on it in production.
+                    #
+                    # @internal
+                    #   NOTE: When `value` is NOT `:success`, `:failure` or `:error`, then something fatal has happened.
+                    #
+                    def to_object
+                      case status.value
+                      when :success
+                        Support::Value.new("object")
+                      when :failure
+                        nil
+                      when :error
+                        raise ::ConvenientService.raise Exceptions::ErrorHasNoOtherTypeRepresentation.new(type: :object)
+                      else
+                        raise ::ConvenientService.raise Support::NeverReachHere.new(extra_message: "Unknown result status `#{status.value}`.")
+                      end
+                    end
+
+                    ##
+                    # Returns an array representation of `result`.
+                    # `success` may be considered as array with items.
+                    # `failure` may be considered as empty array.
+                    # `error` may be considered as `raise exception`.
+                    #
+                    # @api public
+                    # @return [Array<ConvenientService::Support::Value>]
+                    # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Status::Exceptions::ErrorHasNoOtherTypeRepresentation]
+                    #
+                    # @note This method is useful for learning purposes, to show similarities with Ruby's objects. Please, do NOT depend on it in production.
+                    #
+                    # @internal
+                    #   NOTE: When `value` is NOT `:success`, `:failure` or `:error`, then something fatal has happened.
+                    #
+                    def to_a
+                      case status.value
+                      when :success
+                        [Support::Value.new("item")]
+                      when :failure
+                        []
+                      when :error
+                        raise ::ConvenientService.raise Exceptions::ErrorHasNoOtherTypeRepresentation.new(type: :array)
+                      else
+                        raise ::ConvenientService.raise Support::NeverReachHere.new(extra_message: "Unknown result status `#{status.value}`.")
+                      end
+                    end
+
+                    ##
+                    # Returns a hash representation of `result`.
+                    # `success` may be considered as hash with items.
+                    # `failure` may be considered as empty hash.
+                    # `error` may be considered as `raise exception`.
+                    #
+                    # @api public
+                    # @return [Hash{ConvenientService::Support::Value => ConvenientService::Support::Value}]
+                    # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Status::Exceptions::ErrorHasNoOtherTypeRepresentation]
+                    #
+                    # @note This method is useful for learning purposes, to show similarities with Ruby's objects. Please, do NOT depend on it in production.
+                    #
+                    # @internal
+                    #   NOTE: When `value` is NOT `:success`, `:failure` or `:error`, then something fatal has happened.
+                    #
+                    def to_h
+                      case status.value
+                      when :success
+                        {Support::Value.new("key") => Support::Value.new("value")}
+                      when :failure
+                        {}
+                      when :error
+                        raise ::ConvenientService.raise Exceptions::ErrorHasNoOtherTypeRepresentation.new(type: :hash)
+                      else
+                        raise ::ConvenientService.raise Support::NeverReachHere.new(extra_message: "Unknown result status `#{status.value}`.")
+                      end
+                    end
+
+                    ##
+                    # Returns a string representation of `result`.
+                    # `success` may be considered as string with content.
+                    # `failure` may be considered as empty string.
+                    # `error` may be considered as `raise exception`.
+                    #
+                    # @api public
+                    # @return [String]
+                    # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Status::Exceptions::ErrorHasNoOtherTypeRepresentation]
+                    #
+                    # @note This method is useful for learning purposes, to show similarities with Ruby's objects. Please, do NOT depend on it in production.
+                    #
+                    # @internal
+                    #   NOTE: When `value` is NOT `:success`, `:failure` or `:error`, then something fatal has happened.
+                    #
+                    def to_s
+                      case status.value
+                      when :success
+                        "string"
+                      when :failure
+                        ""
+                      when :error
+                        raise ::ConvenientService.raise Exceptions::ErrorHasNoOtherTypeRepresentation.new(type: :string)
+                      else
+                        raise ::ConvenientService.raise Support::NeverReachHere.new(extra_message: "Unknown result status `#{status.value}`.")
+                      end
                     end
                   end
                 end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/entities/status/concern/instance_methods.rb

@@ -70,25 +70,67 @@ module ConvenientService
                           value == :error
                         end
 
+                        ##
+                        # @return [Boolean]
+                        #
+                        def unsafe_success?
+                          value == :success
+                        end
+
+                        ##
+                        # @return [Boolean]
+                        #
+                        def unsafe_failure?
+                          value == :failure
+                        end
+
+                        ##
+                        # @return [Boolean]
+                        #
+                        def unsafe_error?
+                          value == :error
+                        end
+
                         ##
                         # @return [Boolean]
                         #
                         def not_success?
-                          !success?
+                          value != :success
                         end
 
                         ##
                         # @return [Boolean]
                         #
                         def not_failure?
-                          !failure?
+                          value != :failure
                         end
 
                         ##
                         # @return [Boolean]
                         #
                         def not_error?
-                          !error?
+                          value != :error
+                        end
+
+                        ##
+                        # @return [Boolean]
+                        #
+                        def unsafe_not_success?
+                          value != :success
+                        end
+
+                        ##
+                        # @return [Boolean]
+                        #
+                        def unsafe_not_failure?
+                          value != :failure
+                        end
+
+                        ##
+                        # @return [Boolean]
+                        #
+                        def unsafe_not_error?
+                          value != :error
                         end
 
                         ##
@@ -126,20 +168,6 @@ module ConvenientService
                         def to_sym
                           @to_sym ||= value.to_sym
                         end
-
-                        ##
-                        # @return [Boolean, nil]
-                        #
-                        def to_bool
-                          return @to_bool if defined? @to_bool
-
-                          @to_bool =
-                            case value
-                            when :success then true
-                            when :failure then false
-                            when :error then nil
-                            end
-                        end
                       end
                     end
                   end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/entities/status/plugins/can_be_checked/concern.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResult
+        module Entities
+          class Result
+            module Plugins
+              module HasJSendStatusAndAttributes
+                module Entities
+                  class Status
+                    module Plugins
+                      module CanBeChecked
+                        module Concern
+                          include Support::Concern
+
+                          instance_methods do
+                            ##
+                            # @return [Boolean]
+                            #
+                            def checked?
+                              Utils.to_bool(internals.cache[:checked])
+                            end
+                          end
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/entities/status/plugins/can_be_checked/middleware.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResult
+        module Entities
+          class Result
+            module Plugins
+              module HasJSendStatusAndAttributes
+                module Entities
+                  class Status
+                    module Plugins
+                      module CanBeChecked
+                        class Middleware < MethodChainMiddleware
+                          intended_for [
+                            :success?,
+                            :failure?,
+                            :error?,
+                            :not_success?,
+                            :not_failure?,
+                            :not_error?
+                          ],
+                            entity: :result
+
+                          ##
+                          # @param args [Array<Object>]
+                          # @param kwargs [Hash{Symbol => Object}]
+                          # @param block [Proc, nil]
+                          # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                          #
+                          def next(*args, **kwargs, &block)
+                            mark_as_checked = kwargs.fetch(:mark_as_checked) { true }
+
+                            entity.internals.cache[:checked] = true if mark_as_checked
+
+                            chain.next(*args, **Utils::Hash.except(kwargs, [:mark_as_checked]), &block)
+                          end
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/entities/status/plugins/can_be_checked.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "can_be_checked/concern"
+require_relative "can_be_checked/middleware"

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/entities/status/plugins.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "plugins/can_be_checked"
 require_relative "plugins/has_inspect"
 
 require_relative "plugins/aliases"

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/exceptions.rb

@@ -22,6 +22,21 @@ module ConvenientService
                       initialize(message)
                     end
                   end
+
+                  class ErrorHasNoOtherTypeRepresentation < ::ConvenientService::Exception
+                    ##
+                    # @return [void]
+                    #
+                    def initialize_with_kwargs(type:)
+                      message = <<~TEXT
+                        Error results have no `#{type}` representation.
+
+                        They are semantically similar to exceptions.
+                      TEXT
+
+                      initialize(message)
+                    end
+                  end
                 end
               end
             end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_negated_result/concern.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResult
+        module Entities
+          class Result
+            module Plugins
+              module HasNegatedResult
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    ##
+                    # @return [Boolean]
+                    #
+                    def negated?
+                      Utils.to_bool(extra_kwargs[:negated])
+                    end
+
+                    ##
+                    # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                    #
+                    # @internal
+                    #   NOTE: `original_result = result` is used to cache `result` independently, without relying on `CachesReturnValue` plugin.
+                    #
+                    #   TODO: `Utils::String.concat_if`? How?
+                    #   - https://stackoverflow.com/a/28648594/12201472
+                    #
+                    #   IMPORTNANT: `copy` is used instead of `service.success`, or `service.failure` in order to reuse the original result extra kwargs, like `step`, `parent`, etc.
+                    #
+                    #   TODO: A simple way to get constant without referencing other plugin.
+                    #
+                    def negated_result
+                      case status.to_sym
+                      when :success
+                        copy(
+                          overrides: {
+                            kwargs: {
+                              status: :failure,
+                              data: unsafe_data,
+                              message: "Original `result` is `success`#{" with `message` - #{unsafe_message}" unless unsafe_message.empty?}",
+                              code: "negated_#{unsafe_code}"
+                            }
+                          }
+                        )
+                      when :failure
+                        copy(
+                          overrides: {
+                            kwargs: {
+                              status: :success,
+                              data: unsafe_data,
+                              message: "Original `result` is `failure`#{" with `message` - #{unsafe_message}" unless unsafe_message.empty?}",
+                              code: "negated_#{unsafe_code}"
+                            }
+                          }
+                        )
+                      when :error
+                        copy
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_negated_result.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "has_negated_result/concern"

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/raises_on_not_checked_result_status/middleware.rb

@@ -32,7 +32,7 @@ module ConvenientService
                   # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::RaisesOnNotCheckedResultStatus::Exceptions::StatusIsNotChecked]
                   #
                   def assert_has_checked_status!
-                    return if entity.internals.cache.exist?(:has_checked_status)
+                    return if entity.checked?
 
                     ::ConvenientService.raise Exceptions::StatusIsNotChecked.new(attribute: method)
                   end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "plugins/can_recalculate_result"
+require_relative "plugins/has_negated_result"
 require_relative "plugins/can_be_own_result"
 require_relative "plugins/can_be_stubbed_result"
 require_relative "plugins/can_have_fallbacks"

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

@@ -5,7 +5,6 @@ require_relative "has_j_send_result/constants"
 require_relative "has_j_send_result/container"
 require_relative "has_j_send_result/commands"
 require_relative "has_j_send_result/entities"
-require_relative "has_j_send_result/exceptions"
 
 module ConvenientService
   module Service

data/lib/convenient_service/service/plugins/has_j_send_result_params_validations/using_dry_validation/middleware.rb

@@ -4,6 +4,10 @@ module ConvenientService
   module Service
     module Plugins
       module HasJSendResultParamsValidations
+        ##
+        # @internal
+        #   TODO: Consider to add versioning, since `dry` gems often modify thier public API.
+        #
         module UsingDryValidation
           class Middleware < MethodChainMiddleware
             intended_for :result, entity: :service

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasNegatedJSendResult
+        module Concern
+          include Support::Concern
+
+          instance_methods do
+            ##
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            # @note Users may override this method to provide custom `negataed_result` behavior.
+            #
+            def negated_result
+              result.negated_result
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "has_negated_j_send_result/concern"

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasNegatedResult
+        module Concern
+          include Support::Concern
+
+          class_methods do
+            ##
+            # @api public
+            # @raise [ConvenientService::Service::Plugins::HasNegatedResult::Exceptions::NegatedResultIsNotOverridden]
+            #
+            def negated_result(...)
+              new(...).negated_result
+            end
+          end
+
+          instance_methods do
+            ##
+            # @api public
+            # @raise [ConvenientService::Service::Plugins::HasNegatedResult::Exceptions::NegatedResultIsNotOverridden]
+            #
+            def negated_result
+              ::ConvenientService.raise Exceptions::NegatedResultIsNotOverridden.new(service: self)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/{has_j_send_result → has_negated_result}/exceptions.rb

@@ -3,12 +3,12 @@
 module ConvenientService
   module Service
     module Plugins
-      module HasJSendResult
+      module HasNegatedResult
         module Exceptions
-          class ResultIsNotOverridden < ::ConvenientService::Exception
+          class NegatedResultIsNotOverridden < ::ConvenientService::Exception
             def initialize_with_kwargs(service:)
               message = <<~TEXT
-                Result method (#result) of `#{service.class}` is NOT overridden.
+                Negated result method (#negated_result) of `#{service.class}` is NOT overridden.
               TEXT
 
               initialize(message)

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

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "has_negated_result/concern"
+require_relative "has_negated_result/exceptions"

data/lib/convenient_service/service/plugins/{wraps_result_in_db_transaction → wraps_result_in_d_b_transaction}/middleware.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Service
     module Plugins
-      module WrapsResultInDbTransaction
+      module WrapsResultInDBTransaction
         class Middleware < MethodChainMiddleware
           intended_for :result, scope: :class, entity: :service