convenient_service 0.16.0 → 0.17.0

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

@@ -126,6 +126,20 @@ 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/exceptions.rb

@@ -14,12 +14,12 @@ module ConvenientService
                     # @param attribute [Symbol]
                     # @return [void]
                     #
-                    def initialize(attribute:)
+                    def initialize_with_kwargs(attribute:)
                       message = <<~TEXT
                         Data attribute `#{attribute}` does NOT exist. Make sure the corresponding result returns it.
                       TEXT
 
-                      super(message)
+                      initialize(message)
                     end
                   end
                 end

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

@@ -10,14 +10,14 @@ module ConvenientService
               module RaisesOnNotCheckedResultStatus
                 module Exceptions
                   class StatusIsNotChecked < ::ConvenientService::Exception
-                    def initialize(attribute:)
+                    def initialize_with_kwargs(attribute:)
                       message = <<~TEXT
                         Attribute `#{attribute}` is accessed before result status is checked.
 
                         Did you forget to call `success?`, `failure?`, or `error?` on result?
                       TEXT
 
-                      super(message)
+                      initialize(message)
                     end
                   end
                 end

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

@@ -34,7 +34,7 @@ module ConvenientService
                   def assert_has_checked_status!
                     return if entity.internals.cache.exist?(:has_checked_status)
 
-                    raise Exceptions::StatusIsNotChecked.new(attribute: method)
+                    ::ConvenientService.raise Exceptions::StatusIsNotChecked.new(attribute: method)
                   end
                 end
               end

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

@@ -6,12 +6,12 @@ module ConvenientService
       module HasJSendResult
         module Exceptions
           class ResultIsNotOverridden < ::ConvenientService::Exception
