convenient_service 0.16.0 → 0.17.0

data/lib/convenient_service/dependencies/extractions/active_support_backtrace_cleaner/backtrace_cleaner.rb

@@ -7,15 +7,17 @@ module ConvenientService
       # @internal
       #   NOTE:
       #     Copied from `rails/rails` without any logic modification.
-      #     Version: v7.0.4.3.
+      #     Version: v7.1.2.
       #     Wrapped in a namespace `ConvenientService::Dependencies::Extractions::ActiveSupportBacktraceCleaner`.
       #
-      #   - https://api.rubyonrails.org/v7.0.4.3/classes/ActiveSupport/BacktraceCleaner.html
-      #   - https://github.com/rails/rails/blob/v7.0.4.3/activesupport/lib/active_support/backtrace_cleaner.rb
+      #   - https://api.rubyonrails.org/v7.1.2/classes/ActiveSupport/BacktraceCleaner.html
+      #   - https://github.com/rails/rails/blob/v7.1.2/activesupport/lib/active_support/backtrace_cleaner.rb
       #   - https://github.com/marian13/rails/blob/main/activesupport/lib/active_support/backtrace_cleaner.rb
       #   - https://github.com/rails/rails
       #
       module ActiveSupportBacktraceCleaner
+        # = Backtrace Cleaner
+        #
         # Backtraces often include many lines that are not relevant for the context
         # under review. This makes it hard to find the signal amongst the backtrace
         # noise, and adds debugging time. With a BacktraceCleaner, filters and
@@ -34,7 +36,7 @@ module ConvenientService
         #   bc.add_silencer { |line| /puma|rubygems/.match?(line) } # skip any lines from puma or rubygems
         #   bc.clean(exception.backtrace) # perform the cleanup
         #
-        # To reconfigure an existing BacktraceCleaner (like the default one in Rails)
+        # To reconfigure an existing BacktraceCleaner (like the default one in \Rails)
         # and show as much data as possible, you can always call
         # BacktraceCleaner#remove_silencers!, which will restore the
         # backtrace to a pristine state. If you need to reconfigure an existing
@@ -67,11 +69,29 @@ module ConvenientService
           end
           alias :filter :clean
 
+          # Returns the frame with all filters applied.
+          # returns +nil+ if the frame was silenced.
+          def clean_frame(frame, kind = :silent)
+            frame = frame.to_s
+            @filters.each do |f|
+              frame = f.call(frame.to_s)
+            end
+
+            case kind
+            when :silent
+              frame unless @silencers.any? { |s| s.call(frame) }
+            when :noise
+              frame if @silencers.any? { |s| s.call(frame) }
+            else
+              frame
+            end
+          end
+
           # Adds a filter from the block provided. Each line in the backtrace will be
           # mapped against this filter.
           #
           #   # Will turn "/my/rails/root/app/models/person.rb" into "/app/models/person.rb"
-          #   backtrace_cleaner.add_filter { |line| line.gsub(Rails.root, '') }
+          #   backtrace_cleaner.add_filter { |line| line.gsub(Rails.root.to_s, '') }
           def add_filter(&block)
             @filters << block
           end
@@ -121,7 +141,7 @@ module ConvenientService
 
             def filter_backtrace(backtrace)
               @filters.each do |f|
-                backtrace = backtrace.map { |line| f.call(line) }
+                backtrace = backtrace.map { |line| f.call(line.to_s) }
               end
 
               backtrace
@@ -129,7 +149,7 @@ module ConvenientService
 
             def silence(backtrace)
               @silencers.each do |s|
-                backtrace = backtrace.reject { |line| s.call(line) }
+                backtrace = backtrace.reject { |line| s.call(line.to_s) }
               end
 
               backtrace
@@ -138,7 +158,7 @@ module ConvenientService
             def noise(backtrace)
               backtrace.select do |line|
                 @silencers.any? do |s|
-                  s.call(line)
+                  s.call(line.to_s)
                 end
               end
             end

data/lib/convenient_service/dependencies/extractions/active_support_backtrace_cleaner.rb

