convenient_service 0.11.0 → 0.12.0

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Commands
+        class AssertValidMethod < Support::Command
+          ##
+          # @!attribute [r] full_name
+          #   @return [String, Symbol]
+          #
+          attr_reader :full_name
+
+          ##
+          # @!attribute [r] scope
+          #   @return [Symbol]
+          #
+          attr_reader :scope
+
+          ##
+          # @!attribute [r] container
+          #   @return [Module]
+          #
+          attr_reader :container
+
+          ##
+          # @param full_name [String, Symbol]
+          # @param scope [Symbol]
+          # @param container[Module]
+          # @return [void]
+          #
+          def initialize(full_name:, scope:, container:)
+            @full_name = full_name
+            @scope = scope
+            @container = container
+          end
+
+          ##
+          # @return [void]
+          # @raise [ConvenientService::Support::DependencyContainer::Errors::NotExportedMethod]
+          #
+          def call
+            raise Errors::NotExportedMethod.new(method_name: full_name, method_scope: scope, mod: container) unless method
+          end
+
+          private
+
+          ##
+          # @return [ConvenientService::Support::DependencyContainer::Entities::Method, nil]
+          #
+          def method
+            container.exported_methods.find_by(full_name: full_name, scope: scope)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,12 +7,12 @@ module ConvenientService
         class AssertValidScope < Support::Command
           ##
           # @!attribute [r] scope
-          #   @return [Object]
+          #   @return [Symbol]
           #
           attr_reader :scope
 
           ##
-          # @param scope [Object]
+          # @param scope [Symbol]
           # @return [void]
           #
           def initialize(scope:)
@@ -20,7 +20,8 @@ module ConvenientService
           end
 
           ##
-          # @return [Module]
+          # @return [void]
+          # @raise [ConvenientService::Support::DependencyContainer::Errors::InvalidScope]
           #
           def call
             raise Errors::InvalidScope.new(scope: scope) unless Constants::SCOPES.include?(scope)

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Commands
+        class DefineEntry < Support::Command
+          ##
+          # @!attribute [r] container
+          #   @return [Module]
+          #
+          attr_reader :container
+
+          ##
+          # @!attribute [r] name
+          #   @return [String, Symbol]
+          #
+          attr_reader :name
+
+          ##
+          # @!attribute [r] body
+          #   @return [Proc]
+          #
+          attr_reader :body
+
+          ##
+          # @param container [Module]
+          # @param name [String, Symbol]
+          # @param body [Proc]
+          #
+          def initialize(container:, name:, body:)
+            @container = container
+            @name = name
+            @body = body
+          end
+
+          ##
+          # @return [String, Symbol]
+          #
+          def call
+            container.define_singleton_method(name, &body)
+
+            name
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "commands/assert_valid_scope"
+require_relative "commands/assert_valid_container"
+require_relative "commands/assert_valid_method"
 require_relative "commands/create_methods_module"
+require_relative "commands/define_entry"
 require_relative "commands/import_method"

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Container
+        include Export
+
+        export :"constants.DEFAULT_SCOPE" do
+          Constants::DEFAULT_SCOPE
+        end
+
+        export :"commands.AssertValidContainer" do
+          Commands::AssertValidContainer
+        end
+
+        export :"commands.AssertValidScope" do
+          Commands::AssertValidScope
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Entry
+        include Support::Concern
+
+        class_methods do
+          ##
+          # @param name [String, Symbol]
+          # @param body [Proc]
+          # @return [String, Symbol]
+          #
+          def entry(name, &body)
+            Commands::DefineEntry.call(container: self, name: name, body: body)
+          end
+        end
+      end
+    end
+  end
+end

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.