convenient_service 0.11.0 → 0.13.0

data/lib/convenient_service/support/cache/entities/key.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class Cache
+      module Entities
+        class Key
+          ##
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil]
+          # @return [void]
+          #
+          def initialize(*args, **kwargs, &block)
+            @args = args
+            @kwargs = kwargs
+            @block = block
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @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&.source_location != other.block&.source_location
+
+            true
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [Boolean]
+          #
+          # @internal
+          #   IMPORTANT: `Key` instances are used as Ruby hash keys.
+          #
+          #   This method is overridden in order to avoid the following case:
+          #
+          #   hash = {}
+          #
+          #   ##
+          #   # Two equal keys in terms of `==`.
+          #   #
+          #   first_key = ConvenientService::Common::Plugins::CachesReturnValue::Entities::Key.new(method: :result, args: [], kwargs: {}, block: nil)
+          #   second_key = ConvenientService::Common::Plugins::CachesReturnValue::Entities::Key.new(method: :result, args: [], kwargs: {}, block: nil)
+          #
+          #   first_key == second_key
+          #   # => true
+          #
+          #   hash[first_key] = "value"
+          #
+          #   hash[second_key]
+          #   # => nil # This happens since keys are not equal in terms of `eql?`.
+          #
+          #   NOTE: Ruby hash and Object#hash are not the same things.
+          #   - https://ruby-doc.org/core-3.1.2/Object.html#method-i-hash
+          #   - https://belighted.com/blog/overriding-equals-equals/
+          #
+          def eql?(other)
+            return unless other.instance_of?(self.class)
+
+            hash == other.hash
+          end
+
+          ##
+          # @internal
+          #   NOTE: hash is overridden to treat blocks that were defined at the same location as equal.
+          #   - https://ruby-doc.org/core-3.1.2/Proc.html#method-i-source_location
+          #   - https://ruby-doc.org/core-3.1.2/Object.html#method-i-hash
+          #
+          def hash
+            [args, kwargs, block&.source_location].hash
+          end
+
+          protected
+
+          ##
+          # @!attribute [r] args
+          #   @return [Array]
+          #
+          attr_reader :args
+
+          ##
+          # @!attribute [r] kwargs
+          #   @return [Hash]
+          #
+          attr_reader :kwargs
+
+          ##
+          # @!attribute [r] block
+          #   @return [Proc]
+          #
+          attr_reader :block
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/cache/entities.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "entities/caches"
+require_relative "entities/key"

data/lib/convenient_service/support/cache/exceptions.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class Cache
+      module Exceptions
+        class NotSupportedBackend < ::ConvenientService::Exception
+          ##
+          # @param backend [Symbol]
+          # @return [void]
+          #
+          def initialize(backend:)
+            message = <<~TEXT
+              Backend `#{backend}` is NOT supported.
+
+              Supported backends are #{printable_backends}.
+            TEXT
+
+            super(message)
+          end
+
+          private
+
+          ##
+          # @return [String]
+          #
+          def printable_backends
+            Constants::Backends::ALL.map { |backend| "`:#{backend}`" }.join(", ")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/cache.rb

@@ -1,157 +1,30 @@
 # frozen_string_literal: true
 
-require_relative "cache/key"
+require_relative "cache/constants"
+require_relative "cache/entities"
+require_relative "cache/exceptions"
 
 module ConvenientService
   module Support
     class Cache
-      ##
-      # @return [void]
-      #
-      def initialize(hash = {})
-        @hash = hash
-      end
-
       class << self
         ##
-        # @return [ConvenientService::Support::Cache::Key]
+        # @param backend [Symbol]
+        # @return [ConvenientService::Support::Cache::Entities::Caches::Base]
         #
-        def keygen(...)
-          Cache::Key.new(...)
+        def create(backend: Constants::Backends::HASH)
+          case backend
+          when Constants::Backends::ARRAY
+            Entities::Caches::Array.new
+          when Constants::Backends::HASH
+            Entities::Caches::Hash.new
+          when Constants::Backends::THREAD_SAFE_ARRAY
+            Entities::Caches::ThreadSafeArray.new
+          else
+            raise Exceptions::NotSupportedBackend.new(backend: backend)
+          end
         end
       end
