convenient_service 0.17.0 → 0.19.0

data/lib/convenient_service/support/middleware/stack_builder.rb

@@ -18,6 +18,9 @@ module ConvenientService
         #
         # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L43
         #
+        # @internal
+        #   TODO: Direct specs.
+        #
         def initialize(opts = {}, &block)
           super
 
@@ -27,10 +30,41 @@ module ConvenientService
           self.stack = opts[:stack] if opts.has_key?(:stack)
         end
 
+        ##
+        # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+        # @param args [Array<Object>]
+        # @param block [Proc, nil]
+        # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
+        #
+        # @internal
+        #   TODO: Rewrite middleware backend. Consider to use `Array` descendant?
+        #
+        def unshift(middleware, *args, &block)
+          stack.unshift([middleware, args, block])
+
+          self
+        end
+
+        ##
+        # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
+        #
+        alias_method :prepend, :unshift
+
+        ##
+        # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
+        #
+        # @internal
+        #   TODO: Direct specs.
+        #
+        alias_method :remove, :delete
+
         ##
         # @param other [ConvenientService::Support::Middleware::StackBuilder, Object]
         # @return [Boolean, nil]
         #
+        # @internal
+        #   TODO: Direct specs.
+        #
         def ==(other)
           return unless other.instance_of?(self.class)
 
@@ -56,6 +90,9 @@ module ConvenientService
         ##
         # @return [ConvenientService::Support::Middleware::StackBuilder]
         #
