convenient_service 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f1f1683a178b667d76adabe5735fa7361e7946f3a9aa7d3bcfffca62ed4d7b4
-  data.tar.gz: 0d64f2e78e0ef56707d8efcdcb66dafd9386a118c44d96139c699a4517cb7bcb
+  metadata.gz: a908de0164e680bc5926c42eeeea9df2afdcddd065dcad74dcaf403aacfe22f5
+  data.tar.gz: f10f0debfa96eeef7bf37ff35332606cd8a936833ab0f3ff98490bc0f8e6af37
 SHA512:
-  metadata.gz: e16ab9be69fb6721ec9fdc290c857d8da8db77bc46702aad4179f6ce04df3d73a0119befec63c13d04d0c24d15ad5d46310fd243f4d3bb214b7153dfdc1d688e
-  data.tar.gz: cef563d9e931f10f766e6ae5f7eb0136a96ab0c892f28a13ddf9db3860a19fcb984a7e514f6b6430750df8287ec9da4df0f4d75ea7a7e620321a72569b08c29e
+  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>
@@ -49,9 +49,9 @@ This library is under heavy development. Public API may be subject to change. Th
 
 - Visit the [All-in-One Presentation](https://marian13.github.io/static_content/convenient_service/presentations/all_in_one) to get a quick overview.
 
-- Check out [Convenient Service Official User Docs](https://marian13.github.io/convenient_service_docs) for installation, requirements, and usage guides.
+- 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/can_have_user_provided_entity/commands/find_or_create_entity.rb

@@ -32,8 +32,8 @@ module ConvenientService
             # @return [void]
             #
             def call
-              raise Exceptions::ProtoEntityHasNoName.new(proto_entity: proto_entity) unless proto_entity_name
-              raise Exceptions::ProtoEntityHasNoConcern.new(proto_entity: proto_entity) unless proto_entity_concern
+              ::ConvenientService.raise Exceptions::ProtoEntityHasNoName.new(proto_entity: proto_entity) unless proto_entity_name
+              ::ConvenientService.raise Exceptions::ProtoEntityHasNoConcern.new(proto_entity: proto_entity) unless proto_entity_concern
 
               entity.include Core
 
@@ -71,6 +71,11 @@ module ConvenientService
               #
               entity.class_exec(proto_entity) do |proto_entity|
                 define_singleton_method(:proto_entity) { proto_entity }
+
+                ##
+                # @internal
+                #   TODO: Try `self.proto_entity == other.proto_entity if self < proto_entity_concern`.
+                #
                 define_singleton_method(:==) { |other| self.proto_entity == other.proto_entity if other.respond_to?(:proto_entity) }
 
                 ##

data/lib/convenient_service/common/plugins/can_have_user_provided_entity/exceptions.rb

@@ -6,7 +6,7 @@ module ConvenientService
       module CanHaveUserProvidedEntity
         module Exceptions
           class ProtoEntityHasNoName < ::ConvenientService::Exception
-            def initialize(proto_entity:)
+            def initialize_with_kwargs(proto_entity:)
               message = <<~TEXT
                 Proto entity `#{proto_entity}` has no name.
 
@@ -18,12 +18,12 @@ module ConvenientService
                 NOTE: Anonymous classes do NOT have names. Are you passing an anonymous class?
               TEXT
 
-              super(message)
+              initialize(message)
             end
           end
 
           class ProtoEntityHasNoConcern < ::ConvenientService::Exception
-            def initialize(proto_entity:)
+            def initialize_with_kwargs(proto_entity:)
               message = <<~TEXT
                 Proto entity `#{proto_entity}` has no concern.
 
@@ -32,7 +32,7 @@ module ConvenientService
                 It is an example of a valid proto entity.
               TEXT
 
-              super(message)
+              initialize(message)
             end
           end
         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/exceptions.rb

@@ -6,7 +6,7 @@ module ConvenientService
       module HasAroundCallbacks
         module Exceptions
           class AroundCallbackChainIsNotContinued < ::ConvenientService::Exception
-            def initialize(callback:)
+            def initialize_with_kwargs(callback:)
               message = <<~TEXT
                 Around callback chain is NOT continued from `#{callback.block.source_location}`.
 
@@ -19,7 +19,7 @@ module ConvenientService
                 end
               TEXT
 
-              super(message)
+              initialize(message)
             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) }
             )
@@ -123,15 +135,24 @@ module ConvenientService
             ##
             #
             #
-            raise Exceptions::AroundCallbackChainIsNotContinued.new(callback: Utils::Array.find_last(around_callbacks, &:called?)) if around_callbacks.any?(&:not_called?)
+            ::ConvenientService.raise Exceptions::AroundCallbackChainIsNotContinued.new(callback: Utils::Array.find_last(around_callbacks, &:called?)) if around_callbacks.any?(&:not_called?)
 
             ##
             #
             #
-            raise Exceptions::AroundCallbackChainIsNotContinued.new(callback: around_callbacks.last) if initial_around_callback.not_called?
+            ::ConvenientService.raise Exceptions::AroundCallbackChainIsNotContinued.new(callback: around_callbacks.last) if initial_around_callback.not_called?
 
             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/commands/create_instance_proxy_class.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Common
