convenient_service 0.12.0 → 0.13.0

data/benchmark/has_committed_config/ips.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "convenient_service"
+require "benchmark/ips"
+
+##
+# Introduction.
+#
+# This benchmark is checking `.has_committed_config?`. As a result, keep in mind that everything in this file should be reviewed in its context.
+# For example, there is a class called `CurrentImplementation`. Actually, it is the `ImplementationWithoutMemoizationOfHasCommittedConfigInService`.
+# Or `WithMemoizationInService` - means `ImplementationWithMemoizationOfHasCommittedConfigInService`, etc.
+#
+# For the current implementation source, see `ConvenientService::Core::Concern::ClassMethods#has_committed_config?`.
+##
+
+class CurrentImplementation
+  include ConvenientService::Standard::Config
+end
+
+class WithMemoizationInService
+  include ConvenientService::Standard::Config
+
+  class << self
+    def has_committed_config?
+      @__convenient_service_has_committed_config__ ||= super
+    end
+  end
+end
+
+##
+# Warmup.
+#
+implementations = [CurrentImplementation, WithMemoizationInService]
+
+implementations.each(&:commit_config!)
+
+##
+# Benchmarking of iterations per second.
+#
+Benchmark.ips do |x|
+  x.time = 5 # Seconds.
+  x.warmup = 0 # No additional warmup required. It is already performed outside.
+
+  x.report("`.has_committed_config?` - No memoization in service") { CurrentImplementation.has_committed_config? }
+  x.report("`.has_committed_config?` - Memoization in service") { WithMemoizationInService.has_committed_config? }
+
+  x.compare!(order: :baseline)
+end
+
+##
+# Example result.
+#
+# Calculating -------------------------------------
+# `.has_committed_config?` - No memoization in service
+#                         131.142k (± 8.9%) i/s -    220.039k in   1.777241s
+# `.has_committed_config?` - Memoization in service
+#                         131.319k (±10.5%) i/s -    216.215k in   1.763880s
+
+# Comparison:
+# `.has_committed_config?` - No memoization in service:   131142.1 i/s
+# `.has_committed_config?` - Memoization in service:   131319.1 i/s - same-ish: difference falls within error
+##
+
+##
+# Summary.
+#
+# It is one of the Convenient Service design goals to NOT pollute the end-user public interface with extra private methods, instance variables, etc.
+# Since memoization does NOT bring too big performance improvement, no extra instance variables are introduced.
+##
+
+##
+# More info.
+# - https://johnnunemaker.com/how-to-benchmark-your-ruby-gem
+# - https://github.com/evanphx/benchmark-ips
+# - https://rubydoc.info/gems/benchmark-ips/Benchmark/Compare
+# - https://en.wikipedia.org/wiki/Standard_deviation
+##

data/benchmark/has_committed_config/profile.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "convenient_service"
+require "stackprof"
+
+class Service
+  include ConvenientService::Standard::Config
+end
+
+Service.commit_config!
+
+##
+# Quotes:
+# - stackprof will tell you what is impeding your progress.
+# - The assumption is the more times something shows up in the sample the more time it is taking.
+#
+# Docs:
+# - https://www.johnnunemaker.com/how-to-benchmark-your-ruby-gem
+# - https://github.com/tmm1/stackprof
+#
+profile = StackProf.run(mode: :wall, interval: 1_000) do
+  2_000_000.times { Service.has_committed_config? }
+end
+
+result = StackProf::Report.new(profile)
+puts
+result.print_text
+puts "\n\n\n"
+result.print_method(/has_committed_config?/)

data/convenient_service.gemspec

@@ -36,11 +36,35 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "appraisal"
+  ##
+  # Used to run specs with multiple versions of gems.
+  # - https://github.com/thoughtbot/appraisal
+  #
+  spec.add_development_dependency "appraisal", "~> 2.5.0"
 
   spec.add_development_dependency "awesome_print"
 
   ##
+  # Used for benchmarking (iteration per second). See `benchmark` directory.
+  # - https://github.com/evanphx/benchmark-ips
+  # - https://www.johnnunemaker.com/how-to-benchmark-your-ruby-gem
+  #
+  spec.add_development_dependency "benchmark-ips", "~> 2.12.0"
+
+  ##
+  # Used for debugging any Ruby code (CRuby, JRuby, etc), since it written in plain Ruby.
+  # Has minimalistic interface.
+  # Does NOT support frame filtering.
+  # - https://github.com/gsamokovarov/break
+  #
+  spec.add_development_dependency "break"
+
+  ##
+  # Used for debugging CRuby code.
+  # Check `debug` if you need frame filtering.
+  # Check `break` if you need to debug JRuby.
+  # - https://github.com/deivid-rodriguez/byebug
+  #
   # NOTE: `byebug` has C extensions, that is why it is NOT supported in JRuby.
   # - https://github.com/deivid-rodriguez/byebug/tree/master/ext/byebug
   # - https://github.com/deivid-rodriguez/byebug/issues/179#issuecomment-152727003