+        # @internal
+        #   TODO: Direct specs.
+        #
         def dup
           self.class.new(
             ##

data/lib/convenient_service/support/never_reach_here.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class NeverReachHere < ::ConvenientService::Exception
+      ##
+      # @param extra_message [String]
+      # @return [void]
+      #
+      def initialize_with_kwargs(extra_message:)
+        message = <<~TEXT
+          The code that was supposed to be unreachable was executed.
+
+          #{extra_message}
+        TEXT
+
+        initialize(message)
+      end
+    end
+  end
+end

data/lib/convenient_service/support/thread_safe_counter.rb

@@ -2,6 +2,7 @@
 
 module ConvenientService
   module Support
+    ##
     # @internal
     #   NOTE: Mutex and Semaphore docs.
     #   - https://ruby-doc.org/core-2.7.0/Mutex.html

data/lib/convenient_service/support/unique_value.rb

@@ -42,6 +42,9 @@ module ConvenientService
       # @param other [Object] Can be any type.
       # @return [Boolean]
       #
+      # @internal
+      #   TODO: What to do in case unique value is used as hash key? See `ConveninetService::Support::Cache::Entities::Key`.
+      #
       def eql?(other)
         self == other
       end

data/lib/convenient_service/support/value.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class Value
+      ##
+      # @!attribute [r] label
+      #   @return [String]
+      #
+      attr_reader :label
+
+      ##
+      # @param label [String]
+      # @return [void]
+      #
+      def initialize(label = default_label)
+        @label = label
+      end
+
+      ##
+      # @param other [Object] Can be any type.
+      # @return [Boolean]
+      #
+      def ==(other)
+        return unless other.instance_of?(self.class)
+
+        label == other.label
+      end
+
+      ##
+      # @param other [Object] Can be any type.
+      # @return [Boolean]
+      #
+      def ===(other)
+        self == other
+      end
+
+      ##
+      # @param other [Object] Can be any type.
+      # @return [Boolean]
+      #
+      def eql?(other)
+        return unless other.instance_of?(self.class)
+
+        hash == other.hash
+      end
+
+      ##
+      # @return [Integer]
+      #
+      # @internal
+      #   IMPORTANT: What to do with collisions?
+      #
+      def hash
+        label.hash
+      end
+
+      ##
+      # @return [String]
+      #
+      def inspect
+        return default_label if label.nil?
+        return default_label if label.empty?
+
+        label
+      end
+
+      private
+
+      ##
+      # @return [String]
+      #
+      def default_label
+        "value"
+      end
+    end
+  end
+end

data/lib/convenient_service/support.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "support/value"
 require_relative "support/unique_value"
 
 require_relative "support/not_passed"
 require_relative "support/undefined"
+require_relative "support/never_reach_here"
 
 require_relative "support/concern"
 
@@ -18,10 +20,8 @@ require_relative "support/counter"
 require_relative "support/delegate"
 require_relative "support/dependency_container"
 require_relative "support/finite_loop"
-require_relative "support/gems"
+require_relative "support/method_parameters"
 require_relative "support/middleware"
 require_relative "support/raw_value"
-require_relative "support/ruby"
 require_relative "support/safe_method"
 require_relative "support/thread_safe_counter"
-require_relative "support/version"

data/lib/convenient_service/utils/array/find_last.rb

@@ -6,7 +6,7 @@ module ConvenientService
       class FindLast < Support::Command
         ##
         # @!attribute [r] array
-        #   @return [Array]
+        #   @return [Array, Enumerable]
         #
         attr_reader :array
 
@@ -17,7 +17,7 @@ module ConvenientService
         attr_reader :block
 
         ##
-        # @param array [Array]
+        # @param array [Array, Enumerable]
         # @param block [Proc, nil]
         # @return [void]
         #
@@ -29,8 +29,13 @@ module ConvenientService
         ##
         # @return [Object] Can be any type.
         #
+        # @note Works with custom `Enumerable` objects.
+        # @see https://ruby-doc.org/core-2.7.0/Enumerable.html
+        #
         def call
-          array.reverse.find(&block)
+          array.reverse_each { |item| return item if block.call(item) }
+
+          nil
         end
       end
     end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Object
+      class GetOwnMethod < Support::Command
+        ##
+        # @!attribute [r] object
+        #   @return [Object] Can be any type.
+        #
+        attr_reader :object
+
+        ##
+        # @!attribute [r] method_name
+        #   @return [Symbol, String]
+        #
+        attr_reader :method_name
+
+        ##
+        # @!attribute [r] private
+        #   @return [Boolean]
+        #
+        attr_reader :private
+
+        ##
+        # @param object [Object] Can be any type.
+        # @param method_name [Symbol, String]
+        # @param private [Boolean]
+        #
+        def initialize(object, method_name, private: false)
+          @object = object
+          @method_name = method_name
+          @private = private
+        end
+
+        ##
+        # @return [Class]
+        #
+        # @internal
+        #   NOTE: `own_method.bind(object).call` is logically the same as `own_method.bind_call(object)`.
+        #   - 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 call
+          own_method = Utils::Module.get_own_instance_method(object.class, method_name, private: private)
+
+          return unless own_method
+
+          own_method.bind(object)
+        end
+      end
+    end
+  end
+end

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

@@ -33,7 +33,7 @@ module ConvenientService
         # @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)
+          object.remove_instance_variable(ivar_name) if object.instance_variable_defined?(ivar_name)
         end
       end
     end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Object
+      ##
+      # Returns `nil` when `object` does NOT respond to `method`.
+      # Otherwise it calls `method` on `object` and returns its value.
+      # If calling `method` on `object` raises an exception, it is rescued and `nil` is returned.
+      # Only `StandardError` exceptions are rescued.
+      # Uses `__send__` under the hood.
+      #
+      # @note `ArgumentError` is `StandardError` descendant, so it is also rescued. It is up to the client code to ensure that valid arguments are passed.
+      # @see https://ruby-doc.org/core-2.7.0/BasicObject.html#method-i-__send__
+      # @see https://ruby-doc.org/core-2.7.0/Object.html#method-i-respond_to-3F
+      # @see https://ruby-doc.org/core-2.7.0/StandardError.html
+      # @see https://ruby-doc.org/core-2.7.0/ArgumentError.html
+      #
+      class SafeSend < Support::Command
+        ##
+        # @!attribute [r] object
+        #   @return [Object] Can be any type.
+        #
+        attr_reader :object
+
+        ##
+        # @!attribute [r] method
+        #   @return [String, Symbol]
+        #
+        attr_reader :method
+
+        ##
+        # @!attribute [r] args
+        #   @return [Array<Object>]
+        #
+        attr_reader :args
+
+        ##
+        # @!attribute [r] kwargs
+        #   @return [Hash{Symbol => Object}]
+        #
+        attr_reader :kwargs
+
+        ##
+        # @!attribute [r] block
+        #   @return [Proc, nil]
+        #
+        attr_reader :block
+
+        ##
+        # @param object [Object] Can be any type.
+        # @param method [String, Symbol]
+        # @param args [Array<Object>]
+        # @param kwargs [Hash{Symbol => Object}]
+        # @param block [Proc, nil]
+        #
+        def initialize(object, method, *args, **kwargs, &block)
+          @object = object
+          @method = method
+          @args = args
+          @kwargs = kwargs
+          @block = block
+        end
+
+        ##
+        # @return [Object] Can be any type.
+        #
+        # @internal
+        #   NOTE: `true` in `respond_to?(method, true)` means to look for protected and private methods as well.
+        #   - https://ruby-doc.org/core-2.7.0/Object.html#method-i-respond_to-3F
+        #
+        def call
+          return unless object.respond_to?(method, true)
+
+          begin
+            object.__send__(method, *args, **kwargs, &block)
+          rescue
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/object.rb

@@ -2,10 +2,12 @@
 
 require_relative "object/clamp_class"
 require_relative "object/duck_class"
+require_relative "object/get_own_method"
 require_relative "object/instance_variable_delete"
 require_relative "object/instance_variable_fetch"
 require_relative "object/memoize_including_falsy_values"
 require_relative "object/resolve_type"
+require_relative "object/safe_send"
 
 module ConvenientService
   module Utils
@@ -53,6 +55,20 @@ module ConvenientService
           MemoizeIncludingFalsyValues.call(...)
         end
 
+        ##
+        # @example
+        #   object = Object.new.tap { |object| object.instance_eval { self.class.attr_reader :foo } }
+        #
+        #   ConvenientService::Utils::Object.own_method(object, :foo)
+        #   # => #<Method: #<Object:0x0000555e524252d8>.foo() ...>
+        #
+        #   ConvenientService::Utils::Object.own_method(object, :puts)
+        #   # => nil
+        #
+        def own_method(...)
+          GetOwnMethod.call(...)
+        end
+
         ##
         # @example
         #   ConvenientService::Utils::Object.resolve_type("foo")
@@ -60,6 +76,14 @@ module ConvenientService
         def resolve_type(...)
           ResolveType.call(...)
         end
+
+        ##
+        # @example
+        #   ConvenientService::Utils::Object.safe_send(object, method, *args, **kwargs, &block)
+        #
+        def safe_send(...)
+          SafeSend.call(...)
+        end
       end
     end
   end

data/lib/convenient_service/utils/string/enclose.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+##
+# @example Common usage.
+#   ConvenientService::Utils::String::Enclose.call("foo", "_")
+#   # => "_foo_"
+#
+#   ConvenientService::Utils::String::Enclose.call("", "_")
+#   # => "_"
+#
+#   ConvenientService::Utils::String::Enclose.call(nil, "_")
+#   # => "_"
+#
+module ConvenientService
+  module Utils
+    module String
+      class Enclose < Support::Command
+        ##
+        # @!attribute [r] string
+        #   @return [String]
+        #
+        attr_reader :string
+
+        ##
+        # @!attribute [r] char
+        #   @return [String]
+        #
+        attr_reader :char
+
+        ##
+        # @param string [String]
+        # @param char [String]
+        # @return [void]
+        #
+        def initialize(string, char)
+          @string = string
+          @char = char
+        end
+
+        ##
+        # @return [String]
+        #
+        def call
+          return char unless string
+          return char if string.empty?
+
+          "#{char}#{string}#{char}"
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/string.rb

@@ -2,6 +2,7 @@
 
 require_relative "string/camelize"
 require_relative "string/demodulize"
+require_relative "string/enclose"
 require_relative "string/split"
 require_relative "string/truncate"
 
@@ -17,6 +18,10 @@ module ConvenientService
           Demodulize.call(...)
         end
 
+        def enclose(...)
+          Enclose.call(...)
+        end
+
         def split(...)
           Split.call(...)
         end

data/lib/convenient_service/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConvenientService
-  VERSION = "0.17.0"
+  VERSION = "0.19.0"
 end

data/lib/convenient_service.rb

@@ -35,6 +35,12 @@ require_relative "convenient_service/service"
 #
 require_relative "convenient_service/feature"
 
+##
+# @internal
+#   Convenient Service Commands.
+#
+require_relative "convenient_service/commands"
+
 ##
 # @internal
 #   Convenient Service Aliases.
@@ -43,6 +49,71 @@ require_relative "convenient_service/aliases"
 
 module ConvenientService
   class << self
+    ##
+    # @api private
+    #
+    # @return [Boolean]
+    #
+    def debug?
+      ::ENV["CONVENIENT_SERVICE_DEBUG"] == "true"
+    end
+
+    ##
+    # Checks whether a class is a service class.
+    #
+    # @api public
+    #
+    # @param service_class [Object] Can be any type.
+    # @return [Boolean]
+    #
+    # @example Simple usage.
+    #   class Service
+    #     include ConvenientService::Standard::Config
+    #
+    #     def result
+    #       success
+    #     end
+    #   end
+    #
+    #   ConvenientService.service_class?(Service)
+    #   # => true
+    #
+    #   ConvenientService.service_class?(42)
+    #   # => false
+    #
+    def service_class?(service_class)
+      Commands::IsServiceClass[service_class: service_class]
+    end
+
+    ##
+    # Checks whether an object is a service instance.
+    #
+    # @api public
+    #
+    # @param service [Object] Can be any type.
+    # @return [Boolean]
+    #
+    # @example Simple usage.
+    #   class Service
+    #     include ConvenientService::Standard::Config
+    #
+    #     def result
+    #       success
+    #     end
+    #   end
+    #
+    #   service = Service.new
+    #
+    #   ConvenientService.service?(service)
+    #   # => true
+    #
+    #   ConvenientService.service?(42)
+    #   # => false
+    #
+    def service?(service)
+      Commands::IsService[service: service]
+    end
+
     ##
     # @api public
     #
@@ -79,6 +150,18 @@ module ConvenientService
       @examples_root ||= ::Pathname.new(::File.join(root, "lib", "convenient_service", "examples"))
     end
 
+    ##
+    # Returns Convenient Service Specs folder.
+    # For example, it may return something like: `/Users/user/.asdf/installs/ruby/2.7.0/lib/ruby/gems/2.7.0/gems/convenient_service-0.16.0/spec`.
+    #
+    # @api private
+    #
+    # @return [Pathname]
+    #
+    def spec_root
+      @spec_root ||= ::Pathname.new(::File.join(root, "spec"))
+    end
+
     ##
     # @api public
     #
@@ -105,6 +188,8 @@ module ConvenientService
     #   - https://github.com/jruby/jruby/blob/9.4.0.0/core/src/main/java/org/jruby/RubyKernel.java#L881
     #   - https://github.com/ruby/spec/blob/master/core/kernel/raise_spec.rb#L5
     #
+    #   TODO: Create a custom Rubocop cop to statically catch all places where plain `raise` is used.
+    #
     if Dependencies.ruby.jruby?
       def raise(original_exception)
         ::Kernel.raise original_exception