convenient_service 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f24d02cddcb69e9108cf7d810c85f4ccf338201b8a31bbc7da0be1ef92bd91a9
-  data.tar.gz: 89c019fa64f6fe8194c9b74a676d367e390cc5cb33efef361a4fcb448cd72d17
+  metadata.gz: a908de0164e680bc5926c42eeeea9df2afdcddd065dcad74dcaf403aacfe22f5
+  data.tar.gz: f10f0debfa96eeef7bf37ff35332606cd8a936833ab0f3ff98490bc0f8e6af37
 SHA512:
-  metadata.gz: a53a4a7fee700e8128eeea830ac57cee73e6a6034d36e61dd224584e06f08ef4d944cdc513bfbac17187866b09969a4f63f31e316745546de032a24965bad6dd
-  data.tar.gz: 47a180d8079468f98eadcfbddc2654323fabeae0d7f8b47febc7c13f80d43d30a30583d7104d60d486b02f6e024155487fe3ce5c20bd1eea39f214ee326dc9ff
+  metadata.gz: 4f172f536a57db46fd16a29ac859a59f32060c910db5ee568249be5a74328d001b152ad71cd81c35344085b41ea85f6e66f5dd8d9fdc414ed2fbe24433a3e002
+  data.tar.gz: a64c8dda2bce2f27f1462f485c3b62268d06c48367d464486fd7a51c2fba01b0ba96da27c5d66a4f467b053b556631d395a25735833c7c448ad733e474b28540

data/README.md

@@ -7,7 +7,7 @@
 <!-- stand_with_ukraine:end -->
 
 <!-- header:start -->
-<!-- TODO: Remove html to display in YARD with commonmark -->
+<!-- TODO: Remove html to display in YARD with common mark -->
 <h1 align="center">
   Convenient Service
 </h1>
@@ -27,7 +27,7 @@
 <!-- badges:end -->
 
 <!-- logo:start -->
-<!-- TODO: Remove html to display in YARD with commonmark -->
+<!-- TODO: Remove html to display in YARD with common mark -->
 <p align="center">
   <img src="https://raw.githubusercontent.com/marian13/convenient_service/main/logo.png" width="300">
 </p>
