convenient_service 0.5.0 → 0.7.0

data/lib/convenient_service/service/plugins/has_result_steps/middleware.rb

@@ -5,6 +5,9 @@ module ConvenientService
     module Plugins
       module HasResultSteps
         class Middleware < Core::MethodChainMiddleware
+          ##
+          # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
+          #
           def next(...)
             return chain.next(...) if entity.steps.none?
 
@@ -13,11 +16,22 @@ module ConvenientService
 
           private
 
+          ##
+          # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
+          #
           def last_step
-            ##
-            # TODO: Use `entity.steps.find { |step| step.result.tap { |result| entity.step(result) }.not_success? }` for callbacks.
-            #
-            @last_step ||= entity.steps.find(&:not_success?) || entity.steps.last
+            @last_step ||= entity.steps.find.with_index { |step, index| not_success?(step, index) } || entity.steps.last
+          end
+
+          ##
+          # @return [ConvenientService::Service::Plugins::HasResultSteps::Entities::Step]
+          #
+          # @internal
+          #   NOTE: `entity.step(index)` is used as a hook (callbacks trigger).
+          #   IMPORTANT: `step` status MUST be checked before triggering callbacks.
+          #
+          def not_success?(step, index)
+            step.not_success?.tap { entity.step(index) }
           end
         end
       end

data/lib/convenient_service/services/run_method_in_organizer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Services
+    class RunMethodInOrganizer
+      ##
+      # @internal
+      #   TODO: Reuse parent config?
+      #
+      include Configs::Standard
+
+      attr_reader :method_name, :organizer, :kwargs
+
+      def initialize(method_name:, organizer:, **kwargs)
+        @method_name = method_name
+        @organizer = organizer
+        @kwargs = kwargs
+      end
+
+      def result
+        ##
+        # NOTE: `kwargs` are intentionally NOT passed, since all the corresponding methods are available inside `organizer.__send__(method_name)` body.
+        #
+        organizer.__send__(method_name)
+      end
+    end
+  end
+end

data/lib/convenient_service/services/run_own_method_in_organizer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Services
+    class RunOwnMethodInOrganizer
+      module Errors
+        class MethodForStepIsNotDefined < ConvenientService::Error
+          def initialize(service_class:, method_name:)
+            message = <<~TEXT
+              Service #{service_class} tries to use `#{method_name}` method in a step, but it NOT defined.
+
+              Did you forget to define it?
+            TEXT
+
+            super(message)
+          end
+        end
+      end
+
+      ##
+      # @internal
+      #   TODO: Reuse parent config?
+      #
+      include Configs::Standard
+
+      attr_reader :method_name, :organizer, :kwargs
+
+      def initialize(method_name:, organizer:, **kwargs)
+        @method_name = method_name
+        @organizer = organizer
+        @kwargs = kwargs
+      end
+
+      def result
+        raise Errors::MethodForStepIsNotDefined.new(service_class: organizer.class, method_name: method_name) unless own_method
+
+        ##
+        # NOTE: `kwargs` are intentionally NOT passed, since all the corresponding methods are available inside `own_method` body.
+        #
+        own_method.call
+      end
+
+      private
+
+      ##
+      # @return [Method, nil]
+      #
+      # @internal
+      #   TODO: A possible bottleneck. Should be removed if receives negative feedback.
+      #
+      #   NOTE: `own_method.bind(organizer).call` is logically the same as `own_method.bind_call(organizer)`.
+      #   - https://ruby-doc.org/core-2.7.1/UnboundMethod.html#method-i-bind_call
+      #   - https://blog.saeloun.com/2019/10/17/ruby-2-7-adds-unboundmethod-bind_call-method.html
+      #
+      def own_method
+        method = Utils::Module.get_own_instance_method(organizer.class, method_name, private: true)
+
+        return unless method
+
+        method.bind(organizer)
+      end
+    end
+  end
+end

data/lib/convenient_service/{service/plugins/has_result_method_steps/services.rb → services.rb}

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
 
-require_relative "services/method_step_config"
 require_relative "services/run_own_method_in_organizer"
 require_relative "services/run_method_in_organizer"