@@ -4,11 +4,11 @@
 # @internal
 #   NOTE:
 #     Copied from `rails/rails` without any logic modification.
-#     Version: v7.0.4.3.
+#     Version: v7.1.2.
 #     Wrapped in a namespace `ConvenientService::Dependencies::Extractions::ActiveSupportBacktraceCleaner`.
 #
-#   - https://api.rubyonrails.org/v7.0.4.3/classes/ActiveSupport/BacktraceCleaner.html
-#   - https://github.com/rails/rails/blob/v7.0.4.3/activesupport/lib/active_support/backtrace_cleaner.rb
+#   - https://api.rubyonrails.org/v7.1.2/classes/ActiveSupport/BacktraceCleaner.html
+#   - https://github.com/rails/rails/blob/v7.1.2/activesupport/lib/active_support/backtrace_cleaner.rb
 #   - https://github.com/marian13/rails/blob/main/activesupport/lib/active_support/backtrace_cleaner.rb
 #   - https://github.com/rails/rails
 #

data/lib/convenient_service/dependencies/extractions/b.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 ##
 # Works in a similar way as `p`, but for `byebug`.
 # @see https://ruby-doc.org/core-2.7.0/Kernel.html#method-i-p

data/lib/convenient_service/dependencies/extractions/ce.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+##
+# @note `ce` is short for `catch_exception`.
+#
+# @example
+#   ce { some_code }
+#   e = ce { some_code }
+#
+def ce
+  yield
+
+  nil
+rescue => exception
+  exception
+end

data/lib/convenient_service/dependencies/extractions.rb

@@ -7,4 +7,5 @@
 #   https://github.com/marian13/convenient_service/wiki/Docs:-Dependencies
 #
 require_relative "extractions/active_support_concern"
+require_relative "extractions/active_support_backtrace_cleaner"
 require_relative "extractions/ruby_middleware"

data/lib/convenient_service/dependencies.rb

@@ -135,7 +135,7 @@ module ConvenientService
       # @return [Boolean]
       # @note Expected to be called from app entry points like `initializers` in Rails.
       #
-      # @see https://marian13.github.io/convenient_service_docs/troubleshooting/i18n_translate_wrong_number_of_arguments
+      # @see https://userdocs.convenientservice.org/troubleshooting/i18n_translate_wrong_number_of_arguments
       #
       def require_has_j_send_result_params_validations_using_active_model_validations
         ##
@@ -244,6 +244,11 @@ module ConvenientService
         require_relative "dependencies/extractions/byebug_syntax_highlighting" unless ruby.jruby?
 
         require_relative "dependencies/extractions/b" unless ruby.jruby?
+
+        ##
+        #
+        #
+        require_relative "dependencies/extractions/ce"
       end
 
       ##

data/lib/convenient_service/examples/standard/request_params.rb

@@ -6,7 +6,6 @@ require_relative "request_params/services"
 require_relative "request_params/utils"
 
 ##
-# @since 0.3.0
 #
 # @internal
 #   Usage example:

data/lib/convenient_service/examples/standard/v1/request_params.rb

@@ -6,7 +6,6 @@ require_relative "request_params/services"
 require_relative "request_params/utils"
 
 ##
-# @since 0.3.0
 #
 # @internal
 #   Usage example:

data/lib/convenient_service/exception.rb

@@ -1,16 +1,104 @@
 # frozen_string_literal: true
 
-##
-# Base class for all `ConvenientService` exceptions.
-# Can be used as a catch-all solution, for example:
-#
-#   begin
-#     any_service.result
-#   rescue ConvenientService::Exception => exception
-#     puts exception.message
-#   end
-#
 module ConvenientService
+  ##
+  # Base class for all `ConvenientService` exceptions.
+  #
+  # @example Can be used as a catch-all solution.
+  #
+  #   begin
+  #     any_service.result
+  #   rescue ConvenientService::Exception => exception
+  #     puts exception.message
+  #   end
+  #
   class Exception < ::StandardError
