convenient_service 0.12.0 → 0.14.0

data/lib/convenient_service/configs/standard.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "standard/v1"
+require_relative "standard/aliases"
+
 module ConvenientService
   module Configs
     ##
@@ -21,32 +24,71 @@ module ConvenientService
         include Configs::Minimal
 
         concerns do
-          use Plugins::Common::CachesConstructorParams::Concern
+          use Plugins::Common::CachesConstructorArguments::Concern
           use Plugins::Common::CanBeCopied::Concern
           use Plugins::Service::CanRecalculateResult::Concern
-          use Plugins::Service::HasResultShortSyntax::Concern
-          use Plugins::Service::HasResultStatusCheckShortSyntax::Concern
+          use Plugins::Service::HasJSendResultShortSyntax::Concern
+          use Plugins::Service::HasJSendResultStatusCheckShortSyntax::Concern
 
           use Plugins::Common::HasCallbacks::Concern
           use Plugins::Common::HasAroundCallbacks::Concern
+
+          use Plugins::Service::CanHaveFallbacks::Concern
+          use Plugins::Service::HasMermaidFlowchart::Concern
         end
 
         middlewares :initialize do
-          use Plugins::Common::CachesConstructorParams::Middleware
+          use Plugins::Service::CollectsServicesInException::Middleware
+          use Plugins::Common::CachesConstructorArguments::Middleware
         end
 
         middlewares :result do
+          insert_after \
+            Plugins::Common::NormalizesEnv::Middleware,
+            Plugins::Service::CollectsServicesInException::Middleware
+
           insert_before \
-            Plugins::Service::HasResult::Middleware,
+            Plugins::Service::RaisesOnNotResultReturnValue::Middleware,
             Plugins::Common::HasCallbacks::Middleware
 
           insert_after \
             Plugins::Common::HasCallbacks::Middleware,
             Plugins::Common::HasAroundCallbacks::Middleware
 
-          use Plugins::Service::RaisesOnDoubleResult::Middleware
+          ##
+          # TODO: Rewrite. This plugin does NOT do what it states. Probably I was NOT with a clear mind while writing it (facepalm).
+          #
+          # use Plugins::Service::RaisesOnDoubleResult::Middleware
+
+          insert_before \
+            Plugins::Service::RaisesOnNotResultReturnValue::Middleware,
+            Plugins::Service::SetsParentToForeignResult::Middleware
+        end
+
+        ##
+        # @internal
+        #   NOTE: Check `Minimal` docs to understand why `use Plugins::Common::NormalizesEnv::Middleware` for `:fallback_failure_result` is used in `Standard`, not in `Minimal` config.
+        #
+        middlewares :fallback_failure_result do
+          use Plugins::Common::NormalizesEnv::Middleware
+          use Plugins::Service::CollectsServicesInException::Middleware
+          use Plugins::Common::CachesReturnValue::Middleware
+
+          use Plugins::Service::RaisesOnNotResultReturnValue::Middleware
+          use Plugins::Service::CanHaveFallbacks::Middleware.with(status: :failure)
+        end
 
+        ##
+        # @internal
+        #   NOTE: Check `Minimal` docs to understand why `use Plugins::Common::NormalizesEnv::Middleware` for `:fallback_error_result` is used in `Standard`, not in `Minimal` config.
+        #
+        middlewares :fallback_error_result do
+          use Plugins::Common::NormalizesEnv::Middleware
+          use Plugins::Service::CollectsServicesInException::Middleware
           use Plugins::Common::CachesReturnValue::Middleware
+
+          use Plugins::Service::RaisesOnNotResultReturnValue::Middleware
+          use Plugins::Service::CanHaveFallbacks::Middleware.with(status: :error)
         end
 
         middlewares :step do
@@ -55,53 +97,51 @@ module ConvenientService
         end
 
         middlewares :success do
-          use Plugins::Service::HasResultShortSyntax::Success::Middleware
+          use Plugins::Service::HasJSendResultShortSyntax::Success::Middleware
         end
 
         middlewares :failure do
-          use Plugins::Service::HasResultShortSyntax::Failure::Middleware
+          use Plugins::Service::HasJSendResultShortSyntax::Failure::Middleware
         end
 
         middlewares :error do
