convenient_service 0.10.1 → 0.12.0

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

@@ -4,7 +4,7 @@ module ConvenientService
   module Support
     module DependencyContainer
       module Errors
-        class InvalidScope < ConvenientService::Error
+        class InvalidScope < ::ConvenientService::Error
           ##
           # @param scope [Object]
           # @return [void]
@@ -29,7 +29,7 @@ module ConvenientService
           end
         end
 
-        class NotExportableModule < ConvenientService::Error
+        class NotExportableModule < ::ConvenientService::Error
           ##
           # @param mod [Module]
           # @return [void]
@@ -38,14 +38,14 @@ module ConvenientService
             message = <<~TEXT
               Module `#{mod}` can NOT export methods.
 
-              Did you forget to include `ConvenientService::Container.export` into it?
+              Did you forget to include `ConvenientService::DependencyContainer::Export` into it?
             TEXT
 
             super(message)
           end
         end
 
-        class NotExportedMethod < ConvenientService::Error
+        class NotExportedMethod < ::ConvenientService::Error
           ##
           # @param method_name [String]
           # @param method_scope [Symbol]
@@ -69,7 +69,7 @@ module ConvenientService
           end
         end
 
-        class NotModule < ConvenientService::Error
+        class NotModule < ::ConvenientService::Error
           ##
           # @param klass [Class]
           # @return [void]

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

@@ -17,11 +17,11 @@ module ConvenientService
           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)
+            Commands::AssertValidContainer.call(container: from)
 
-            method = from.exported_methods.find_by(full_name: full_name, scope: scope)
+            Commands::AssertValidMethod.call(full_name: full_name, scope: scope, container: from)
 
-            raise Errors::NotExportedMethod.new(method_name: full_name, method_scope: scope, mod: from) unless method
+            method = from.exported_methods.find_by(full_name: full_name, scope: scope)
 
             Commands::ImportMethod.call(importing_module: self, exported_method: method, prepend: prepend)
           end

data/lib/convenient_service/support/dependency_container.rb

@@ -5,5 +5,8 @@ require_relative "dependency_container/constants"
 require_relative "dependency_container/entities"
 require_relative "dependency_container/errors"
 
+require_relative "dependency_container/entry"
 require_relative "dependency_container/export"
 require_relative "dependency_container/import"
+
+require_relative "dependency_container/container"

data/lib/convenient_service/support/finite_loop.rb

@@ -3,10 +3,17 @@
 module ConvenientService
   module Support
     module FiniteLoop
+      ##
+      # @return [Integer]
+      #
       MAX_ITERATION_COUNT = 1_000
 
       module Errors
-        class MaxIterationCountExceeded < ::StandardError
+        class MaxIterationCountExceeded < ::ConvenientService::Error
+          ##
+          # @param limit [Integer]
+          # @return [void]
+          #
           def initialize(limit:)
             message = <<~TEXT
               Max iteration count is exceeded. Current limit is #{limit}.
@@ -18,7 +25,10 @@ module ConvenientService
           end
         end
 
-        class NoBlockGiven < ::StandardError
+        class NoBlockGiven < ::ConvenientService::Error
+          ##
+          # @return [void]
+          #
           def initialize
             message = <<~TEXT
               `finite_loop` always expects a block to be given.
@@ -31,6 +41,31 @@ module ConvenientService
 
       private
 
+      ##
+      # @example Provides `self.finite_loop` in order to have a way to use `finite_loop` without including `ConvenientService::Support::FiniteLoop`.
+      #   ConvenientService::Support::FiniteLoop.finite_loop do |index|
+      #     break if index > 3
+      #   end
+      #
+      module_function
+
+      ##
+      # @param max_iteration_count [Integer]
+      # @param raise_on_exceedance [Boolean]
+      # @param block [Proc, nil]
+      # @return [Object] Can be any type.
+      #
+      # @example
+      #   class Person
+      #     include ConvenientService::Support::FiniteLoop
+      #
+      #     def foo
+      #       finite_loop do |index|
+      #         break if index > 3
+      #       end
+      #     end
+      #   end
+      #
       def finite_loop(max_iteration_count: MAX_ITERATION_COUNT, raise_on_exceedance: true, &block)
         raise Errors::NoBlockGiven.new unless block
 

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

@@ -13,7 +13,7 @@ module ConvenientService
       class StackBuilder < Dependencies::Extractions::RubyMiddleware::Middleware::Builder
         ##
         # @param opts [Hash]
-        # @param block [Proc]
+        # @param block [Proc, nil]
         # @return [void]
         #
         # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L43

data/lib/convenient_service/support/not_passed.rb

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

data/lib/convenient_service/support/ruby.rb

@@ -16,6 +16,37 @@ module ConvenientService
         def version
           @version ||= Support::Version.new(::RUBY_VERSION)
         end