+    class << self
+      ##
+      # Creates `ConvenientService` exception instance.
+      # In contract to `StandardError.new`, may accept `kwargs`.
+      # In such a case the descendant must implement `initialize_with_kwargs` to specify the logic of how to generate a `message`.
+      # Without arguments behavior is also changed, it calls `initialize_without_arguments` instead of immediately setting `nil` as `message`.
+      #
+      # @note `initialize_with_kwargs` or `initialize_without_arguments` must call `initialize(message)`, otherwise exception instance won't be properly set up.
+      #
+      # @overload new
+      #   Calls `initialize_without_arguments` under the hood to generate the exception message.
+      #
+      #   @api private
+      #
+      #   @return [ConvenientService::Exception]
+      #
+      #   @example Usage.
+      #     module Exceptions
+      #       class Foo < ::ConvenientService::Exception
+      #         def initialize_without_arguments
+      #           # message = ...
+      #           initialize(message)
+      #         end
+      #       end
+      #     end
+      #
+      #     ::ConvenientService.raise Foo.new
+      #
+      # @overload new(message)
+      #   Calls `initialize(message)` under the hood to set the exception message.
+      #
+      #   @api private
+      #
+      #   @param message [String]
+      #
+      #   @return [ConvenientService::Exception]
+      #
+      #   @example Usage.
+      #     module Exceptions
+      #       class Foo < ::ConvenientService::Exception
+      #       end
+      #     end
+      #
+      #     ::ConvenientService.raise Foo.new("some message")
+      #
+      # @overload new(**kwargs)
+      #   Calls `initialize_with_kwargs(**kwargs)` under the hood to generate the exception message.
+      #
+      #   @api private
+      #
+      #   @param kwargs [Hash{Symbol => Object}]
+      #   @return [ConvenientService::Exception]
+      #
+      #   @example Usage.
+      #     module Exceptions
+      #       class Foo < ::ConvenientService::Exception
+      #         def initialize_with_kwargs(**kwargs)
+      #           # message = ...
+      #           initialize(message)
+      #         end
+      #       end
+      #     end
+      #
+      #     ::ConvenientService.raise Foo.new(foo: :bar, baz: :qux)
+      #
+      def new(message = nil, **kwargs)
+        if message
+          super(message)
+        elsif kwargs.any?
+          allocate.tap { |exception| exception.initialize_with_kwargs(**kwargs) }
+        else
+          allocate.tap(&:initialize_without_arguments)
+        end
+      end
+    end
+
+    ##
+    # @internal
+    #   NOTE: Two exceptions are equal when their classes, messages, and backtraces are equal.
+    #   - https://blog.arkency.com/2015/01/ruby-exceptions-equality
+    #
+    #   TODO: Compare skipping backtraces? Why?
+    #
+    # def ==(other)
+    #   # ...
+    # end
+    ##
   end
 end

data/lib/convenient_service/feature/configs/standard.rb

@@ -14,6 +14,14 @@ module ConvenientService
 
           concerns do
             use ConvenientService::Plugins::Feature::CanHaveEntries::Concern
+
+            use ConvenientService::Plugins::Common::HasInstanceProxy::Concern
+          end
+
+          middlewares :new, scope: :class do
+            use ConvenientService::Plugins::Common::NormalizesEnv::Middleware
+
+            use ConvenientService::Plugins::Common::HasInstanceProxy::Middleware
           end
         end
       end