@@ -53,6 +77,21 @@ Gem::Specification.new do |spec|
   #
   spec.add_development_dependency "commonmarker" unless ConvenientService::Support::Ruby.jruby?
 
+  ##
+  # Used for debugging CRuby code.
+  # Has almost the same public API as `byebug`, but supports frame filtering.
+  # Check `break` if you need to debug JRuby.
+  # - https://github.com/ruby/debug
+  # - https://st0012.dev/from-byebug-to-ruby-debug
+  # - https://st0012.dev/from-byebug-to-ruby-debug#heading-configuration
+  # - https://github.com/ruby/debug#configuration
+  # - ENV["RUBY_DEBUG_SKIP_PATH"]
+  #
+  # NOTE: `debug` has C extensions, that is why it is NOT supported in JRuby.
+  # - https://github.com/ruby/debug/tree/master/ext/debug
+  #
+  spec.add_development_dependency "debug" unless ConvenientService::Support::Ruby.jruby?
+
   spec.add_development_dependency "faker"
 
   spec.add_development_dependency "gem-release"
@@ -61,6 +100,35 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "json"
 
+  ##
+  # Used for memory profiling of Ruby code.
+  # - https://github.com/SamSaffron/memory_profiler
+  # - https://thoughtbot.com/blog/a-crash-course-in-analyzing-memory-usage-in-ruby
+  #
+  spec.add_development_dependency "memory_profiler"
+
+  ##
+  # Used for testing Ruby code outside RSpec.
+  # - https://github.com/minitest/minitest
+  # - https://semaphoreci.com/community/tutorials/getting-started-with-minitest
+  # - https://cloudbees.com/blog/getting-started-with-minitest
+  #
+  spec.add_development_dependency "minitest", "~> 5.18.0"
+
+  ##
+  # Used for mutation testing of Ruby code.
+  # - https://github.com/mbj/mutant
+  # - https://github.com/mbj/mutant/blob/main/docs/nomenclature.md
+  # - https://github.com/mbj/mutant/blob/main/docs/mutant-rspec.md
+  # - https://github.com/mbj/mutant/blob/main/docs/incremental.md
+  #
+  spec.add_development_dependency "mutant", "~> 0.11.21"
+  spec.add_development_dependency "mutant-rspec", "~> 0.11.21"
+
+  ##
+  # Used for coloring logs.
+  # - https://github.com/janlelis/paint
+  #
   spec.add_development_dependency "paint"
 
   spec.add_development_dependency "progressbar"
@@ -71,23 +139,76 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "rouge"
 
+  ##
+  # Used for testing Ruby code.
+  # https://rspec.info
+  #
   spec.add_development_dependency "rspec", "~> 3.11.0"
 
-  spec.add_development_dependency "rubocop", "~> 1.40.0"
+  ##
+  # Used for performance testing with RSpec.
+  # https://github.com/piotrmurach
+  #
+  spec.add_development_dependency "rspec-benchmark", "~> 0.6.0"
 
-  spec.add_development_dependency "rubocop-rspec"
+  ##
+  # Used for linting Ruby files.
+  # https://github.com/rubocop/rubocop
+  #
+  spec.add_development_dependency "rubocop", "~> 1.52.0"
+
+  ##
+  # Used as a set of rules for rubocop for linting RSpec files.
+  # https://github.com/rubocop/rubocop-rspec
+  #
+  spec.add_development_dependency "rubocop-rspec", "~> 2.22.0"
 
   spec.add_development_dependency "tty-prompt"
 
-  spec.add_development_dependency "standard"
+  ##
+  # Used as a set of rules for robocop for linting source files.
+  # https://github.com/testdouble/standard
+  #
+  spec.add_development_dependency "standard", "~> 1.30.1"
 
   spec.add_development_dependency "simplecov"
 
   spec.add_development_dependency "simplecov-lcov"
 