@@ -51,7 +51,7 @@ This library is under heavy development. Public API may be subject to change. Th
 
 - Check out [Convenient Service Official User Docs](https://userdocs.convenientservice.org/) for installation, requirements, and usage guides.
 
-- Read [the API docs](https://marian13.github.io/convenient_service) to get familiar with the newest functionality that is not documented yet.
+- Read [the API docs](https://apidocs.convenientservice.org/) to get familiar with the newest functionality that is not documented yet.
 
 - Create [an issue](https://github.com/marian13/convenient_service/issues) if you are going to report a bug.
 
@@ -70,5 +70,5 @@ This library is under heavy development. Public API may be subject to change. Th
 ---
 
 <!-- author:start -->
-Copyright (c) 2022-2023 [Marian Kostyk](http://mariankostyk.com).
+Copyright (c) 2022-2024 Marian Kostyk.
 <!-- author:end -->

data/lib/convenient_service/common/plugins/ensures_negated_j_send_result/middleware.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Common
+    module Plugins
+      module EnsuresNegatedJSendResult
+        class Middleware < MethodChainMiddleware
+          intended_for :negated_result, entity: any_entity
+
+          ##
+          # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+          #
+          def next(...)
+            result = chain.next(...)
+
+            result.negated? ? result : result.copy(overrides: {kwargs: {negated: true}})
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/common/plugins/ensures_negated_j_send_result.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ensures_negated_j_send_result/middleware"

data/lib/convenient_service/common/plugins/has_around_callbacks/concern.rb

@@ -8,8 +8,15 @@ module ConvenientService
           include Support::Concern
 
           class_methods do
+            ##
+            # @api public
+            #
+            # @param type [Symbol]
+            # @param block [Proc]
+            # @return [ConvenientService::Common::Plugins::HasCallbacks::Entities::Callback]
+            #
             def around(type, &block)
-              Plugins::HasCallbacks::Entities::Callback.new(types: [:around, type], block: block).tap { |callback| callbacks << callback }
+              callbacks.create(types: [:around, type], block: block)
             end
           end
         end

data/lib/convenient_service/common/plugins/has_around_callbacks/middleware.rb

@@ -5,16 +5,28 @@ module ConvenientService
     module Plugins
       module HasAroundCallbacks
         class Middleware < MethodChainMiddleware
+          include Support::Delegate
+
           ##
           # @internal
-          #   TODO: Move to command.
+          #   TODO: Support of callbacks for class methods.
           #
-          include Support::DependencyContainer::Import
+          intended_for any_method, entity: any_entity
 
-          import :"entities.Callback", from: Common::Plugins::HasCallbacks::Container
-
-          intended_for any_method, scope: any_scope, entity: any_entity
+          ##
+          # @return [Class<ConvenientService::Common::Plugins::HasCallbacks::Entities::Callback>]
+          #
+          delegate :callback_class, to: :callbacks
 
+          ##
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil]
+          # @return [Object] Can be any type.
+          #
+          # @internal
+          #   TODO: Move to command.
+          #
           def next(*args, **kwargs, &block)
             ##
             # A variable that stores return value of middleware `chain.next` aka `original_value`.
@@ -41,12 +53,12 @@ module ConvenientService
             #   end
             # end
             #
-            around_callbacks = entity.callbacks.for([:around, method])
+            around_callbacks = callbacks.for([:around, method])
 
             ##
             #
             #
-            initial_around_callback = entities.Callback.new(
+            initial_around_callback = callback_class.new(
               types: [:around, method],
               block: proc { original_value = chain.next(*args, **kwargs, &block) }
             )
@@ -132,6 +144,15 @@ module ConvenientService
 
             original_value
           end
+
+          private
+
+          ##
+          # @return [ConvenientService::Common::Plugins::HasCallbacks::Entities::CallbackCollection]
+          #
+          def callbacks
+            entity.class.callbacks
+          end
         end
       end
     end

data/lib/convenient_service/common/plugins/has_callbacks/concern.rb

@@ -7,26 +7,36 @@ module ConvenientService
         module Concern
           include Support::Concern
 
-          instance_methods do
-            include Support::Delegate
-
-            delegate :callbacks, to: :class
-          end
-
           class_methods do
             ##
             # @api private
             #
+            # @return [ConvenientService::Common::Plugins::HasCallbacks::Entities::CallbackCollection]
+            #
             def callbacks
-              @__callbacks__ ||= Entities::CallbackCollection.new
+              internals_class.cache.fetch(:callbacks) { Entities::CallbackCollection.new }
             end
 
+            ##
+            # @api public
+            #
+            # @param type [Symbol]
+            # @param block [Proc]
+            # @return [ConvenientService::Common::Plugins::HasCallbacks::Entities::Callback]
+            #
             def before(type, &block)
-              Entities::Callback.new(types: [:before, type], block: block).tap { |callback| callbacks << callback }
+              callbacks.create(types: [:before, type], block: block)
             end
 
+            ##
+            # @api public
+            #
+            # @param type [Symbol]
+            # @param block [Proc]
+            # @return [ConvenientService::Common::Plugins::HasCallbacks::Entities::Callback]
+            #
             def after(type, &block)
-              Entities::Callback.new(types: [:after, type], block: block).tap { |callback| callbacks << callback }
+              callbacks.create(types: [:after, type], block: block)
             end
           end
         end

data/lib/convenient_service/common/plugins/has_callbacks/entities/callback_collection.rb

@@ -6,20 +6,68 @@ module ConvenientService
       module HasCallbacks
         module Entities
           class CallbackCollection
+            include ::Enumerable
+
             include Support::Delegate
 
+            ##
+            # @api private
+            #
+            # @!attribute [r] types
+            #   @return [ConvenientService::Common::Plugins::HasCallbacks::Entities::TypeCollection]
+            #
             attr_reader :callbacks
 
-            delegate :each, :include?, :<<, to: :callbacks
+            ##
+            # @api private
+            #
+            # @return [Array<ConvenientService::Common::Plugins::HasCallbacks::Entities::Callback>]
+            #
+            delegate :each, to: :callbacks
 
+            ##
+            # @api private
+            #
+            # @return [void]
+            #
             def initialize
               @callbacks = []
             end
 
+            ##
+            # @return [Class<ConvenientService::Common::Plugins::HasCallbacks::Entities::Callback>]
+            #
+            def callback_class
+              Entities::Callback
+            end
+
+            ##
+            # @api private
+            #
+            # @param types [Array<Symbol>]
+            # @return [Array<ConvenientService::Common::Plugins::HasCallbacks::Entities::Callback>]
+            #
             def for(types)
               callbacks.select { |callback| callback.types.contain_exactly?(types) }
             end
 
+            ##
+            # @api private
+            #
+            # @param kwargs [Hash{Symbol => Object}]
+            # @return [ConvenientService::Common::Plugins::HasCallbacks::Entities::Callback]
+            #
+            def create(**kwargs)
+              Entities::Callback.new(**kwargs)
+                .tap { |callback| callbacks << callback }
+            end
+
+            ##
+            # @api private
+            #
+            # @param other [Object] Can be any type.
+            # @return [Boolean]
+            #
             def ==(other)
               return unless other.instance_of?(self.class)
 

data/lib/convenient_service/common/plugins/has_callbacks/middleware.rb

@@ -5,9 +5,18 @@ module ConvenientService
     module Plugins
       module HasCallbacks
         class Middleware < MethodChainMiddleware
-          intended_for any_method, scope: any_scope, entity: any_entity
+          ##
+          # @internal
+          #   TODO: Support of callbacks for class methods.
+          #
+          intended_for any_method, entity: any_entity
 
           ##
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil]
+          # @return [Object] Can be any type.
+          #
           # @internal
           #   TODO: Move to command.
           #
@@ -21,7 +30,7 @@ module ConvenientService
             #   end
             # end
             #
-            entity.callbacks.for([:before, method]).each { |callback| callback.call_in_context_with_arguments(entity, *args, **kwargs, &block) }
+            callbacks.for([:before, method]).each { |callback| callback.call_in_context_with_arguments(entity, *args, **kwargs, &block) }
 
             original_value = chain.next(*args, **kwargs, &block)
 
@@ -37,10 +46,19 @@ module ConvenientService
             #   end
             # end
             #
-            entity.callbacks.for([:after, method]).reverse_each { |callback| callback.call_in_context_with_value_and_arguments(entity, original_value, *args, **kwargs, &block) }
+            callbacks.for([:after, method]).reverse_each { |callback| callback.call_in_context_with_value_and_arguments(entity, original_value, *args, **kwargs, &block) }
 
             original_value
           end
+
+          private
+
+          ##
+          # @return [ConvenientService::Common::Plugins::HasCallbacks::Entities::CallbackCollection]
+          #
+          def callbacks
+            entity.class.callbacks
+          end
         end
       end
     end

data/lib/convenient_service/common/plugins/has_callbacks.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
 require_relative "has_callbacks/concern"
-require_relative "has_callbacks/container"
 require_relative "has_callbacks/entities"
 require_relative "has_callbacks/middleware"

data/lib/convenient_service/common/plugins/has_instance_proxy/entities/instance_proxy.rb

@@ -66,7 +66,7 @@ module ConvenientService
             # @return [Object] Can be any type.
             #
             def method_missing(...)
-              instance_proxy_target.public_send(...)
+              ::ConvenientService.reraise { instance_proxy_target.public_send(...) }
             end
           end
         end

data/lib/convenient_service/common/plugins/has_internals/entities/internals/plugins/has_cache/concern.rb

@@ -15,6 +15,18 @@ module ConvenientService
                 module Concern
                   include Support::Concern
 
+                  class_methods do
+                    ##
+                    # @return [ConvenientService::Support::Cache]
+                    #
+                    # @internal
+                    #   TODO: `Support::Cache.create(backend: :thread_safe_hash)`.
+                    #
+                    def cache
+                      @cache ||= Support::Cache.create(backend: :hash)
+                    end
+                  end
+
                   instance_methods do
                     ##
                     # @return [ConvenientService::Support::Cache]

data/lib/convenient_service/common/plugins.rb

@@ -9,6 +9,7 @@ require_relative "plugins/caches_constructor_arguments"
 require_relative "plugins/caches_return_value"
 require_relative "plugins/can_be_copied"
 require_relative "plugins/can_have_user_provided_entity"
+require_relative "plugins/ensures_negated_j_send_result"
 require_relative "plugins/has_callbacks"
 require_relative "plugins/has_around_callbacks"
 require_relative "plugins/has_constructor"

data/lib/convenient_service/core/entities/config/exceptions.rb

@@ -30,6 +30,8 @@ module ConvenientService
             #   TODO: Create a troubleshooting page with possible reasons (preliminary RSpec mocks etc).
             #   Append a link to it to the error message.
             #
+            #   TODO: Add a note of the most common scenario when this issue appears - when the RSpec stub is used before auto config commitment. For example, with `delegate_to`.
+            #
             def initialize_with_kwargs(config:)
               message = <<~TEXT
                 `#{config.klass}` config is committed too many times from `method_missing`.

data/lib/convenient_service/core/entities/config.rb

@@ -142,6 +142,9 @@ module ConvenientService
         # @internal
         #   IMPORTANT: `commit!` MUST be thread safe.
         #
+        #   NOTE: Inspired by `Response#commit!` and others.
+        #   - https://github.com/rails/rails/blob/36c1591bcb5e0ee3084759c7f42a706fe5bb7ca7/actionpack/lib/action_controller/metal/live.rb#L307
+        #
         def commit!(trigger: Constants::Triggers::USER)
           (committed? ? false : concerns.include!)
             .tap { Commands::TrackMethodMissingCommitTrigger.call(config: self, trigger: trigger) }

data/lib/convenient_service/dependencies.rb

@@ -175,13 +175,20 @@ module ConvenientService
       end
 
       ##
-      # @api public
+      # @api private
       #
       # @return [Boolean]
       # @note Expected to be called from app entry points like `initializers` in Rails.
       #
-      def require_cleans_exception_backtrace
-        require_relative "dependencies/extractions/active_support_backtrace_cleaner"
+      def require_wraps_result_in_db_transaction
+        ##
+        # - https://edgeguides.rubyonrails.org/active_record_basics.html
+        # - https://api.rubyonrails.org/classes/ActiveRecord.html
+        # - https://github.com/rails/rails/tree/main/activerecord
+        #
+        require "active_record"
+
+        require_relative "service/plugins/wraps_result_in_db_transaction"
       end
 
       ##
@@ -336,6 +343,7 @@ module ConvenientService
         require_relative ::File.join("examples", "standard", version, "factorial")
         require_relative ::File.join("examples", "standard", version, "gemfile")
         require_relative ::File.join("examples", "standard", version, "request_params")
+        require_relative ::File.join("examples", "standard", version, "comprehensive_suite") if version.empty?
       end
 
       ##

data/lib/convenient_service/logger.rb

@@ -36,11 +36,19 @@ module ConvenientService
       #   - https://github.com/ruby/logger/blob/v1.5.3/lib/logger.rb#L397
       #
       #   TODO: Specs for `super(::STDOUT)`.
+      #   TODO: Warning and fallback when `CONVENIENT_SERVICE_LOGGER_LEVEL` is NOT valid.
       #
       # rubocop:disable Style/GlobalStdStream
       def new
         super(::STDOUT).tap do |logger|
-          logger.level = ::ENV["CONVENIENT_SERVICE_LOGGER_LEVEL"] || ::Logger::INFO
+          logger.level =
+            if ::ENV["CONVENIENT_SERVICE_DEBUG"] == "true"
+              ::Logger::DEBUG
+            elsif ::ENV["CONVENIENT_SERVICE_LOGGER_LEVEL"]
+              ::ENV["CONVENIENT_SERVICE_LOGGER_LEVEL"]
+            else
+              ::Logger::INFO
+            end
 
           logger.formatter = (::ENV["CONVENIENT_SERVICE_LOGGER_ENABLE_COLORS"] == "true") ? colored_formatter : original_formatter
         end

data/lib/convenient_service/rspec/matchers/classes/call_chain_next.rb

@@ -11,6 +11,13 @@ module ConvenientService
         #     .with_arguments(*args, **kwargs, &block)
         #     .and_return_its_value
         #
+        # @internal
+        #   TODO:
+        #     expect { method.call }
+        #       .to call_chain_next.on(method)
+        #       .with_arguments(*args, **kwargs, &block)
+        #       .and_return { |chain_value| chain_value.copy(kwargs: {overrides: {foo: :bar}})}
+        #
         class CallChainNext
           include ::RSpec::Expectations
           include ::RSpec::Matchers
@@ -45,6 +52,10 @@ module ConvenientService
               expect(value).to eq(method.chain_value)
             end
 
+            if used_and_return?
+              expect(value).to eq(return_block.call(method.chain_value))
+            end
+
             true
           end
 
@@ -88,6 +99,10 @@ module ConvenientService
               expect(value).not_to eq(method.chain_value)
             end
 
+            if used_and_return?
+              expect(value).not_to eq(return_block.call(method.chain_value))
+            end
+
             true
           end
 
@@ -170,6 +185,18 @@ module ConvenientService
             self
           end
 
+          ##
+          # @param args [Array<Object>]
+          # @param block [Proc, nil]
+          #
+          # @return [ConvenientService::RSpec::Matchers::Classes::CallChainNext]
+          #
+          def and_return(*args, &block)
+            chain[:and_return] = args.any? ? proc { args.first } : block
+
+            self
+          end
+
           private
 
           ##
@@ -192,6 +219,13 @@ module ConvenientService
             chain.key?(:and_return_its_value)
           end
 
+          ##
+          # @return [Boolean]
+          #
+          def used_and_return?
+            chain.key?(:and_return)
+          end
+
           ##
           # @return [Hash{Symbol => Object}]
           #
@@ -242,6 +276,13 @@ module ConvenientService
             @block = chain.dig(:with_arguments, :block)
           end
 
+          ##
+          # @return [Proc]
+          #
+          def return_block
+            @return_block ||= chain[:and_return]
+          end
+
           ##
           # @return [Proc, nil]
           #

data/lib/convenient_service/rspec/primitive_matchers/classes/delegate_to/commands/generate_printable_method.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Commands
+            class GeneratePrintableMethod < Support::Command
+              ##
+              # @!attribute [r] object
+              #   @return [Object] Can be any type.
+              #
+              attr_reader :object
+
+              ##
+              # @!attribute [r] method
+              #   @return [Symbol, String]
+              #
+              attr_reader :method
+
+              ##
+              # @param object [Object] Can by any type.
+              # @param method [Symbol, String]
+              # @return [void]
+              #
+              def initialize(object:, method:)
+                @object = object
+                @method = method
+              end
+
+              def call
+                case Utils::Object.resolve_type(object)
+                when "class", "module"
+                  "#{object}.#{method}"
+                when "instance"
+                  "#{object.class}##{method}"
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/rspec/primitive_matchers/classes/delegate_to/entities/delegation.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module RSpec
+    module PrimitiveMatchers
+      module Classes
+        class DelegateTo
+          module Entities
+            class Delegation
+              ##
+              # @api private
+              #
+              # @!attribute [r] arguments
+              #   @return [ConvenientService::RSpec::PrimitiveMatchers::Classes::DelegateTo::Entities::Delegation]
+              #
+              attr_reader :arguments
+
+              ##
+              # @api private
+              #
+              # @!attribute [r] method
+              #   @return [Symbol]
+              #
+              attr_reader :method
+
+              ##
+              # @api private
+              #
+              # @!attribute [r] object
+              #   @return [Object] Can be any type.
+              #
+              attr_reader :object
+
+              ##
+              # @api private
+              #
+              # @param object [Object] Can be any type.
+              # @param method [Symbol]
+              # @param args [Array<Object>]
+              # @param kwargs [Hash{Symbol => Object}]
+              # @param block [Proc, nil]
+              # @return [void]
+              #
+              def initialize(object:, method:, args:, kwargs:, block:)
+                @object = object
+                @method = method
+                @arguments = Support::Arguments.new(*args, **kwargs, &block)
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Booleam]
+              #
+              def with_arguments?
+                arguments.any?
+              end
+
+              ##
+              # @api private
+              #
+              # @return [Boolean]
+              #
+              def without_arguments?
+                !with_arguments?
+              end
+
+              ##
+              # @api private
+              #
+              # @param other [Object]
+              # @return [Boolean]
+              #
+              def ==(other)
+                return unless other.instance_of?(self.class)
+
+                return false if object != other.object
+                return false if method != other.method
+                return false if arguments != other.arguments
+
+                true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end