data/lib/convenient_service/feature/plugins/can_have_entries/commands/define_entries.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Feature
+    module Plugins
+      module CanHaveEntries
+        module Commands
+          class DefineEntries < Support::Command
+            ##
+            # @!attribute [r] feature_class
+            #   @return [Class]
+            #
+            attr_reader :feature_class
+
+            ##
+            # @!attribute [r] names
+            #   @return [Array<String, Symbol>]
+            #
+            attr_reader :names
+
+            ##
+            # @!attribute [r] body
+            #   @return [Proc, nil]
+            #
+            attr_reader :body
+
+            ##
+            # @param feature_class [Class]
+            # @param names [Array<String, Symbol>]
+            # @param body [Proc, nil]
+            #
+            def initialize(feature_class:, names:, body:)
+              @feature_class = feature_class
+              @names = names
+              @body = body
+            end
+
+            ##
+            # @return [Array<String, Symbol>]
+            #
+            def call
+              names.map { |name| Commands::DefineEntry.call(feature_class: feature_class, name: name, body: body) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/feature/plugins/can_have_entries/commands/define_entry.rb

@@ -20,14 +20,14 @@ module ConvenientService
 
             ##
             # @!attribute [r] body
-            #   @return [Proc]
+            #   @return [Proc, nil]
             #
             attr_reader :body
 
             ##
             # @param feature_class [Class]
             # @param name [String, Symbol]
-            # @param body [Proc]
+            # @param body [Proc, nil]
             #
             def initialize(feature_class:, name:, body:)
               @feature_class = feature_class
@@ -44,13 +44,27 @@ module ConvenientService
               # That is why `feature_class.class_exec` wrapper is required.
               #
               feature_class.class_exec(name) do |name|
-                define_singleton_method(name) { |*args, **kwargs, &block| new.public_send(name, *args, **kwargs, &block) }
+                define_singleton_method(name) { |*args, **kwargs, &block| new.entry(name, *args, **kwargs, &block) }
               end
 
               if body
                 feature_class.define_method(name, &body)
               else
-                feature_class.define_method(name) { raise ::ConvenientService::Feature::Plugins::CanHaveEntries::Exceptions::NotDefinedEntryMethod.new(name: __method__, feature: self) }
+                feature_class.define_method(name) { |*args, **kwargs, &block| ::ConvenientService.raise ::ConvenientService::Feature::Plugins::CanHaveEntries::Exceptions::NotDefinedEntryMethod.new(name: __method__, feature: self) }
+              end
+
+              ##
+              # NOTE: Just `feature_class.instance_proxy_class.define_method` does NOT create a closure for `name`.
+              # That is why `feature_class.instance_proxy_class.class_exec` wrapper is required.
+              #
+              feature_class.instance_proxy_class.class_exec(name) do |name|
+                define_method(name) do |*args, **kwargs, &block|
+                  instance_proxy_target.entry(name, *args, **kwargs, &block)
+                end
+              end
+
+              feature_class.instance_proxy_class.define_method(:entry) do |*args, **kwargs, &block|
+                instance_proxy_target.entry(*args, **kwargs, &block)
               end
 
               name

data/lib/convenient_service/feature/plugins/can_have_entries/commands.rb

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
+require_relative "commands/define_entries"
 require_relative "commands/define_entry"

data/lib/convenient_service/feature/plugins/can_have_entries/concern.rb

@@ -7,14 +7,23 @@ module ConvenientService
         module Concern
           include Support::Concern
 
+          instance_methods do
+            ##
+            # @return [Object] Can be any type.
+            #
+            def entry(...)
+              public_send(...)
+            end
+          end
+
           class_methods do
             ##
-            # @param name [String, Symbol]
+            # @param names [Array<String, Symbol>]
             # @param body [Proc, nil]
-            # @return [String, Symbol]
+            # @return [Array<String, Symbol>]
             #
-            def entry(name, &body)
-              Commands::DefineEntry.call(feature_class: self, name: name, body: body)
+            def entry(*names, &body)
+              Commands::DefineEntries.call(feature_class: self, names: names, body: body)
             end
           end
         end

data/lib/convenient_service/feature/plugins/can_have_entries/exceptions.rb

@@ -6,18 +6,28 @@ module ConvenientService
       module CanHaveEntries
         module Exceptions
           class NotDefinedEntryMethod < ::ConvenientService::Exception
-            def initialize(name:, feature:)
+            def initialize_with_kwargs(name:, feature:)
               message = <<~TEXT
                 Entry for `#{name}` is registered inside `#{feature.class}` feature, but its corresponding method is NOT defined.
 
-                Did you forget to define it? For example:
+                Did you forget to define it? For example, using method form:
 
                 class #{feature.class}
                   entry :#{name}
 
                   # ...
 
-                  def #{name}
+                  def #{name}(...)
+                    # ...
+                  end
+
+                  # ...
+                end
+
+                Or using block form:
+
+                class #{feature.class}
+                  entry :#{name} do |*args, **kwargs, &block|
                     # ...
                   end
 
@@ -25,7 +35,7 @@ module ConvenientService
                 end
               TEXT
 
-              super(message)
+              initialize(message)
             end
           end
         end

data/lib/convenient_service/logger.rb

@@ -14,6 +14,9 @@ module ConvenientService
   ##
   # @internal
   #   TODO: Custom matcher to track log messages.
+  #   TODO: Fallback for logging methods. Just like with `#clean` in backtrace cleaner.
+  #   TODO: Highlight vertical bars.
+  #   TODO: Highlight tag brackets.
   #
   class Logger < ::Logger
     include ::Singleton
@@ -92,7 +95,7 @@ module ConvenientService
     #
     #   NOTE: Early return is NOT used, since it is NOT possible to return custom values from `writer` methods.
     #
-    #   NOTE: `Warning.warn` is chosen over `Kernel.warn` in order to have a simple to track delegation from RSpec.
+    #   NOTE: `Warning.warn` is chosen over `Kernel.warn` in order to have a simple way to track delegation from RSpec.
     #   - https://ruby-doc.org/core-2.7.0/Warning.html#method-i-warn
     #
     # TODO: Tag/prefix for all Convenient Service logs.

data/lib/convenient_service/rspec/helpers/classes/stub_service/entities/result_spec.rb

@@ -16,7 +16,6 @@ module ConvenientService
               # @param service_class [Class]
               # @param chain [Hash]
               # @return [void]
-              # @since 0.1.0
               #
               def initialize(status:, service_class: nil, chain: {})
                 @status = status
@@ -27,7 +26,6 @@ module ConvenientService
               ##
               # @param service_class [Class]
               # @return [ConvenientService::RSpec::Helpers::Classes::StubService::Entities::ResultSpec]
-              # @since 0.1.0
               #
               def for(service_class)
                 self.class.new(status: status, service_class: service_class, chain: chain)
@@ -36,7 +34,6 @@ module ConvenientService
               ##
               # @param data [Hash]
               # @return [ConvenientService::RSpec::Helpers::Classes::StubService::Entities::ResultSpec]
-              # @since 0.1.0
               #
               def with_data(data)
                 chain[:data] = data
@@ -47,7 +44,6 @@ module ConvenientService
               ##
               # @param message [String]
               # @return [ConvenientService::RSpec::Helpers::Classes::StubService::Entities::ResultSpec]
-              # @since 0.1.0
               #
               def with_message(message)
                 chain[:message] = message
@@ -58,7 +54,6 @@ module ConvenientService
               ##
               # @param code [String]
               # @return [ConvenientService::RSpec::Helpers::Classes::StubService::Entities::ResultSpec]
-              # @since 0.1.0
               #
               def with_code(code)
                 chain[:code] = code
@@ -69,7 +64,6 @@ module ConvenientService
               ##
               # @param data [Hash]
               # @return [ConvenientService::RSpec::Helpers::Classes::StubService::Entities::ResultSpec]
-              # @since 0.1.0
               #
               def and_data(data)
                 chain[:data] = data
@@ -80,7 +74,6 @@ module ConvenientService
               ##
               # @param message [String]
               # @return [ConvenientService::RSpec::Helpers::Classes::StubService::Entities::ResultSpec]
-              # @since 0.1.0
               #
               def and_message(message)
                 chain[:message] = message
@@ -91,7 +84,6 @@ module ConvenientService
               ##
               # @param code [String]
               # @return [ConvenientService::RSpec::Helpers::Classes::StubService::Entities::ResultSpec]
-              # @since 0.1.0
               #
               def and_code(code)
                 chain[:code] = code

data/lib/convenient_service/rspec/helpers/classes/wrap_method/entities/wrapped_method.rb

@@ -132,7 +132,7 @@ module ConvenientService
               # @raise [ConvenientService::RSpec::Helpers::Classes::WrapMethod::Exceptions::ChainAttributePreliminaryAccess]
               #
               def chain_value
-                raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :value) unless chain_called?
+                ::ConvenientService.raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :value) unless chain_called?
 
                 @chain_value
               end