-          use Plugins::Service::HasResultShortSyntax::Error::Middleware
+          use Plugins::Service::HasJSendResultShortSyntax::Error::Middleware
         end
 
         class self::Result
           concerns do
-            use Plugins::Result::HasResultShortSyntax::Concern
+            use Plugins::Common::HasJSendResultDuckShortSyntax::Concern
             use Plugins::Result::CanRecalculateResult::Concern
 
-            use Plugins::Result::HasStep::Concern
+            use Plugins::Result::CanHaveStep::Concern
+            use Plugins::Result::CanBeOwnResult::Concern
+            use Plugins::Result::CanHaveFallbacks::Concern
             use Plugins::Result::CanHaveParentResult::Concern
-          end
-
-          middlewares :initialize do
-            use Plugins::Result::HasStep::Initialize::Middleware
-            use Plugins::Result::CanHaveParentResult::Initialize::Middleware
+            use Plugins::Result::CanHaveCheckedStatus::Concern
           end
 
           middlewares :success? do
-            use Plugins::Result::MarksResultStatusAsChecked::Middleware
+            use Plugins::Result::CanHaveCheckedStatus::Middleware
           end
 
           middlewares :failure? do
-            use Plugins::Result::MarksResultStatusAsChecked::Middleware
+            use Plugins::Result::CanHaveCheckedStatus::Middleware
           end
 
           middlewares :error? do
-            use Plugins::Result::MarksResultStatusAsChecked::Middleware
+            use Plugins::Result::CanHaveCheckedStatus::Middleware
           end
 
           middlewares :not_success? do
-            use Plugins::Result::MarksResultStatusAsChecked::Middleware
+            use Plugins::Result::CanHaveCheckedStatus::Middleware
           end
 
           middlewares :not_failure? do
-            use Plugins::Result::MarksResultStatusAsChecked::Middleware
+            use Plugins::Result::CanHaveCheckedStatus::Middleware
           end
 
           middlewares :not_error? do
-            use Plugins::Result::MarksResultStatusAsChecked::Middleware
+            use Plugins::Result::CanHaveCheckedStatus::Middleware
           end
 
           middlewares :data do
@@ -115,28 +155,76 @@ module ConvenientService
           middlewares :code do
             use Plugins::Result::RaisesOnNotCheckedResultStatus::Middleware
           end
-
-          middlewares :to_kwargs do
-            use Plugins::Result::HasStep::ToKwargs::Middleware
-            use Plugins::Result::CanHaveParentResult::ToKwargs::Middleware
-          end
         end
 
         class self::Step
-          middlewares :calculate_result do
+          concerns do
+            use Plugins::Common::HasJSendResultDuckShortSyntax::Concern
+            use Plugins::Step::CanHaveFallbacks::Concern
+          end
+
+          middlewares :result do
+            use Plugins::Step::CanHaveFallbacks::Middleware.with(fallback_true_status: :failure)
             use Plugins::Step::CanHaveParentResult::Middleware
           end
+
+          middlewares :service_fallback_failure_result do
+            use Plugins::Common::NormalizesEnv::Middleware
+            use Plugins::Common::CachesReturnValue::Middleware
+          end
+
+          middlewares :fallback_failure_result do
+            use Plugins::Common::NormalizesEnv::Middleware
+            use Plugins::Common::CachesReturnValue::Middleware
+          end
+
+          middlewares :service_fallback_error_result do
+            use Plugins::Common::NormalizesEnv::Middleware
+            use Plugins::Common::CachesReturnValue::Middleware
+          end
+
+          middlewares :fallback_error_result do
+            use Plugins::Common::NormalizesEnv::Middleware
+            use Plugins::Common::CachesReturnValue::Middleware
+          end
         end
 
         if Dependencies.rspec.loaded?
           concerns do
-            insert_before 0, Plugins::Service::CanHaveStubbedResult::Concern
+            insert_before 0, Plugins::Service::CanHaveStubbedResults::Concern
+          end
+
+          middlewares :result do
+            insert_after \
+              Plugins::Common::NormalizesEnv::Middleware,
+              Plugins::Service::CanHaveStubbedResults::Middleware
+
+            insert_before \
+              Plugins::Service::CanHaveStubbedResults::Middleware,
+              Plugins::Service::CountsStubbedResultsInvocations::Middleware
           end
 
           middlewares :result, scope: :class do
             insert_after \
               Plugins::Common::NormalizesEnv::Middleware,