data/lib/convenient_service/support/arguments/null_arguments.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class Arguments
+      ##
+      # @api private
+      #
+      class NullArguments < Support::Arguments
+        ##
+        # @return [void]
+        #
+        def initialize
+          @args = []
+          @kwargs = {}
+          @block = nil
+        end
+
+        ##
+        # @return [Boolean]
+        #
+        def null_arguments?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/arguments.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "arguments/null_arguments"
+
+module ConvenientService
+  module Support
+    class Arguments
+      ##
+      # @!attribute [r] args
+      #   @return [Array]
+      #
+      attr_reader :args
+
+      ##
+      # @!attribute [r] kwargs
+      #   @return [Hash]
+      #
+      attr_reader :kwargs
+
+      ##
+      # @!attribute [r] block
+      #   @return [Proc]
+      #
+      attr_reader :block
+
+      ##
+      # @param args [Array]
+      # @param kwargs [Hash]
+      # @param block [Proc]
+      # @return [void]
+      #
+      def initialize(*args, **kwargs, &block)
+        @args = args
+        @kwargs = kwargs
+        @block = block
+      end
+
+      class << self
+        ##
+        # @return [ConvenientService::Support::Arguments::NullArguments]
+        #
+        def null_arguments
+          @null_arguments ||= Support::Arguments::NullArguments.new
+        end
+      end
+
+      ##
+      # @return [Boolean]
+      #
+      def null_arguments?
+        false
+      end
+
+      ##
+      # @return [Booleam]
+      #
+      def any?
+        return true if args.any?
+        return true if kwargs.any?
+        return true if block
+
+        false
+      end
+
+      ##
+      # @return [Booleam]
+      #
+      def none?
+        !any?
+      end
+
+      ##
+      # @param other [Object]
+      # @return [Boolean]
+      #
+      def ==(other)
+        return unless other.instance_of?(self.class)
+
+        return false if args != other.args
+        return false if kwargs != other.kwargs
+        return false if block != other.block
+
+        true
+      end
+    end
+  end
+end

data/lib/convenient_service/support/copyable.rb

@@ -20,8 +20,12 @@ module ConvenientService
       #   NOTE: This method is NOT likely to be ever changed, that is why inline logic is preferred over command classes in this particular case.
       #
       def copy(overrides: {})
-        overrides[:args] ||= {}
-        overrides[:kwargs] ||= {}
+        defaults = {args: {}, kwargs: {}}
+
+        ##
+        # IMPORTANT: Do not mutate `overrides`.
+        #
+        overrides = defaults.merge(overrides)
 
         ##
         # TODO: Refactor runtime `respond_to?`. Investigate before refactoring.

data/lib/convenient_service/support/dependency_container/commands/assert_valid_scope.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Commands
+        class AssertValidScope < Support::Command
+          ##
+          # @!attribute [r] scope
+          #   @return [Object]
+          #
+          attr_reader :scope
+
+          ##
+          # @param scope [Object]
+          # @return [void]
+          #
+          def initialize(scope:)
+            @scope = scope
+          end
+
+          ##
+          # @return [Module]
+          #
+          def call
+            raise Errors::InvalidScope.new(scope: scope) unless Constants::SCOPES.include?(scope)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/dependency_container/commands/import_method.rb

@@ -5,6 +5,8 @@ module ConvenientService
     module DependencyContainer
       module Commands
         class ImportMethod < Support::Command
+          include Support::Delegate
+
           ##
           # @!attribute [r] importing_module
           #   @return [Module]
@@ -12,41 +14,31 @@ module ConvenientService
           attr_reader :importing_module
 
           ##
-          # @!attribute [r] exporting_module
-          #   @return [Module]
+          # @!attribute [r] exported_method
+          #   @return [ConvenientService::Support::DependencyContainer::Method]
           #
-          attr_reader :exporting_module
+          attr_reader :exported_method
 
           ##
-          # @!attribute [r] method
-          #   @return [ConvenientService::Support::DependencyContainer::Method]
+          # @!attribute [r] prepend
+          #   @return [Boolean]
           #
-          attr_reader :method
+          attr_reader :prepend
 
           ##
           # @!attribute [r] scope
           #   @return [Symbol]
           #
-          attr_reader :scope
-
-          ##
-          # @!attribute [r] prepend
-          #   @return [Boolean]
-          #
-          attr_reader :prepend
+          delegate :scope, to: :exported_method
 
           ##
           # @param importing_module [Module]
-          # @param exporting_module [Module]
-          # @param method [ConvenientService::Support::DependencyContainer::Method]
-          # @param scope [:instance, :class]
+          # @param exported_method [ConvenientService::Support::DependencyContainer::Method]
           # @param prepend [Boolean]
           #