@@ -142,7 +142,7 @@ module ConvenientService
               # @raise [ConvenientService::RSpec::Helpers::Classes::WrapMethod::Exceptions::ChainAttributePreliminaryAccess]
               #
               def chain_args
-                raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :args) unless chain_called?
+                ::ConvenientService.raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :args) unless chain_called?
 
                 @chain_arguments.args
               end
@@ -152,7 +152,7 @@ module ConvenientService
               # @raise [ConvenientService::RSpec::Helpers::Classes::WrapMethod::Exceptions::ChainAttributePreliminaryAccess]
               #
               def chain_kwargs
-                raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :kwargs) unless chain_called?
+                ::ConvenientService.raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :kwargs) unless chain_called?
 
                 @chain_arguments.kwargs
               end
@@ -162,7 +162,7 @@ module ConvenientService
               # @raise [ConvenientService::RSpec::Helpers::Classes::WrapMethod::Exceptions::ChainAttributePreliminaryAccess]
               #
               def chain_block
-                raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :block) unless chain_called?
+                ::ConvenientService.raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :block) unless chain_called?
 
                 @chain_arguments.block
               end
@@ -172,7 +172,7 @@ module ConvenientService
               # @raise [ConvenientService::RSpec::Helpers::Classes::WrapMethod::Exceptions::ChainAttributePreliminaryAccess]
               #
               def chain_exception