-            def initialize(service:)
+            def initialize_with_kwargs(service:)
               message = <<~TEXT
                 Result method (#result) of `#{service.class}` is NOT overridden.
               TEXT
 
-              super(message)
+              initialize(message)
             end
           end
         end

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

@@ -6,3 +6,42 @@ 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
+    module Plugins
+      module HasJSendResult
+        class << self
+          ##
+          # Checks whether an object is a result instance.
+          #
+          # @api public
+          #
+          # @param result [Object] Can be any type.
+          # @return [Boolean]
+          #
+          # @example Simple usage.
+          #   class Service
+          #     include ConvenientService::Standard::Config
+          #
+          #     def result
+          #       success
+          #     end
+          #   end
+          #
+          #   result = Service.result
+          #
+          #   ConvenientService::Plugins::Service::HasJSendResult.result?(result)
+          #   # => true
+          #
+          #   ConvenientService::Plugins::Service::HasJSendResult.result?(42)
+          #   # => false
+          #
+          def result?(result)
+            Commands::IsResult[result: result]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/error/exceptions.rb

@@ -10,7 +10,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   Both `args` and `kwargs` are passed to the `error` method.
 
@@ -23,7 +23,7 @@ module ConvenientService
                   error(message: "Helpful text", code: :descriptive_code)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
 
@@ -31,7 +31,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   `kwargs` passed to `error` method contain JSend keys and extra keys. That's NOT allowed.
 
@@ -61,12 +61,12 @@ module ConvenientService
                   error(data: {foo: :bar}, message: "foo", code: :foo)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
 
             class MoreThanTwoArgsArePassed < ::ConvenientService::Exception
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   More than two `args` are passed to the `error` method.
 
@@ -76,7 +76,7 @@ module ConvenientService
                   error("Helpful text", :descriptive_code)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
           end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/error/middleware.rb

@@ -15,7 +15,7 @@ module ConvenientService
             # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
             #
             def next(*args, **kwargs, &block)
-              raise Exceptions::BothArgsAndKwargsArePassed.new if args.any? && kwargs.any?
+              ::ConvenientService.raise Exceptions::BothArgsAndKwargsArePassed.new if args.any? && kwargs.any?
 
               args.any? ? error_from_args : error_from_kwargs
             end
@@ -31,7 +31,7 @@ module ConvenientService
               when 1 then chain.next(message: next_arguments.args[0])
               when 2 then chain.next(message: next_arguments.args[0], code: next_arguments.args[1])
               else
-                raise Exceptions::MoreThanTwoArgsArePassed.new
+                ::ConvenientService.raise Exceptions::MoreThanTwoArgsArePassed.new
               end
             end
 
@@ -44,7 +44,7 @@ module ConvenientService
             def error_from_kwargs
               return chain.next(data: next_arguments.kwargs) if [:data, :message, :code].none? { |key| next_arguments.kwargs.has_key?(key) }
 
-              raise Exceptions::KwargsContainJSendAndExtraKeys.new if next_arguments.kwargs.keys.difference([:data, :message, :code]).any?
+              ::ConvenientService.raise Exceptions::KwargsContainJSendAndExtraKeys.new if next_arguments.kwargs.keys.difference([:data, :message, :code]).any?
 
               chain.next(**next_arguments.kwargs)
             end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/failure/exceptions.rb

@@ -10,7 +10,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   `kwargs` passed to `failure` method contain JSend keys and extra keys. That's NOT allowed.
 
@@ -40,7 +40,7 @@ module ConvenientService
                   failure(data: {foo: :bar}, message: "foo", code: :foo)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
 
@@ -48,7 +48,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   Both `args` and `kwargs` are passed to the `failure` method.
 
@@ -61,7 +61,7 @@ module ConvenientService
                   failure(message: "Helpful text", code: :descriptive_code)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
 
@@ -69,7 +69,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   More than two `args` are passed to the `failure` method.
 
@@ -79,7 +79,7 @@ module ConvenientService
                   failure("Helpful text", :descriptive_code)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
           end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/failure/middleware.rb

@@ -15,7 +15,7 @@ module ConvenientService
             # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
             #
             def next(*args, **kwargs, &block)
-              raise Exceptions::BothArgsAndKwargsArePassed.new if args.any? && kwargs.any?
+              ::ConvenientService.raise Exceptions::BothArgsAndKwargsArePassed.new if args.any? && kwargs.any?
 
               args.any? ? failure_from_args : failure_from_kwargs
             end
@@ -31,7 +31,7 @@ module ConvenientService
               when 1 then chain.next(message: next_arguments.args[0])
               when 2 then chain.next(message: next_arguments.args[0], code: next_arguments.args[1])
               else
-                raise Exceptions::MoreThanTwoArgsArePassed.new
+                ::ConvenientService.raise Exceptions::MoreThanTwoArgsArePassed.new
               end
             end
 
@@ -44,7 +44,7 @@ module ConvenientService
             def failure_from_kwargs
               return chain.next(data: next_arguments.kwargs) if [:data, :message, :code].none? { |key| next_arguments.kwargs.has_key?(key) }
 
-              raise Exceptions::KwargsContainJSendAndExtraKeys.new if next_arguments.kwargs.keys.difference([:data, :message, :code]).any?
+              ::ConvenientService.raise Exceptions::KwargsContainJSendAndExtraKeys.new if next_arguments.kwargs.keys.difference([:data, :message, :code]).any?
 
               chain.next(**next_arguments.kwargs)
             end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/success/commands/refute_kwargs_contain_j_send_and_extra_keys.rb

@@ -56,7 +56,7 @@ module ConvenientService
 
                 return if kwargs.keys.difference([:data, :message, :code]).none?
 
-                raise Exceptions::KwargsContainJSendAndExtraKeys.new
+                ::ConvenientService.raise Exceptions::KwargsContainJSendAndExtraKeys.new
               end
             end
           end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/success/exceptions.rb

@@ -10,7 +10,7 @@ module ConvenientService
               ##
               # @return [void]
               #
-              def initialize
+              def initialize_without_arguments
                 message = <<~TEXT
                   `kwargs` passed to `success` method contain JSend keys and extra keys. That's NOT allowed.
 
@@ -30,7 +30,7 @@ module ConvenientService
                   success(code: :foo)
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
           end

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

@@ -10,7 +10,6 @@ module ConvenientService
           class_methods do
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def success?(...)
               result(...).success?
@@ -18,7 +17,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def error?(...)
               result(...).error?
@@ -26,7 +24,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def failure?(...)
               result(...).failure?
@@ -34,7 +31,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def not_success?(...)
               result(...).not_success?
@@ -42,7 +38,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def not_error?(...)
               result(...).not_error?
@@ -50,7 +45,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.2.0
             #
             def not_failure?(...)
               result(...).not_failure?
@@ -58,7 +52,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.12.0
             #
             def ok?(...)
               result(...).success?
@@ -66,7 +59,6 @@ module ConvenientService
 
             ##
             # @return [Boolean]
-            # @since 0.12.0
             #
             def not_ok?(...)
               result(...).not_success?

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

@@ -23,7 +23,7 @@ module ConvenientService
             # @raise [ConvenientService::Service::Plugins::HasResult::Exceptions::ResultIsNotOverridden]
             #
             def result
-              raise Exceptions::ResultIsNotOverridden.new(service: self)
+              ::ConvenientService.raise Exceptions::ResultIsNotOverridden.new(service: self)
             end
           end
         end

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

@@ -6,12 +6,12 @@ module ConvenientService
       module HasResult
         module Exceptions
           class ResultIsNotOverridden < ::ConvenientService::Exception
-            def initialize(service:)
+            def initialize_with_kwargs(service:)
               message = <<~TEXT
                 Result method (#result) of `#{service.class}` is NOT overridden.
               TEXT
 
-              super(message)
+              initialize(message)
             end
           end
         end

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

@@ -6,7 +6,7 @@ module ConvenientService
       module RaisesOnDoubleResult
         module Exceptions
           class DoubleResult < ::ConvenientService::Exception
-            def initialize(service:)
+            def initialize_with_kwargs(service:)
               message = <<~TEXT
                 `#{service.class}` service has a double result.
 
@@ -24,7 +24,7 @@ module ConvenientService
                 end
               TEXT
 
-              super(message)
+              initialize(message)
             end
           end
         end

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

@@ -48,7 +48,7 @@ module ConvenientService
           def refute_has_j_send_result!
             return unless entity.internals.cache.exist?(:has_j_send_result)
 
-            raise Exceptions::DoubleResult.new(service: entity)
+            ::ConvenientService.raise Exceptions::DoubleResult.new(service: entity)
           end
 
           ##

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

@@ -6,7 +6,7 @@ module ConvenientService
       module RaisesOnNotResultReturnValue
         module Exceptions
           class ReturnValueNotKindOfResult < ::ConvenientService::Exception
-            def initialize(service:, result:, method:)
+            def initialize_with_kwargs(service:, result:, method:)
               message = <<~TEXT
                 Return value of service `#{service.class}` is NOT a `Result`.
                 It is `#{result.class}`.
@@ -14,7 +14,7 @@ module ConvenientService
                 Did you forget to call `success`, `failure`, or `error` from the `:#{method}` method?
               TEXT
 
-              super(message)
+              initialize(message)
             end
           end
         end

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

@@ -16,7 +16,7 @@ module ConvenientService
 
             return original_result if commands.is_result?(original_result)
 
-            raise Exceptions::ReturnValueNotKindOfResult.new(service: entity, result: original_result, method: method)
+            ::ConvenientService.raise Exceptions::ReturnValueNotKindOfResult.new(service: entity, result: original_result, method: method)
           end
         end
       end

data/lib/convenient_service/support/abstract_method/exceptions.rb

@@ -5,7 +5,7 @@ module ConvenientService
     module AbstractMethod
       module Exceptions
         class AbstractMethodNotOverridden < ::ConvenientService::Exception
-          def initialize(instance:, method:)
+          def initialize_with_kwargs(instance:, method:)
             klass = instance.is_a?(::Class) ? instance : instance.class
             method_type = Utils::Object.resolve_type(instance)
 
@@ -13,7 +13,7 @@ module ConvenientService
               `#{klass}` should implement abstract #{method_type} method `#{method}`.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
       end

data/lib/convenient_service/support/abstract_method.rb

@@ -11,7 +11,7 @@ module ConvenientService
         def abstract_method(*names)
           names.each do |name|
             define_method(name) do |*args, **kwargs, &block|
-              raise Exceptions::AbstractMethodNotOverridden.new(instance: self, method: name)
+              ::ConvenientService.raise Exceptions::AbstractMethodNotOverridden.new(instance: self, method: name)
             end
           end
         end

data/lib/convenient_service/support/backtrace_cleaner.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+##
+# @note Other gems are also trying to integrate with Rails Backtrace Cleaner.
+# @see https://github.com/sidekiq/sidekiq/pull/5796
+# @see https://github.com/sidekiq/sidekiq/issues/5589
+# @see https://github.com/appsignal/appsignal-ruby/issues/380
+#
+module ConvenientService
+  module Support
+    ##
+    # Rails v7.1.2 Backtrace Cleaner descendant.
+    # Has Convenient Service specific silencer - `add_convenient_service_silencer`.
+    # By default, it uses only `add_stdlib_silencer` and `add_convenient_service_silencer`.
+    #
+    # @see https://api.rubyonrails.org/classes/ActiveSupport/BacktraceCleaner.html
+    # @see https://medium.com/one-medical-technology/filtering-ruby-backtraces-for-debugging-4df75133ab71
+    # @see https://twitter.com/websebdev/status/1375831554518360065?ref_src=twsrc%5Etfw%7Ctwcamp%5Etweetembed%7Ctwterm%5E1375831554518360065%7Ctwgr%5E459595174e71c0f1aa3826c89f2ffca0c3da6ea3%7Ctwcon%5Es1_&ref_url=https%3A%2F%2Fwww.redditmedia.com%2Fmediaembed%2Fmegii9%2F%3Fresponsive%3Dtrueis_nightmode%3Dtrue
+    # @see https://stackoverflow.com/questions/22727219/using-backtracecleaner-in-rails-console
+    #
+    class BacktraceCleaner < Dependencies::Extractions::ActiveSupportBacktraceCleaner::BacktraceCleaner
+      ##
+      # @return [void]
+      #
+      # @note `ConvenientService::Support::BacktraceCleaner` intentionally does NOT exclude external gems lines from backtrace.
+      #
+      # @see https://api.rubyonrails.org/classes/ActiveSupport/BacktraceCleaner.html
+      # @see https://github.com/rails/rails/blob/v7.1.2/activesupport/lib/active_support/backtrace_cleaner.rb#L34
+      #
+      # @internal
+      #   IMPORTANT: Convenient Service integrates with external gems.
+      #   This means that external gems exceptions should NOT be considered as Convenient Service internal exceptions.
+      #
+      def initialize(...)
+        super
+
+        remove_filters!
+        remove_silencers!
+
+        ##
+        # NOTE: Uses `::RbConfig` to resolve stdlib directory.
+        # - https://idiosyncratic-ruby.com/42-ruby-config.html
+        # - https://github.com/ruby/ruby/blob/master/tool/mkconfig.rb
+        #
+        add_stdlib_silencer
+
+        ##
+        # NOTE:
+        #
+        add_convenient_service_silencer
+      end
+
+      ##
+      # @note `add_gem_filter` is made public to have a way to bring back Rails Backtrace Cleaner default behavior if necessary.
+      #
+      # @return [void]
+      #
+      # @see https://github.com/rails/rails/blob/v7.1.2/activesupport/lib/active_support/backtrace_cleaner.rb#L110
+      #
+      public :add_gem_filter
+
+      ##
+      # @note `add_gem_silencer` is made public to have a way to bring back Rails Backtrace Cleaner default behavior if necessary.
+      #
+      # @return [void]
+      #
+      # @see https://github.com/rails/rails/blob/v7.1.2/activesupport/lib/active_support/backtrace_cleaner.rb#L119
+      #
+      public :add_gem_silencer
+
+      ##
+      # @note `add_stdlib_silencer` is made public to allow the end-user to adjust clean in any way.
+      #
+      # @return [void]
+      #
+      # @see https://github.com/rails/rails/blob/v7.1.2/activesupport/lib/active_support/backtrace_cleaner.rb#L123
+      #
+      public :add_stdlib_silencer
+
+      ##
+      # Since Convenient Service is using middleware chains under the hood, exception backtraces may be huge.
+      # As a consequence, it takes too much time during the debugging process to find the application line of code that causes the exception.
+      # This silencer removes all Convenient Service lines from backtraces.
+      #
+      # @note To bring back Convenient Service lines to backtraces, use the `remove_silencers` or check the `CleansExceptionBacktrace` plugin.
+      #
+      # @return [void]
+      #
+      def add_convenient_service_silencer
+        add_silencer { |line| line.start_with?(::ConvenientService.root.to_s) && !line.start_with?(::ConvenientService.examples_root.to_s) }
+      end
+
+      ##
+      # Works exactly in the same way as the original `clean`, except it falls back to the original backtrace in case of any exceptions inside filters or silencers.
+      # Also returns an empty array, when `backtrace` is `nil`.
+      #
+      # @return [Array<String>]
+      #
+      # @see https://api.rubyonrails.org/classes/ActiveSupport/BacktraceCleaner.html#method-i-clean
+      #
+      # @internal
+      #   IMPORTANT: Sometimes `exception.backtrace` can be `nil`.
+      #   - https://blog.kalina.tech/2019/04/exception-without-backtrace-in-ruby.html
+      #   - https://github.com/jruby/jruby/issues/4467
+      #
+      def clean(backtrace, *args)
+        if backtrace.nil?
+          ::ConvenientService.logger.warn { "[BacktraceCleaner] `nil` backtrace | Empty array is used as fallback" }
+
+          return []
+        end
+
+        begin
+          super
+        rescue
+          ::ConvenientService.logger.warn { "[BacktraceCleaner] Some filter or silencer is broken | Original backtrace is used as fallback" }
+
+          backtrace
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/cache/exceptions.rb

@@ -9,14 +9,14 @@ module ConvenientService
           # @param backend [Symbol]
           # @return [void]
           #
-          def initialize(backend:)
+          def initialize_with_kwargs(backend:)
             message = <<~TEXT
               Backend `#{backend}` is NOT supported.
 
               Supported backends are #{printable_backends}.
             TEXT
 
-            super(message)
+            initialize(message)
           end
 
           private

data/lib/convenient_service/support/cache.rb

@@ -21,7 +21,7 @@ module ConvenientService
           when Constants::Backends::THREAD_SAFE_ARRAY
             Entities::Caches::ThreadSafeArray.new
           else
-            raise Exceptions::NotSupportedBackend.new(backend: backend)
+            ::ConvenientService.raise Exceptions::NotSupportedBackend.new(backend: backend)
           end
         end
       end

data/lib/convenient_service/support/castable/exceptions.rb

@@ -5,22 +5,22 @@ module ConvenientService
     module Castable
       module Exceptions
         class CastIsNotOverridden < ::ConvenientService::Exception
-          def initialize(klass:)
+          def initialize_with_kwargs(klass:)
             message = <<~TEXT
               Cast method (.cast) of `#{klass}` is NOT overridden.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
 
         class FailedToCast < ::ConvenientService::Exception
-          def initialize(other:, klass:)
+          def initialize_with_kwargs(other:, klass:)
             message = <<~TEXT
               Failed to cast `#{other.inspect}` into `#{klass}`.
             TEXT
 
-            super(message)
+            initialize(message)
           end
         end
       end