-          def initialize(importing_module:, exporting_module:, method:, scope:, prepend:)
+          def initialize(importing_module:, exported_method:, prepend:)
             @importing_module = importing_module
-            @exporting_module = exporting_module
-            @method = method
-            @scope = scope
+            @exported_method = exported_method
             @prepend = prepend
           end
 
@@ -56,9 +48,7 @@ module ConvenientService
           def call
             import imported_scoped_methods
 
-            method.define_in_module!(imported_scoped_methods)
-
-            method
+            exported_method.define_in_module!(imported_scoped_methods)
           end
 
           private

data/lib/convenient_service/support/dependency_container/commands.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 
+require_relative "commands/assert_valid_scope"
 require_relative "commands/create_methods_module"
 require_relative "commands/import_method"

data/lib/convenient_service/support/dependency_container/constants.rb

@@ -4,8 +4,10 @@ module ConvenientService
   module Support
     module DependencyContainer
       module Constants
-        INSTANCE_SCOPE = :instance
-        CLASS_SCOPE = :class
+        SCOPES = [
+          INSTANCE_SCOPE = :instance,
+          CLASS_SCOPE = :class
+        ]
 
         DEFAULT_SCOPE = Constants::INSTANCE_SCOPE
         DEFAULT_PREPEND = false

data/lib/convenient_service/support/dependency_container/entities/method.rb

@@ -80,9 +80,9 @@ module ConvenientService
             #   - Same methods are redefined.
             #   - In contrast, same namespaces are always reused.
             #
-            innermost_namespace.define_method(method.name, &method.body)
+            innermost_namespace.define_method(name, &body)
 
-            method
+            self
           end
 
           ##
@@ -101,13 +101,6 @@ module ConvenientService
 
           private
 
-          ##
-          # @return [ConvenientService::Support::DependencyContainer::Entities::Method]
-          #
-          def method
-            self
-          end
-
           ##
           # @return [Array<String>]
           #

data/lib/convenient_service/support/dependency_container/entities/namespace_collection.rb

@@ -13,15 +13,6 @@ module ConvenientService
             @namespaces = namespaces
           end
 
-          ##
-          #
-          #
-          def define_namespace(namespace)
-            namespaces << namespace
-
-            define_singleton_method(namespace.name) { namespace.body.call }
-          end
-
           ##
           # @param name [String, Symbol]
           # @return [ConvenientService::Support::DependencyContainer::Entities::Namespace, nil]

data/lib/convenient_service/support/dependency_container/errors.rb

@@ -4,6 +4,31 @@ module ConvenientService
   module Support
     module DependencyContainer
       module Errors
+        class InvalidScope < ConvenientService::Error
+          ##
+          # @param scope [Object]
+          # @return [void]
+          #
+          def initialize(scope:)
+            message = <<~TEXT
+              Scope `#{scope.inspect}` is NOT valid.
+
+              Valid options are #{printable_valid_scopes}.
+            TEXT
+
+            super(message)
+          end
+
+          private
+
+          ##
+          # @return [String]
+          #
+          def printable_valid_scopes
+            Constants::SCOPES.map { |scope| "`:#{scope}`" }.join(", ")
+          end
+        end
+
         class NotExportableModule < ConvenientService::Error
           ##
           # @param mod [Module]
@@ -31,7 +56,7 @@ module ConvenientService
             message = <<~TEXT
               Module `#{mod}` does NOT export method `#{method_name}` with `#{method_scope}` scope.
 
-              Did you forget to export if from `#{mod}`? For example:
+              Did you forget to export it from `#{mod}`? For example:
 
               module #{mod}
                 export #{method_name}, scope: :#{method_scope} do |*args, **kwargs, &block|

data/lib/convenient_service/support/dependency_container/export.rb

@@ -13,7 +13,15 @@ module ConvenientService
           # @param body [Proc]
           # @return [ConvenientService::Support::DependencyContainer::Entities::Method]
           #
+          # @internal
+          #   NOTE: `export` does NOT accept `prepend` kwarg intentionally.
+          #   It is done to follow "the Ruby way".
+          #   You won't ever see a module in Ruby that contains methods for `include` and `prepend` at the same time.
+          #   So why `export` should allow to do it?
+          #
           def export(full_name, scope: Constants::DEFAULT_SCOPE, &body)
+            Commands::AssertValidScope.call(scope: scope)
+
             Entities::Method.new(full_name: full_name, scope: scope, body: body).tap { |method| exported_methods << method }
           end
 

data/lib/convenient_service/support/dependency_container/import.rb