-                raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :exception) unless chain_called?
+                ::ConvenientService.raise Exceptions::ChainAttributePreliminaryAccess.new(attribute: :exception) unless chain_called?
 
                 @chain_exception
               end

data/lib/convenient_service/rspec/helpers/classes/wrap_method/exceptions.rb

@@ -11,12 +11,12 @@ module ConvenientService
               # @param attribute [Symbol]
               # @return [void]
               #
-              def initialize(attribute:)
+              def initialize_with_kwargs(attribute:)
                 message = <<~TEXT
                   Chain attribute `#{attribute}` is accessed before the chain is called.
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
           end

data/lib/convenient_service/rspec/matchers/classes/results/base/entities/validator/commands/validate_result_step.rb

@@ -76,7 +76,7 @@ module ConvenientService
                       when :result then match_result_method_step?
                       when ::Symbol then match_method_step?
                       when nil then match_without_step?
-                      else raise Exceptions::InvalidStep.new(step: step)
+                      else ::ConvenientService.raise Exceptions::InvalidStep.new(step: step)
                       end
                     end
 

data/lib/convenient_service/rspec/matchers/classes/results/base/exceptions.rb

@@ -14,7 +14,7 @@ module ConvenientService
                 # @param step [ConvenientService::Service, Symbol]
                 # @return [void]
                 #
-                def initialize(step:)
+                def initialize_with_kwargs(step:)
                   message = <<~TEXT
                     Step `#{step}` is NOT valid.
 
@@ -29,7 +29,7 @@ module ConvenientService
                     be_success.without_step
                   TEXT
 
-                  super(message)
+                  initialize(message)
                 end
               end
             end

data/lib/convenient_service/rspec/primitive_helpers/classes/ignoring_exception/exceptions.rb

@@ -11,12 +11,12 @@ module ConvenientService
               # @param exception [StandardError]
               # @return [void]
               #
-              def initialize(exception:)
+              def initialize_with_kwargs(exception:)
                 message = <<~TEXT
                   Exception `#{exception}` is NOT raised. That is why it is NOT ignored.
                 TEXT
 
-                super(message)
+                initialize(message)
               end
             end
           end