-              Plugins::Service::CanHaveStubbedResult::Middleware
+              Plugins::Service::CanHaveStubbedResults::Middleware
+
+            insert_before \
+              Plugins::Service::CanHaveStubbedResults::Middleware,
+              Plugins::Service::CountsStubbedResultsInvocations::Middleware
+          end
+
+          class self::Result
+            concerns do
+              use Plugins::Result::CanBeStubbedResult::Concern
+              use Plugins::Result::HasStubbedResultInvocationsCounter::Concern
+            end
+
+            middlewares :initialize do
+              insert_before \
+                Plugins::Result::HasJSendStatusAndAttributes::Middleware,
+                Plugins::Result::HasStubbedResultInvocationsCounter::Middleware
+            end
           end
         end
       end

data/lib/convenient_service/core/aliases.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 module ConvenientService
-  module Core
-    ClassicMiddleware = ::ConvenientService::Core::Entities::ClassicMiddleware
-    ConcernMiddleware = ::ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Middleware
-    MethodChainMiddleware = ::ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middleware
-  end
+  ConcernMiddleware = ::ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Middleware
+
+  MethodClassicMiddleware = ::ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Classic
+  MethodChainMiddleware = ::ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Chain
 end

data/lib/convenient_service/core/concern/class_methods.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Concern
+      module ClassMethods
+        ##
+        # @see ConvenientService::Core::Entities::Config#concerns
+        #
+        # @internal
+        #   NOTE: The instance variable is named `@__convenient_service_config__` intentionally in order to decrease the possibility of accidental redefinition by the end-user.
+        #   NOTE: An `attr_reader` for `@__convenient_service_config__` is NOT created intentionally in order to NOT pollute the end-user class interface.
+        #
+        def concerns(...)
+          (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).concerns(...)
+        end
+
+        ##
+        # @see ConvenientService::Core::Entities::Config#middlewares
+        #
+        # @internal
+        #   NOTE: The instance variable is named `@__convenient_service_config__` intentionally in order to decrease the possibility of accidental redefinition by the end-user.
+        #   NOTE: An `attr_reader` for `@__convenient_service_config__` is NOT created intentionally in order to NOT pollute the end-user class interface.
+        #
+        def middlewares(...)
+          (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).middlewares(...)
+        end
+
+        ##
+        # @return [Boolean] Returns `true` when config is committed, otherwise - `false`.
+        #
+        def has_committed_config?
+          (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).committed?
+        end
+
+        ##
+        # Commits config when called for the first time.
+        # Does nothing for the subsequent calls.
+        #
+        # @param trigger [ConvenientService::Support::UniqueValue]
+        # @return [Boolean] `true` if called for the first time, `false` otherwise (similarly as `Kernel#require`).
+        #
+        # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-require
+        #
+        # @internal
+        #   NOTE: The instance variable is named `@__convenient_service_config__` intentionally in order to decrease the possibility of accidental redefinition by the end-user.
+        #   NOTE: An `attr_reader` for `@__convenient_service_config__` is NOT created intentionally in order to NOT pollute the end-user class interface.
+        #
+        def commit_config!(trigger: ConvenientService::Core::Constants::Triggers::USER)
+          (@__convenient_service_config__ ||= Entities::Config.new(klass: self)).commit!(trigger: trigger)
+            .tap { ConvenientService.logger.debug { "[Core] Committed config for `#{self}` | Triggered by `.commit_config!(trigger: #{trigger.inspect})` " } }
+        end
+
+        ##
+        # @internal
+        #   TODO: Create `def uncommit_config` that raises an explanatory exception why the "uncommitment" is NOT possible (because Ruby can NOT "uninclude" modules).
+        ##
+
+        ##
+        # @param args [Array<Object>]
+        # @param kwargs [Hash{Symbol => Object}]
+        # @param block [Proc, nil]
+        # @return [Object] Can be any type.
+        #
+        def new(*args, **kwargs, &block)
+          has_committed_config? ? super : method_missing(:new, *args, **kwargs, &block)
+        end
+
+        private
+
+        ##
+        # @see https://thoughtbot.com/blog/always-define-respond-to-missing-when-overriding
+        # @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)
+          return true if singleton_class.method_defined?(method_name)
+          return true if concerns.class_method_defined?(method_name)
+
+          if include_private
+            return true if singleton_class.private_method_defined?(method_name)
+            return true if concerns.private_class_method_defined?(method_name)
+          end
+
+          false
+        end
+
+        ##
+        # Commits config. In other words, includes `concerns` into the mixing class.
+        # If `method` is still NOT defined, raises `NoMethodError`, otherwise - retries to call the `method`.
+        #
+        # @param method [Symbol]
+        # @param args [Array<Object>]
+        # @param kwargs [Hash{Symbol => Object}]
+        # @param block [Proc, nil]
+        # @return [void]
+        #
+        # @note Config commitment via a missing class method is very common. Convenient Service Standard config does that by `.new`, `.result` and `.step` most of the time.
+        #
+        # @internal
+        #   IMPORTANT: `method_missing` MUST be thread-safe.
+        #
+        #   NOTE: `__send__` is used instead of `Support::SafeMethod` intentionally, since checking whether a method is defined is performed earlier by `Utils::Module.class_method_defined?`.
+        #
+        #   TODO: Include `method` into trigger metadata.
+        #
+        def method_missing(method, *args, **kwargs, &block)
+          commit_config!(trigger: Constants::Triggers::CLASS_METHOD_MISSING)
+
+          return super unless Utils::Module.class_method_defined?(self, method, public: true, protected: false, private: false)
+
+          return super if middlewares(method, scope: :class).defined_without_super_method?
+
+          ConvenientService.logger.debug { "[Core] Committed config for `#{self}` | Triggered by `method_missing` | Method: `.#{method}`" }
+
+          __send__(method, *args, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/concern/instance_methods.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Concern
+      module InstanceMethods
+        ##
+        # @return [void]
+        #
+        # @internal
+        #   NOTE: required by `.new` in `ClassMethods`.
+        #
+        def initialize(...)
+        end
+
+        private
+
+        ##
+        # @see https://thoughtbot.com/blog/always-define-respond-to-missing-when-overriding
+        # @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)
+          return true if self.class.method_defined?(method_name)
+          return true if self.class.concerns.instance_method_defined?(method_name)
+
+          if include_private
+            return true if self.class.private_method_defined?(method_name)
+            return true if self.class.concerns.private_instance_method_defined?(method_name)
+          end
+
+          false
+        end
+
+        ##
+        # Commits config. In other words, includes `concerns` into the mixing class.
+        # If `method` is still NOT defined, raises `NoMethodError`, otherwise - retries to call the `method`.
+        #
+        # @param method [Symbol]
+        # @param args [Array<Object>]
+        # @param kwargs [Hash{Symbol => Object}]
+        # @param block [Proc, nil]
+        # @return [void]
+        #
+        # @note Config commitment via a missing instance method is very rare. It is only possible when an instance is created without calling `.new` on a class.
+        #
+        # @internal
+        #   IMPORTANT: `method_missing` MUST be thread-safe.
+        #
+        #   NOTE: `__send__` is used instead of `Support::SafeMethod` intentionally, since checking whether a method is defined is performed earlier by `Utils::Module.instance_method_defined?`.
+        #
+        #   TODO: Include `method` into trigger metadata.
+        #
+        def method_missing(method, *args, **kwargs, &block)
+          self.class.commit_config!(trigger: Constants::Triggers::INSTANCE_METHOD_MISSING)
+
+          return super unless Utils::Module.instance_method_defined?(self.class, method, public: true, protected: false, private: false)
+
+          return super if self.class.middlewares(method, scope: :instance).defined_without_super_method?
+
+          ConvenientService.logger.debug { "[Core] Committed config for `#{self.class}` | Triggered by `method_missing` | Method: `##{method}`" }
+
+          __send__(method, *args, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/core/concern.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "concern/instance_methods"
+require_relative "concern/class_methods"
+
+module ConvenientService
+  module Core
+    module Concern
+      include Support::Concern
+
+      included do |entity_class|
+        ##
+        # NOTE: Currently this aliasing is tested indirectly by `HasConstructor`.
+        #
+        # TODO: Direct test when `have_alias_method` starts to support classes.
+        #
+        entity_class.singleton_class.alias_method :new_without_commit_config, :new
+
+        entity_class.include InstanceMethods
+
+        entity_class.extend ClassMethods
+      end
+    end
+  end
+end

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

@@ -35,7 +35,7 @@ module ConvenientService
               return unless method_missing_trigger_valid?
               return if method_missing_commits_counter_incremented?
 
-              raise Errors::TooManyCommitsFromMethodMissing.new(config: config)
+              raise Exceptions::TooManyCommitsFromMethodMissing.new(config: config)
             end
 
             ##
@@ -49,7 +49,7 @@ module ConvenientService
             # @return [Boolean]
             #
             def method_missing_commits_counter_incremented?
-              Utils::Object.memoize_including_falsy_values(self, :@method_missing_commits_counter_incremented) { config.method_missing_commits_counter.bincrement }
+              Utils.memoize_including_falsy_values(self, :@method_missing_commits_counter_incremented) { config.method_missing_commits_counter.bincrement }
             end
 
             ##

data/lib/convenient_service/core/entities/config/entities/concerns/entities/middleware/commands/cast_middleware.rb

@@ -28,9 +28,9 @@ module ConvenientService
                     # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Middleware, nil]
                     #
                     def call
-                      if other.instance_of?(Class) && other < Entities::Middleware
+                      if other.instance_of?(::Class) && other < Entities::Middleware
                         cast_middleware(other)
-                      elsif other.instance_of?(Module)
+                      elsif other.instance_of?(::Module)
                         cast_module(other)
                       end
                     end

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

@@ -24,6 +24,7 @@ module ConvenientService
                   ##
                   # @internal
                   #   TODO: Why regular `include Support::AbstractMethod` does NOT work?.
+                  #   NOTE: That is probably happening since the `included` block is evaluated once per hierarchy.
                   #
                   extend Support::AbstractMethod::ClassMethods
 

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/cast_caller.rb

@@ -47,9 +47,9 @@ module ConvenientService
 
                       case hash[:scope]
                       when :instance
-                        Caller.new(prefix: Caller::INSTANCE_PREFIX)
+                        Caller.new(prefix: Constants::INSTANCE_PREFIX)
                       when :class
-                        Caller.new(prefix: Caller::CLASS_PREFIX)
+                        Caller.new(prefix: Constants::CLASS_PREFIX)
                       end
                     end
 

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/concern/instance_methods.rb

@@ -49,10 +49,17 @@ module ConvenientService
                     end
 
                     ##
-                    # @return [Hash]
+                    # @return [Hash{Symbol => Object}]
                     #
                     def to_kwargs
-                      {prefix: prefix}
+                      to_arguments.kwargs
+                    end
+
+                    ##
+                    # @return [ConvenientService::Support::Arguments]
+                    #
+                    def to_arguments
+                      Support::Arguments.new(prefix: prefix)
                     end
                   end
                 end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/constants.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "concern/instance_methods"
+require_relative "concern/class_methods"
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              class Caller
+                module Constants
+                  INSTANCE_PREFIX = "self.class."
+
+                  CLASS_PREFIX = ""
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -2,6 +2,7 @@
 
 require_relative "caller/commands"
 require_relative "caller/concern"
+require_relative "caller/constants"
 
 module ConvenientService
   module Core
@@ -11,9 +12,6 @@ module ConvenientService
           class MethodMiddlewares
             module Entities
               class Caller
-                INSTANCE_PREFIX = "self.class."
-                CLASS_PREFIX = ""
-
                 include Concern
               end
             end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/container/concern/instance_methods.rb

@@ -37,7 +37,7 @@ module ConvenientService
                     # @return [UnboundMethod, nil]
                     #
                     def super_method_defined?(method_name)
-                      Utils::Bool.to_bool(resolve_unbound_super_method(method_name))
+                      Utils.to_bool(resolve_unbound_super_method(method_name))
                     end
 
                     ##
@@ -148,10 +148,17 @@ module ConvenientService
                     end
 
                     ##
-                    # @return [Hash]
+                    # @return [Hash{Symbol => Object}]
                     #
                     def to_kwargs
-                      {klass: klass}
+                      to_arguments.kwargs
+                    end
+
+                    ##
+                    # @return [ConvenientService::Support::Arguments]
+                    #
+                    def to_arguments
+                      Support::Arguments.new(klass: klass)
                     end
                   end
                 end