+    module Plugins
+      module HasInstanceProxy
+        module Commands
+          class CreateInstanceProxyClass < Support::Command
+            ##
+            # @!attribute [r] target_class
+            #   @return [Class]
+            #
+            attr_reader :target_class
+
+            ##
+            # @param target_class [Class]
+            # @return [void]
+            #
+            def initialize(target_class:)
+              @target_class = target_class
+            end
+
+            ##
+            # @return [void]
+            #
+            def call
+              klass = ::Class.new(Entities::InstanceProxy)
+
+              ##
+              # @example Result for feature.
+              #
+              #   klass = ConvenientService::Common::Plugins::HasInstanceProxy::Commands::CreateInstanceProxyClass.call(
+              #     target_class: SomeFeature
+              #   )
+              #
+              #   ##
+              #   # `klass` is something like:
+              #   #
+              #   # class InstanceProxy < ConvenientService::Service::Plugins::HasInstanceProxy::Entities::InstanceProxy
+              #   #   class << self
+              #   #     def target_class
+              #   #       ##
+              #   #       # NOTE: Returns `target_class` passed to `CreateInstanceProxyClass`.
+              #   #       #
+              #   #       target_class
+              #   #     end
+              #   #
+              #   #     def ==(other)
+              #   #       return unless other.respond_to?(:target_class)
+              #   #
+              #   #       self.target_class == other.target_class
+              #   #     end
+              #   #   end
+              #   # end
+              #
+              klass.class_exec(target_class) do |target_class|
+                ##
+                # @return [Class]
+                #
+                define_singleton_method(:target_class) { target_class }
+
+                ##
+                # @return [Boolean, nil]
+                #
+                # @internal
+                #   TODO: Try `self.target_class == other.target_class if self < ::ConvenientService::Common::Plugins::HasInstanceProxy::Entities::InstanceProxy`.
+                #
+                define_singleton_method(:==) { |other| self.target_class == other.target_class if other.respond_to?(:target_class) }
+
+                ##
+                # @return [String]
+                #
+                define_singleton_method(:inspect) { "#{target_class}::InstanceProxy" }
+              end
+
+              klass
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/common/plugins/has_instance_proxy/commands.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "commands/create_instance_proxy_class"

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Common
+    module Plugins
+      module HasInstanceProxy
+        module Concern
+          include Support::Concern
+
+          class_methods do
+            ##
+            # @return [Class] Can be any type.
+            #
+            def instance_proxy_class
+              @instance_proxy_class ||= Commands::CreateInstanceProxyClass[target_class: self]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Common
+    module Plugins
+      module HasInstanceProxy
+        module Entities
+          class InstanceProxy
+            ##
+            # @api private
+            #
+            # @param target [Object] Can be any type.
+            # @return [void]
+            #
+            def initialize(target:)
+              @__convenient_service_instance_proxy_target__ = target
+            end
+
+            ##
+            # @api public
+            #
+            # @return [Object] Can be any type.
+            #
+            def instance_proxy_target
+              @__convenient_service_instance_proxy_target__
+            end
+
+            ##
+            # @api public
+            #
+            # @param other [Object] Can be any type.
+            # @return [Boolean, nil]
+            #
+            # @internal
+            #   TODO: Direct Specs.
+            #
+            def ==(other)
+              return unless other.instance_of?(self.class)
+
+              return false if instance_proxy_target != other.instance_proxy_target
+
+              true
+            end
+
+            private
+
+            ##
+            # @see https://thoughtbot.com/blog/always-define-respond-to-missing-when-overriding
+            # @see https://blog.marc-andre.ca/2010/11/15/methodmissing-politely
+            # @see https://stackoverflow.com/a/3304683/12201472
+            #
+            # @param method_name [Symbol, String]
+            # @param include_private [Boolean]
+            # @return [Boolean]
+            #
+            # @internal
+            #   IMPORTANT: `respond_to_missing?` is like `initialize`. It is always `private`.
+            #   - https://ruby-doc.org/core-2.7.0/Object.html#method-i-respond_to_missing-3F
+            #   - https://github.com/ruby/spec/blob/master/language/def_spec.rb#L65
+            #
+            def respond_to_missing?(method_name, include_private = false)
+              instance_proxy_target.respond_to?(method_name, include_private)
+            end
+
+            ##
+            # @return [Object] Can be any type.
+            #
+            def method_missing(...)
+              ::ConvenientService.reraise { instance_proxy_target.public_send(...) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "entities/instance_proxy"

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Common
+    module Plugins
+      module HasInstanceProxy
+        class Middleware < MethodChainMiddleware
+          intended_for :new, scope: :class, entity: any_entity
+
+          ##
+          # @return [ConvenientService::Common::Plugins::HasInstanceProxy::Entities::InstanceProxy]
+          #
+          def next(...)
+            entity.instance_proxy_class.new(target: chain.next(...))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "has_instance_proxy/commands"
+require_relative "has_instance_proxy/concern"
+require_relative "has_instance_proxy/entities"
+require_relative "has_instance_proxy/middleware"

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]