+  ##
+  # Used to have a simplified public API of minitest.
+  # - https://github.com/thoughtbot/shoulda-context
+  #
+  spec.add_development_dependency "shoulda-context", "~> 2.0.0"
+
+  ##
+  # Used for benchmarking (call-stack profiler). See `benchmark` directory.
+  # - https://github.com/tmm1/stackprof
+  # - https://www.johnnunemaker.com/how-to-benchmark-your-ruby-gem
+  #
+  spec.add_development_dependency "stackprof", "~> 0.2.25" unless ConvenientService::Support::Ruby.jruby?
+
   spec.add_development_dependency "webrick"
 
   spec.add_development_dependency "yard", "~> 0.9.28"
 
   spec.add_development_dependency "yard-junk"
+
+  ##
+  # The following gems are Convenient Service alternatives.
+  # Used for performance comparisons.
+  # See `benchmark/empty_service`.
+  # - https://github.com/sunny/actor
+  # - https://github.com/collectiveidea/interactor
+  # - https://github.com/trailblazer/trailblazer-operation
+  # - https://github.com/AaronLasseigne/active_interaction
+  # - https://github.com/adomokos/light-service
+  # - https://github.com/cypriss/mutations
+  #
+  spec.add_development_dependency "service_actor", "~> 3.7.0"
+  spec.add_development_dependency "interactor", "~> 3.1.2"
+  spec.add_development_dependency "trailblazer-operation", "~> 0.10.1"
+  spec.add_development_dependency "active_interaction", "~> 5.3.0"
+  spec.add_development_dependency "light-service", "~> 0.18.0"
+  spec.add_development_dependency "mutations", "~> 0.9.1"
 end

data/lib/convenient_service/alias.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+CS = ::ConvenientService

data/lib/convenient_service/aliases.rb

@@ -9,8 +9,4 @@ module ConvenientService
   Command = ::ConvenientService::Support::Command
   Concern = ::ConvenientService::Support::Concern
   DependencyContainer = ::ConvenientService::Support::DependencyContainer
-
-  ClassicMiddleware = ::ConvenientService::Core::Entities::ClassicMiddleware
-  ConcernMiddleware = ::ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Middleware
-  MethodChainMiddleware = ::ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware
 end

data/lib/convenient_service/common/plugins/assigns_attributes_in_constructor/using_active_model_attribute_assignment/middleware.rb

@@ -5,7 +5,9 @@ module ConvenientService
     module Plugins
       module AssignsAttributesInConstructor
         module UsingActiveModelAttributeAssignment
-          class Middleware < Core::MethodChainMiddleware
+          class Middleware < MethodChainMiddleware
+            intended_for :initialize, entity: any_entity
+
             ##
             # @param args [Array<Object>]
             # @param kwargs [Hash{Symbol => Object}]

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Common
+    module Plugins
+      module CachesConstructorArguments
+        module Concern
+          include Support::Concern
+
+          instance_methods do
+            ##
+            # @return [ConvenientService::Support::Arguments]
+            #
+            def constructor_arguments
+              internals.cache[:constructor_arguments] || Support::Arguments.null_arguments
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Common
+    module Plugins
+      module CachesConstructorArguments
+        class Middleware < MethodChainMiddleware
+          intended_for :initialize, entity: any_entity
+
+          ##
+          # @return [void]
+          #
+          def next(...)
+            entity.internals.cache[:constructor_arguments] = Support::Arguments.new(...)
+
+            chain.next(...)
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -4,17 +4,14 @@ module ConvenientService
   module Common
     module Plugins
       module CachesReturnValue
-        class Middleware < Core::MethodChainMiddleware
+        class Middleware < MethodChainMiddleware
+          intended_for any_method, scope: any_scope, entity: any_entity
+
           ##
-          # @param args [Array<Object>]
-          # @param kwargs [Hash{Symbol => Object}]
-          # @param block [Proc, nil]
           # @return [Object] Can be any type.
           #
-          def next(*args, **kwargs, &block)
-            key = cache.keygen(:return_values, method, *args, **kwargs, &block)
-
-            cache.fetch(key) { chain.next(*args, **kwargs, &block) }
+          def next(...)
+            cache.fetch(key) { chain.next(...) }
           end
 
           private
@@ -25,6 +22,13 @@ module ConvenientService
           def cache
             @cache ||= entity.internals.cache
           end
+
+          ##
+          # @return [ConvenientService::Support::Cache::Entities::Key]
+          #
+          def key
+            @key ||= cache.keygen(:return_values, method, *next_arguments.args, **next_arguments.kwargs, &next_arguments.block)
+          end
         end
       end
     end

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