-
-      ##
-      # @return [Boolean]
-      #
-      # @internal
-      #   https://ruby-doc.org/core-2.7.0/Hash.html#method-i-empty-3F
-      #
-      def empty?
-        hash.empty?
-      end
-
-      ##
-      # @return [Boolean]
-      #
-      # @internal
-      #   https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-exist-3F
-      #
-      def exist?(key)
-        hash.has_key?(key)
-      end
-
-      ##
-      # @return [Object] Can be any type.
-      #
-      # @internal
-      #   https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-read
-      #
-      def read(key)
-        hash[key]
-      end
-
-      ##
-      # @return [Object] Can be any type.
-      #
-      # @internal
-      #   NOTE: `alias_method` is NOT used in order to have an ability to use `allow(cache).to receive(:read).with(key).and_call_original` for both `cache[key]` and `cache.read(key)` in RSpec.
-      #
-      def [](key)
-        read(key)
-      end
-
-      ##
-      # @param key [Object] Can be any type.
-      # @param value [Object] Can be any type.
-      # @return [Object] Can be any type.
-      #
-      # @internal
-      #   https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-write
-      #
-      def write(key, value)
-        hash[key] = value
-      end
-
-      ##
-      # @param key [Object] Can be any type.
-      # @param value [Object] Can be any type.
-      # @return [Object] Can be any type.
-      #
-      # @internal
-      #   NOTE: `alias_method` is NOT used in order to have an ability to use `allow(cache).to receive(:write).with(key, value).and_call_original` for both `cache[key] = value` and `cache.write(key, value)` in RSpec.
-      #
-      def []=(key, value)
-        write(key, value)
-      end
-
-      ##
-      # @param key [Object] Can be any type.
-      # @return [Object] Can be any type.
-      #
-      # @internal
-      #   https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-delete
-      #
-      def delete(key)
-        hash.delete(key)
-      end
-
-      ##
-      # @param key [Object] Can be any type.
-      # @param block [Proc]
-      # @return [Object] Can be any type.
-      #
-      # @internal
-      #   https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-fetch
-      #
-      def fetch(key, &block)
-        return read(key) unless block
-
-        exist?(key) ? read(key) : write(key, block.call)
-      end
-
-      ##
-      # @return [ConvenientService::Support::Cache]
-      #
-      def clear
-        hash.clear
-
-        self
-      end
-
-      ##
-      # @return [ConvenientService::Support::Cache]
-      #
-      def scope(key)
-        fetch(key) { Support::Cache.new }
-      end
-
-      ##
-      # @return [ConvenientService::Support::Cache::Key]
-      #
-      def keygen(...)
-        Cache.keygen(...)
-      end
-
-      ##
-      # @param other [Object] Can be any type.
-      # @return [Boolean]
-      #
-      def ==(other)
-        return unless other.instance_of?(self.class)
-
-        return false if hash != other.hash
-
-        true
-      end
-
-      protected
-
-      ##
-      # @!attribute [r] hash
-      #   @return [Hash]
-      #
-      attr_reader :hash
     end
   end
 end

data/lib/convenient_service/support/castable/{errors.rb → exceptions.rb}

@@ -3,8 +3,8 @@
 module ConvenientService
   module Support
     module Castable
-      module Errors
-        class CastIsNotOverridden < ::StandardError
+      module Exceptions
+        class CastIsNotOverridden < ::ConvenientService::Exception
           def initialize(klass:)
             message = <<~TEXT
               Cast method (.cast) of `#{klass}` is NOT overridden.
@@ -14,7 +14,7 @@ module ConvenientService
           end
         end
 
-        class FailedToCast < ::StandardError
+        class FailedToCast < ::ConvenientService::Exception
           def initialize(other:, klass:)
             message = <<~TEXT
               Failed to cast `#{other.inspect}` into `#{klass}`.

data/lib/convenient_service/support/castable.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "castable/errors"
+require_relative "castable/exceptions"
 
 module ConvenientService
   module Support
@@ -34,7 +34,7 @@ module ConvenientService
         def cast!(other, **options)
           casted = cast(other, **options)
 
-          raise Errors::FailedToCast.new(other: other, klass: self) unless casted
+          raise Exceptions::FailedToCast.new(other: other, klass: self) unless casted
 
           casted
         end

data/lib/convenient_service/support/command.rb

@@ -3,22 +3,61 @@
 module ConvenientService
   module Support
     ##