@@ -15,13 +15,15 @@ module ConvenientService
           # @return [ConvenientService::Support::DependencyContainer::Entities::Method]
           #
           def import(full_name, from:, scope: Constants::DEFAULT_SCOPE, prepend: Constants::DEFAULT_PREPEND)
+            Commands::AssertValidScope.call(scope: scope)
+
             raise Errors::NotExportableModule.new(mod: from) unless Utils::Module.include_module?(from, DependencyContainer::Export)
 
             method = from.exported_methods.find_by(full_name: full_name, scope: scope)
 
             raise Errors::NotExportedMethod.new(method_name: full_name, method_scope: scope, mod: from) unless method
 
-            Commands::ImportMethod.call(importing_module: self, exporting_module: from, method: method, scope: scope, prepend: prepend)
+            Commands::ImportMethod.call(importing_module: self, exported_method: method, prepend: prepend)
           end
         end
       end

data/lib/convenient_service/support/not_passed.rb

@@ -2,6 +2,8 @@
 
 module ConvenientService
   module Support
-    NOT_PASSED = ::Object.new
+    NOT_PASSED = ::Object.new.tap do |object|
+      object.define_singleton_method(:inspect) { "not_passed" }
+    end
   end
 end

data/lib/convenient_service/support/version/null_version.rb

@@ -11,6 +11,13 @@ module ConvenientService
       #   - https://avdi.codes/null-objects-and-falsiness/
       #
       class NullVersion
+        ##
+        # @return [Boolean]
+        #
+        def null_version?
+          true
+        end
+
         ##
         # @return [nil]
         #

data/lib/convenient_service/support/version.rb

@@ -24,10 +24,17 @@ module ConvenientService
         # @return [ConvenientService::Support::Version::NullVersion]
         #
         def null_version
-          @null_version ||= NullVersion.new
+          @null_version ||= Support::Version::NullVersion.new
         end
       end
 
+      ##
+      # @return [Boolean]
+      #
+      def null_version?
+        false
+      end
+
       ##
       # @return [Gem::Version, nil]
       #
@@ -52,6 +59,9 @@ module ConvenientService
 
       private
 
+      ##
+      # @return [String]
+      #
       attr_reader :value
 
       ##

data/lib/convenient_service/support.rb

@@ -4,6 +4,7 @@ require_relative "support/not_passed"
 require_relative "support/concern"
 
 require_relative "support/abstract_method"
+require_relative "support/arguments"
 require_relative "support/cache"
 require_relative "support/castable"
 require_relative "support/command"

data/lib/convenient_service/utils/object/instance_variable_delete.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+##
+#
+#
+module ConvenientService
+  module Utils
+    module Object
+      class InstanceVariableDelete < Support::Command
+        ##
+        # @!attribute [r] object
+        #   @return [Object]
+        #
+        attr_reader :object
+
+        ##
+        # @!attribute [r] ivar_name
+        #   @return [Symbol, String]
+        #
+        attr_reader :ivar_name
+
+        ##
+        # @param object [Object]
+        # @param ivar_name [Symbol]
+        # @return [void]
+        #
+        def initialize(object, ivar_name)
+          @object = object
+          @ivar_name = ivar_name
+        end
+
+        ##
+        # @return [Object] Value of ivar. Can be any type.
+        #
+        def call
+          return object.remove_instance_variable(ivar_name) if object.instance_variable_defined?(ivar_name)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/object/instance_variable_fetch.rb

@@ -6,6 +6,10 @@
 module ConvenientService
   module Utils
     module Object
+      ##
+      # Can be used instead of `return @ivar if defined? @ivar`.
+      # @see https://www.justinweiss.com/articles/4-simple-memoization-patterns-in-ruby-and-one-gem/
+      #
       class InstanceVariableFetch < Support::Command
         ##
         # @!attribute [r] object

data/lib/convenient_service/utils/object.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "object/instance_variable_delete"
 require_relative "object/instance_variable_fetch"
 require_relative "object/resolve_type"
 
@@ -7,6 +8,14 @@ module ConvenientService
   module Utils
     module Object
       class << self
+        ##
+        # @example
+        #   ConvenientService::Utils::Object.instance_variable_delete("abc", :@foo)
+        #
+        def instance_variable_delete(...)
+          InstanceVariableDelete.call(...)
+        end
+
         ##
         # @example
         #   ConvenientService::Utils::Object.instance_variable_fetch("abc", :@foo) { :bar }