+
+        ##
+        # Returns `true` when JRuby, `false` otherwise.
+        #
+        # @return [Boolean]
+        #
+        # @see https://github.com/rdp/os
+        #
+        # @internal
+        #   NOTE: Gratefully copied from the `os` gem. Version `1.1.4`.
+        #   - https://github.com/rdp/os/blob/v1.1.4/lib/os.rb#L101
+        #
+        #   NOTE: Modified original implementation in order to return a boolean.
+        #
+        def jruby?
+          ::RUBY_PLATFORM.to_s.match?(/java/)
+        end
+
+        ##
+        # Returns `true` when TruffleRuby, `false` otherwise.
+        #
+        # @return [Boolean]
+        #
+        # @internal
+        #   NOTE: Taken from irb testing. May NOT be stable.
+        #
+        #   TODO: Find a confirmation of stability.
+        #
+        def truffleruby?
+          ::RUBY_ENGINE.to_s.match?(/truffleruby/)
+        end
       end
     end
   end

data/lib/convenient_service/support/safe_method.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class SafeMethod
+      ##
+      # @!attribute [r] object
+      #   @return [Object] Can be any type.
+      #
+      attr_reader :object
+
+      ##
+      # @!attribute [r] method
+      #   @return [Symbol, String]
+      #
+      attr_reader :method
+
+      ##
+      # @!attribute [r] default
+      #   @return [Object] Can be any type.
+      #
+      attr_reader :default
+
+      ##
+      # @param object [Object] Can be any type.
+      # @param method [Symbol, String]
+      # @param default [Object, nil] Can be any type.
+      # @return [void]
+      #
+      def initialize(object, method, default: nil)
+        @object = object
+        @method = method
+        @default = default
+      end
+
+      ##
+      # @param args [Array<Object>]
+      # @param kwargs [Hash{Symbol => Object}]
+      # @param block [Proc, nil]
+      # @return [Object] Can be any type.
+      #
+      def call(*args, **kwargs, &block)
+        return default unless method_defined?
+
+        object.__send__(method, *args, **kwargs, &block)
+      end
+
+      private
+
+      ##
+      # @return [Boolean]
+      #
+      def method_defined?
+        Utils::Method.defined?(method, klass, private: true)
+      end
+
+      ##
+      # @return [Class]
+      #
+      def klass
+        @klass ||= Utils::Object.resolve_class(object)
+      end
+    end
+  end
+end

data/lib/convenient_service/support/thread_safe_counter.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    # @internal
+    #   NOTE: Mutex and Semaphore docs.
+    #   - https://ruby-doc.org/core-2.7.0/Mutex.html
+    #   - https://en.wikipedia.org/wiki/Semaphore_(programming)
+    #
+    class ThreadSafeCounter < Support::Counter
+      ##
+      # @see ConvenientService::Support::Counter#current_value=
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   IMPORTANT: The lock is always properly released since it uses ensure under the hood.
+      #   - https://github.com/ruby/ruby/blob/v2_7_0/thread_sync.c#L525
+      #
+      def current_value=(...)
+        @lock.synchronize { super }
+      end
+
+      ##
+      # @see ConvenientService::Support::Counter#increment
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   IMPORTANT: The lock is always properly released since it uses ensure under the hood.
+      #   - https://github.com/ruby/ruby/blob/v2_7_0/thread_sync.c#L525
+      #
+      def increment(...)
+        @lock.synchronize { super }
+      end
+
+      ##
+      # @see ConvenientService::Support::Counter#increment!
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   IMPORTANT: The lock is always properly released since it uses ensure under the hood.
+      #   - https://github.com/ruby/ruby/blob/v2_7_0/thread_sync.c#L525
+      #
+      def increment!(...)
+        @lock.synchronize { super }
+      end
+
+      ##
+      # `bincrement` means boolean increment. Works exactly in the same way as `increment` except returns a boolean value.
+      # If incremented successfully then returns `true`, otherwise - returns `false`.
+      #
+      # @see ConvenientService::Support::Counter#bincrement
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   IMPORTANT: The lock is always properly released since it uses ensure under the hood.
+      #   - https://github.com/ruby/ruby/blob/v2_7_0/thread_sync.c#L525
+      #
+      def bincrement(...)
+        @lock.synchronize { super }
+      end
+
+      ##
+      # @see ConvenientService::Support::Counter#decrement
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   IMPORTANT: The lock is always properly released since it uses ensure under the hood.
+      #   - https://github.com/ruby/ruby/blob/v2_7_0/thread_sync.c#L525
+      #
+      def decrement(...)
+        @lock.synchronize { super }
+      end
+
+      ##
+      # @see ConvenientService::Support::Counter#decrement!
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   IMPORTANT: The lock is always properly released since it uses ensure under the hood.
+      #   - https://github.com/ruby/ruby/blob/v2_7_0/thread_sync.c#L525
+      #
+      def decrement!(...)
+        @lock.synchronize { super }
+      end
+
+      ##
+      # `bdecrement` means boolean decrement. Works exactly in the same way as `decrement` except returns a boolean value.
+      # If decremented successfully then returns `true`, otherwise - returns `false`.
+      #
+      # @see ConvenientService::Support::Counter#bdecrement
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   IMPORTANT: The lock is always properly released since it uses ensure under the hood.
+      #   - https://github.com/ruby/ruby/blob/v2_7_0/thread_sync.c#L525
+      #
+      def bdecrement(...)
+        @lock.synchronize { super }
+      end
+
+      ##
+      # @see ConvenientService::Support::Counter#reset
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      def reset(...)
+        @lock.synchronize { super }
+      end
+    end
+  end
+end