-    # @abstract Subclass and override {#initialize} and {#call} to implement a Command.
+    # @abstract Subclass and override {#initialize} and {#call} to implement a `Command`.
     #
     class Command
+      module Exceptions
+        class CallIsNotOverridden < ::ConvenientService::Exception
+          def initialize(command:)
+            message = <<~TEXT
+              Call method (#call) of `#{command.class}` is NOT overridden.
+            TEXT
+
+            super(message)
+          end
+        end
+      end
+
       class << self
         ##
-        # TODO: Specs.
+        # @return [Object] Can be any type.
         #
         def call(...)
           new(...).call
         end
+
+        ##
+        # @return [Object] Can be any type.
+        #
+        # @internal
+        #   NOTE: Delegates to `call` instead of aliasing in order to have an ability
+        #   to use the same RSpec stubs for short and usual syntax.
+        #
+        #   For example:
+        #
+        #     allow(Command).to receive(:call).with(:foo).and_call_original
+        #
+        #   works for both `Command.call(:foo)` and `Command[:foo]`.
+        #
+        def [](...)
+          call(...)
+        end
+      end
+
+      ##
+      # @abstract
+      # @return [void]
+      #
+      def initialize(...)
       end
 
       ##
-      # TODO: Specs. Raise error if not overridden.
+      # @abstract
+      # @return [Object] Can be any type.
+      # @raise [ConvenientService::Support::Command::Exceptions::CallIsNotOverridden]
       #
       def call
+        raise Exceptions::CallIsNotOverridden.new(command: self)
       end
     end
   end

data/lib/convenient_service/support/copyable.rb

@@ -19,6 +19,8 @@ module ConvenientService
       #   NOTE: Inline logic instead of private methods is used intentionally in order to NOT pollute the public interface.
       #   NOTE: This method is NOT likely to be ever changed, that is why inline logic is preferred over command classes in this particular case.
       #
+      #   NOTE: The `respond_to` solution was slower by 16%. Check this file history to review the previous implementation. Use the `empty_service` benchmark to compare.
+      #
       def copy(overrides: {})
         defaults = {args: {}, kwargs: {}}
 
@@ -27,32 +29,14 @@ module ConvenientService
         #
         overrides = defaults.merge(overrides)
 
-        ##
-        # TODO: Refactor runtime `respond_to?`. Investigate before refactoring.
-        #
         args =
-          if respond_to?(:to_args)
-            case overrides[:args]
-            when ::Array
-              overrides[:args]
-            when ::Hash
-              Utils::Array.merge(to_args, overrides[:args])
-            end
-          else
-            []
+          case overrides[:args]
+          when ::Array then overrides[:args]
+          when ::Hash then Utils::Array.merge(to_arguments.args, overrides[:args])
           end
 
-        kwargs =
-          if respond_to?(:to_kwargs)
-            to_kwargs.merge(overrides[:kwargs])
-          else
-            {}
-          end
-
-        block =
-          if respond_to?(:to_block)
-            overrides[:block] || to_block
-          end
+        kwargs = to_arguments.kwargs.merge(overrides[:kwargs])
+        block = overrides[:block] || to_arguments.block
 
         self.class.new(*args, **kwargs, &block)
       end

data/lib/convenient_service/support/counter.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    ##
+    # @internal
+    #   NOTE: `return` exits from the enclosing method. `break` from the iterator method. `next` from the block.
+    #   - https://github.com/ruby/spec/blob/master/language/return_spec.rb
+    #   - https://github.com/ruby/spec/blob/master/language/break_spec.rb
+    #   - https://github.com/ruby/spec/blob/master/language/next_spec.rb
+    #   - https://stackoverflow.com/a/1402764/12201472
+    #
+    class Counter
+      module Exceptions
+        class ValueAfterIncrementIsGreaterThanMaxValue < ::ConvenientService::Exception
+          ##
+          # @param n [Integer]
+          # @param current_value [Integer]
+          # @param max_value [Integer]
+          # @return [void]
+          #
+          def initialize(n:, current_value:, max_value:)
+            message = <<~TEXT
+              Value after increment by `#{n}` is greater than the max value.
+
+              Current value is `#{current_value}`.
+
+              Max value is `#{max_value}`.
+            TEXT
+
+            super(message)
+          end
+        end
+
+        class ValueAfterDecrementIsLowerThanMinValue < ::ConvenientService::Exception
+          ##
+          # @param n [Integer]
+          # @param current_value [Integer]
+          # @param min_value [Integer]
+          # @return [void]
+          #
+          def initialize(n:, current_value:, min_value:)
+            message = <<~TEXT
+              Value after decrement by `#{n}` is lower than the min value.
+
+              Current value is `#{current_value}`.
+
+              Min value is `#{min_value}`.
+            TEXT
+
+            super(message)
+          end
+        end
+      end
+
+      ##
+      # @!attribute [r] initial_value
+      #   @return [Integer]
+      #
+      attr_reader :initial_value
+
+      ##
+      # @!attribute [rw] current_value
+      #   @return [Integer]
+      #
+      attr_accessor :current_value
+
+      ##
+      # @!attribute [r] min_value
+      #   @return [Integer, Float::INFINITY]
+      #
+      attr_reader :min_value
+
+      ##
+      # @!attribute [r] max_value
+      #   @return [Integer, Float::INFINITY]
+      #
+      attr_reader :max_value
+
+      ##
+      # @param initial_value [Integer]
+      # @param min_value [Integer, -::Float::Infinity]
+      # @param max_value [Integer, Float::Infinity]
+      # @return [void]
+      #
+      # @note Do NOT rely on the fact that `min_value` and `max_value` are almost always `Integer` instances since they are set to `-Float::INFINITY` and `Float::INFINITY` by default.
+      # @note `Float::INFINITY` and `Integer` are just contextual ducks, NOT full ducks. For example, `Float::INFINITY.to_i` raises `FloatDomainError`.
+      #
+      def initialize(initial_value: 0, min_value: -::Float::INFINITY, max_value: ::Float::INFINITY)
+        @initial_value = initial_value
+        @current_value = initial_value
+        @min_value = min_value
+        @max_value = max_value
+      end
+
+      ##
+      # @param n [Integer]
+      # @return [Integer]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   NOTE: The name is inspired by Redis and Concurrent Ruby.
+      #   - https://redis.io/commands/incr/
+      #   - https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/AtomicFixnum.html#increment-instance_method
+      #
+      def increment(n = 1)
+        return @current_value if @current_value + n > @max_value
+
+        @current_value += n
+      end
+
+      ##
+      # @param n [Integer]
+      # @return [Integer]
+      # @raise [ConvenientService::Support::ThreadSafeCounter::Exceptions::ValueAfterIncrementIsGreaterThanMaxValue]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   NOTE: The name is inspired by Rails.
+      #   - https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save
+      #   - https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save-21
+      #
+      def increment!(n = 1)
+        raise Exceptions::ValueAfterIncrementIsGreaterThanMaxValue.new(n: n, current_value: @current_value, max_value: @max_value) if @current_value + n > @max_value
+
+        @current_value += n
+      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`.
+      #
+      # @param n [Integer]
+      # @return [Boolean]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      def bincrement(n = 1)
+        return false if @current_value + n > @max_value
+
+        @current_value += n
+
+        true
+      end
+
+      ##
+      # @param n [Integer]
+      # @return [Integer]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   NOTE: The name is inspired by Redis and Concurrent Ruby.
+      #   - https://redis.io/commands/decr/
+      #   - https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/AtomicFixnum.html#decrement-instance_method
+      #
+      def decrement(n = 1)
+        return @current_value if @current_value - n < @min_value
+
+        @current_value -= n
+      end
+
+      ##
+      # @param n [Integer]
+      # @return [Integer]
+      # @raise [ConvenientService::Support::ThreadSafeCounter::Exceptions::ValueAfterDecrementIsLowerThanMinValue]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   NOTE: The name is inspired by Rails.
+      #   - https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save
+      #   - https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save-21
+      #
+      def decrement!(n = 1)
+        raise Exceptions::ValueAfterDecrementIsLowerThanMinValue.new(n: n, current_value: @current_value, min_value: @min_value) if @current_value - n < @min_value
+
+        @current_value -= n
+      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`.
+      #
+      # @param n [Integer]
+      # @return [Boolean]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      def bdecrement(n = 1)
+        return false if @current_value - n < @min_value
+
+        @current_value -= n
+
+        true
+      end
+
+      ##
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      def reset
+        @current_value = @initial_value
+      end
+    end
+  end
+end