@@ -8,22 +8,39 @@ module ConvenientService
           include Support::Concern
 
           ##
-          # NOTE: `CanBeCopied` plugin expects that `CachesConstructorParams` plugin is already used.
-          # That is why `constructor_params` method is available.
+          # @internal
+          #   NOTE: `CanBeCopied` plugin expects that `CachesConstructorArguments` plugin is already used.
+          #   That is why `constructor_arguments` method is available.
           #
           instance_methods do
             include Support::Copyable
 
+            ##
+            # @return [Array<Object>]
+            #
             def to_args
-              constructor_params.args
+              constructor_arguments.args
             end
 
+            ##
+            # @return [Hash{Symbol => Object}]
+            #
             def to_kwargs
-              constructor_params.kwargs
+              constructor_arguments.kwargs
             end
 
+            ##
+            # @return [Proc, nil]
+            #
             def to_block
-              constructor_params.block
+              constructor_arguments.block
+            end
+
+            ##
+            # @return [ConvenientService::Support::Arguments]
+            #
+            def to_arguments
+              constructor_arguments
             end
           end
         end

data/lib/convenient_service/common/plugins/can_have_user_provided_entity/commands/find_or_create_entity.rb

@@ -32,8 +32,10 @@ module ConvenientService
             # @return [void]
             #
             def call
-              raise Errors::ProtoEntityHasNoName.new(proto_entity: proto_entity) unless proto_entity_name
-              raise Errors::ProtoEntityHasNoConcern.new(proto_entity: proto_entity) unless proto_entity_concern
+              raise Exceptions::ProtoEntityHasNoName.new(proto_entity: proto_entity) unless proto_entity_name
+              raise Exceptions::ProtoEntityHasNoConcern.new(proto_entity: proto_entity) unless proto_entity_concern
+
+              entity.include Core
 
               entity.include proto_entity_concern
 
@@ -42,14 +44,14 @@ module ConvenientService
               #
               #   klass = ConvenientService::Common::Plugins::CanHaveUserProvidedEntity::Commands::FindOrCreateEntity.call(
               #     namespace: SomeService,
-              #     proto_entity: ConvenientService::Service::Plugins::HasResult::Entities::Result
+              #     proto_entity: ConvenientService::Service::Plugins::HasJSendResult::Entities::Result
               #   )
               #
               #   ##
               #   # `klass` is something like:
               #   #
-              #   # class Result < ConvenientService::Service::Plugins::HasResult::Entities::Result # or just `class Result` if service (namespace) class defines its own.
-              #   #   include ConvenientService::Service::Plugins::HasResult::Entities::Result::Concern # (concern)
+              #   # class Result < ConvenientService::Service::Plugins::HasJSendResult::Entities::Result # or just `class Result` if service (namespace) class defines its own.
+              #   #   include ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Concern # (concern)
               #   #
               #   #   class << self
               #   #     def proto_entity
@@ -93,7 +95,7 @@ module ConvenientService
             # @return [String, nil]
             #
             def proto_entity_name
-              Utils::Object.memoize_including_falsy_values(self, :@proto_entity_name) { proto_entity.name }
+              Utils.memoize_including_falsy_values(self, :@proto_entity_name) { proto_entity.name }
             end
 
             ##
@@ -107,7 +109,7 @@ module ConvenientService
             # @return [Module]
             #
             def proto_entity_concern
-              Utils::Object.memoize_including_falsy_values(self, :@proto_entity_concern) { Utils::Module.get_own_const(proto_entity, :Concern) }
+              Utils.memoize_including_falsy_values(self, :@proto_entity_concern) { Utils::Module.get_own_const(proto_entity, :Concern) }
             end
           end
         end

data/lib/convenient_service/common/plugins/can_have_user_provided_entity/{errors.rb → exceptions.rb}

@@ -4,8 +4,8 @@ module ConvenientService
   module Common
     module Plugins
       module CanHaveUserProvidedEntity
-        module Errors
-          class ProtoEntityHasNoName < ::ConvenientService::Error
+        module Exceptions
+          class ProtoEntityHasNoName < ::ConvenientService::Exception
             def initialize(proto_entity:)
               message = <<~TEXT
                 Proto entity `#{proto_entity}` has no name.
@@ -22,12 +22,12 @@ module ConvenientService
             end
           end
 
-          class ProtoEntityHasNoConcern < ::ConvenientService::Error
+          class ProtoEntityHasNoConcern < ::ConvenientService::Exception
             def initialize(proto_entity:)
               message = <<~TEXT
                 Proto entity `#{proto_entity}` has no concern.
 