data/lib/convenient_service/support/undefined.rb

@@ -2,8 +2,9 @@
 
 module ConvenientService
   module Support
-    UNDEFINED = ::Object.new.tap do |object|
-      object.define_singleton_method(:inspect) { "undefined" }
-    end
+    ##
+    # @return [ConvenientService::Support::UniqueValue]
+    #
+    UNDEFINED = Support::UniqueValue.new("undefined")
   end
 end

data/lib/convenient_service/support/unique_value.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class UniqueValue
+      ##
+      # @!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]
+      #
+      # @internal
+      #   NOTE: Every single Ruby object responds to `object_id`.
+      #
+      def ==(other)
+        return unless other.instance_of?(self.class)
+
+        object_id == other.object_id
+      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)
+        self == other
+      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
+        "unique_value_#{object_id}"
+      end
+    end
+  end
+end

data/lib/convenient_service/support.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "support/unique_value"
 require_relative "support/not_passed"
 require_relative "support/undefined"
 
@@ -11,6 +12,7 @@ require_relative "support/cache"
 require_relative "support/castable"
 require_relative "support/command"
 require_relative "support/copyable"
+require_relative "support/counter"
 require_relative "support/delegate"
 require_relative "support/dependency_container"
 require_relative "support/finite_loop"
@@ -18,4 +20,6 @@ require_relative "support/gems"
 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/errors.rb

@@ -4,7 +4,7 @@ module ConvenientService
   module Utils
     module Array
       module Errors
-        class NonIntegerIndex < Error
+        class NonIntegerIndex < ::ConvenientService::Error
           def initialize(index:)
             message = <<~TEXT
               Index `#{index.inspect}` is NOT an integer.

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

@@ -18,7 +18,7 @@ module ConvenientService
 
         ##
         # @param array [Array]
-        # @param block [Proc]
+        # @param block [Proc, nil]
         # @return [void]
         #
         def initialize(array, &block)

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

@@ -66,7 +66,7 @@ module ConvenientService
 
         ##
         # @param array [Array]
-        # @param block [Proc]
+        # @param block [Proc, nil]
         # @return [void]
         #
         def initialize(array, &block)

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+##
+# @example
+#   module Musician
+#   end
+#
+#   class Person
+#   end
+#
+#   person = Person.new
+#
+#   ConvenientService::Utils::Object::ResolveClass.call(42)
+#   # => Integer
+#
+#   ConvenientService::Utils::Object::ResolveClass.call("foo")
+#   # => String
+#
+#   ConvenientService::Utils::Object::ResolveClass.call(person)
+#   # => Person
+#
+#   ConvenientService::Utils::Object::ResolveClass.call(Person)
+#   # => #<Class:Person>
+#
+#   ConvenientService::Utils::Object::ResolveClass.call(Musician)
+#   # => #<Class:Musician>
+#
+module ConvenientService
+  module Utils
+    module Object
+      class ResolveClass < Support::Command
+        ##
+        # @!attribute [r] object
+        #   @return [Object] Can be any type.
+        #
+        attr_reader :object
+
+        ##
+        # @param object [Object] Can be any type.
+        #
+        def initialize(object)
+          @object = object
+        end
+
+        ##
+        # @return [Class]
+        #
+        def call
+          return object.singleton_class if object.is_a?(::Module)
+
+          object.class
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/object.rb

@@ -3,6 +3,7 @@
 require_relative "object/instance_variable_delete"
 require_relative "object/instance_variable_fetch"
 require_relative "object/memoize_including_falsy_values"
+require_relative "object/resolve_class"
 require_relative "object/resolve_type"
 
 module ConvenientService
@@ -35,6 +36,14 @@ module ConvenientService
           MemoizeIncludingFalsyValues.call(...)
         end
 
+        ##
+        # @example
+        #   ConvenientService::Utils::Object.resolve_class("foo")
+        #
+        def resolve_class(...)
+          ResolveClass.call(...)
+        end
+
         ##
         # @example
         #   ConvenientService::Utils::Object.resolve_type("foo")

data/lib/convenient_service/version.rb

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

data/lib/convenient_service.rb

@@ -36,6 +36,12 @@ require_relative "convenient_service/configs"
 #
 require_relative "convenient_service/services"
 
+##
+# @internal
+#   Convenient Service Feature.
+#
+require_relative "convenient_service/feature"
+
 ##
 # @internal
 #   Convenient Service Aliases.