-                Have a look at `ConvenientService::Service::Plugins::HasResult::Entities::Result`.
+                Have a look at `ConvenientService::Service::Plugins::HasJSendResult::Entities::Result`.
 
                 It is an example of a valid proto entity.
               TEXT

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

@@ -2,4 +2,4 @@
 
 require_relative "can_have_user_provided_entity/commands"
 require_relative "can_have_user_provided_entity/container"
-require_relative "can_have_user_provided_entity/errors"
+require_relative "can_have_user_provided_entity/exceptions"

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Common
+    module Plugins
+      module CanUtilizeFiniteLoop
+        module Concern
+          include Support::Concern
+
+          instance_methods do
+            private
+
+            ##
+            # @param max_iteration_count [Integer]
+            # @param default [Object] Can be any type.
+            # @param raise_on_exceedance [Boolean]
+            # @param block [Proc]
+            # @return [Object] Can be any type.
+            #
+            def finite_loop(
+              max_iteration_count: Constants::MAX_ITERATION_COUNT,
+              default: Constants::FINITE_LOOP_EXCEEDED,
+              raise_on_exceedance: false,
+              &block
+            )
+              Support::FiniteLoop.finite_loop(max_iteration_count: max_iteration_count, default: default, raise_on_exceedance: raise_on_exceedance, &block)
+            end
+
+            ##
+            # @return [ConvenientService::Support::UniqueValue]
+            #
+            def finite_loop_exceeded
+              Constants::FINITE_LOOP_EXCEEDED
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/common/plugins/can_utilize_finite_loop/constants.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Common
+    module Plugins
+      module CanUtilizeFiniteLoop
+        module Constants
+          ##
+          # @return [ConvenientService::Support::UniqueValue]
+          #
+          FINITE_LOOP_EXCEEDED = Support::UniqueValue.new("finite_loop_exceeded")
+
+          ##
+          # @return [Integer]
+          #
+          MAX_ITERATION_COUNT = 1_000
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "can_utilize_finite_loop/concern"
+require_relative "can_utilize_finite_loop/constants"

data/lib/convenient_service/common/plugins/has_around_callbacks/{errors.rb → exceptions.rb}

@@ -4,8 +4,8 @@ module ConvenientService
   module Common
     module Plugins
       module HasAroundCallbacks
-        module Errors
-          class AroundCallbackChainIsNotContinued < ::ConvenientService::Error
+        module Exceptions
+          class AroundCallbackChainIsNotContinued < ::ConvenientService::Exception
             def initialize(callback:)
               message = <<~TEXT
                 Around callback chain is NOT continued from `#{callback.block.source_location}`.

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

@@ -4,11 +4,17 @@ module ConvenientService
   module Common
     module Plugins
       module HasAroundCallbacks
-        class Middleware < Core::MethodChainMiddleware
+        class Middleware < MethodChainMiddleware
+          ##
+          # @internal
+          #   TODO: Move to command.
+          #
           include Support::DependencyContainer::Import
 
           import :"entities.Callback", from: Common::Plugins::HasCallbacks::Container
 
+          intended_for any_method, scope: any_scope, entity: any_entity
+
           def next(*args, **kwargs, &block)
             ##
             # A variable that stores return value of middleware `chain.next` aka `original_value`.
@@ -117,12 +123,12 @@ module ConvenientService
             ##
             #
             #
-            raise Errors::AroundCallbackChainIsNotContinued.new(callback: Utils::Array.find_last(around_callbacks, &:called?)) if around_callbacks.any?(&:not_called?)
+            raise Exceptions::AroundCallbackChainIsNotContinued.new(callback: Utils::Array.find_last(around_callbacks, &:called?)) if around_callbacks.any?(&:not_called?)
 
             ##
             #
             #
-            raise Errors::AroundCallbackChainIsNotContinued.new(callback: around_callbacks.last) if initial_around_callback.not_called?
+            raise Exceptions::AroundCallbackChainIsNotContinued.new(callback: around_callbacks.last) if initial_around_callback.not_called?
 
             original_value
           end

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 require_relative "has_around_callbacks/concern"
-require_relative "has_around_callbacks/errors"
+require_relative "has_around_callbacks/exceptions"
 require_relative "has_around_callbacks/middleware"

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

@@ -32,7 +32,7 @@ module ConvenientService
             # @return [Boolean]
             #
             def called?
-              Utils::Bool.to_bool(@called)
+              Utils.to_bool(@called)
             end
 
             ##