convenient_service 0.19.1 → 0.20.0

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
     class Cache
@@ -17,6 +22,34 @@ module ConvenientService
               end
             end
 
+            ##
+            # @!attribute [r] store
+            #   @return [Object]
+            #
+            attr_reader :store
+
+            ##
+            # @!attribute [r] default
+            #   @return [Object] Can be any type.
+            #
+            attr_reader :default
+
+            ##
+            # @note `parent` is only present when cache is scoped.
+            #
+            # @!attribute [r] parent
+            #   @return [ConvenientService::Support::Cache::Entities::Caches::Base, nil]
+            #
+            attr_reader :parent
+
+            ##
+            # @note `key` is only present when cache is scoped.
+            #
+            # @!attribute [r] key
+            #   @return [ConvenientService::Support::Cache::Entities::Key, Object]
+            #
+            attr_reader :key
+
             ##
             # @return [Boolean]
             #
@@ -53,9 +86,32 @@ module ConvenientService
             abstract_method :clear
 
             ##
+            # @return [ConvenientService::Support::Cache::Enitities::Caches::Base]
+            #
+            abstract_method :scope
+
+            ##
+            # @return [ConvenientService::Support::Cache::Enitities::Caches::Base]
+            #
+            abstract_method :scope!
+
+            ##
+            # @return [Object] Can be any type.
+            #
+            abstract_method :default=
+
+            ##
+            # @param store [Object] Can be any type.
+            # @param default [Object] Can be any type.
+            # @param parent [ConvenientService::Support::Cache::Entities::Caches::Base, nil]
+            # @param key [ConvenientService::Support::Cache::Entities::Key, Object]
             # @return [void]
             #
-            def initialize
+            def initialize(store: nil, default: nil, parent: nil, key: nil)
+              @store = store
+              @default = default
+              @parent = parent
+              @key = key
             end
 
             ##
@@ -75,6 +131,16 @@ module ConvenientService
               read(...)
             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.get(key)` and `cache.read(key)` in RSpec.
+            #
+            def get(...)
+              read(...)
+            end
+
             ##
             # @return [Object] Can be any type.
             #
@@ -86,14 +152,13 @@ module ConvenientService
             end
 
             ##
-            # @param key [Object] Can be any type.
-            # @return [ConvenientService::Support::Cache::Entities::Caches::Base]
+            # @return [Object] Can be any type.
             #
             # @internal
-            #   TODO: What to do if `scope` was called accidentally? Currently, its `key` will NOT be garbage-collected.
+            #   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.set(key, value)` and `cache.write(key, value)` in RSpec.
             #
-            def scope(key)
-              fetch(key) { self.class.new }
+            def set(...)
+              write(...)
             end
 
             ##
@@ -107,6 +172,22 @@ module ConvenientService
 
               true
             end
+
+            private
+
+            ##
+            # @return [void]
+            #
+            def save_self_as_scope_in_parent!
+              parent&.fetch(key) { self }
+            end
+
+            ##
+            # @return [void]
+            #
+            def delete_self_as_scope_in_parent!
+              parent&.delete(key)
+            end
           end
         end
       end

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
     class Cache
@@ -7,17 +12,18 @@ module ConvenientService
         module Caches
           class Hash < Caches::Base
             ##
+            # @param store [Hash{Object => Object}]
             # @return [void]
             #
-            def initialize(hash = {})
-              @hash = hash
+            def initialize(store: {}, **kwargs)
+              super(store: ::Hash.new(kwargs[:default]).update(store), **kwargs)
             end
 
             ##
-            # @return [Hash{Object => Object}]
+            # @return [Symbol]
             #
-            def store
-              hash
+            def backend
+              Constants::Backends::HASH
             end
 
             ##
@@ -27,7 +33,7 @@ module ConvenientService
             #   https://ruby-doc.org/core-2.7.0/Hash.html#method-i-empty-3F
             #
             def empty?
-              hash.empty?
+              store.empty?
             end
 
             ##
@@ -38,7 +44,7 @@ module ConvenientService
             #   https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-exist-3F
             #
             def exist?(key)
-              hash.has_key?(key)
+              store.has_key?(key)
             end
 
             ##
@@ -49,7 +55,7 @@ module ConvenientService
             #   https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-read
             #
             def read(key)
-              hash[key]
+              store[key]
             end
 
             ##
@@ -61,7 +67,9 @@ module ConvenientService
             #   https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-write
             #
             def write(key, value)
-              hash[key] = value
+              save_self_as_scope_in_parent!
+
+              store[key] = value
             end
 
             ##
@@ -73,9 +81,11 @@ module ConvenientService
             #   https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-fetch
             #
             def fetch(key, &block)
-              return hash[key] unless block
+              return store[key] unless block
 
-              hash.fetch(key) { hash[key] = yield }
+              save_self_as_scope_in_parent!
+
+              store.fetch(key) { store[key] = yield }
             end
 
             ##
@@ -86,25 +96,63 @@ module ConvenientService
             #   https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-delete
             #
             def delete(key)
-              hash.delete(key)
+              value = store.delete(key)
+
+              delete_self_as_scope_in_parent! if store.empty?
+
+              value
             end
 
             ##
             # @return [ConvenientService::Support::Cache::Entities::Caches::Hash]
             #
             def clear
-              hash.clear
+              store.clear
 
               self
             end
 
-            private
+            ##
+            # Creates a scoped cache. Parent cache is modified on the first write to the scoped cache.
+            #
+            # @param key [Object] Can be any type.
+            # @param backed_by [Symbol]
+            # @param default [Object] Can be any type.
+            # @return [ConvenientService::Support::Cache::Entities::Caches::Base]
+            #
+            # @internal
+            #   TODO: Add specs for `default` option transfer.
+            #
+            def scope(key, backed_by: backend, default: self.default)
+              store.fetch(key) { Support::Cache.backed_by(backed_by).new(default: default, parent: self, key: key) }
+            end
 
             ##
-            # @!attribute [r] hash
-            #   @return [Hash]
+            # Creates a scoped cache. Parent cache is modified immediately.
             #
-            attr_reader :hash
+            # @param key [Object] Can be any type.
+            # @param backed_by [Symbol]
+            # @param default [Object] Can be any type.
+            # @return [ConvenientService::Support::Cache::Entities::Caches::Base]
+            #
+            # @internal
+            #   TODO: Add specs for `default` option transfer.
+            #
+            def scope!(key, backed_by: backend, default: self.default)
+              store.fetch(key) { store[key] = Support::Cache.backed_by(backed_by).new(default: default, parent: self, key: key) }
+            end
+
+            ##
+            # @param value [Object] Can be any type.
+            # @return [Object] Can be any type.
+            #
+            def default=(value)
+              save_self_as_scope_in_parent!
+
+              store.default = value
+
+              @default = value
+            end
           end
         end
       end

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

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
-require_relative "array/entities"
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
 
 module ConvenientService
   module Support
@@ -11,12 +14,19 @@ module ConvenientService
             ##
             # @return [void]
             #
-            def initialize(array = [])
+            def initialize(...)
               super
 
               @lock = ::Mutex.new
             end
 
+            ##
+            # @return [Symbol]
+            #
+            def backend
+              Constants::Backends::THREAD_SAFE_ARRAY
+            end
+
             ##
             # @return [Boolean]
             #
@@ -67,13 +77,25 @@ module ConvenientService
             end
 
             ##
-            # @internal
-            #   `scope` method from parent delegates to thread-safe `fetch`, that is why child `scope` method does NOT require additional synchronization.
+            # @return [ConvenientService::Support::Cache::Entities::Caches::Array]
             #
-            # def scope(...)
-            #   # ...
-            # end
+            def scope(...)
+              @lock.synchronize { super }
+            end
+
             ##
+            # @return [ConvenientService::Support::Cache::Entities::Caches::Array]
+            #
+            def scope!(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @return [Object] Can be any type.
+            #
+            def default=(...)
+              @lock.synchronize { super }
+            end
 
             ##
             # @note NOT thread-safe.

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Support
+    class Cache
+      module Entities
+        module Caches
+          class ThreadSafeHash < Caches::Hash
+            ##
+            # @return [void]
+            #
+            def initialize(...)
+              super
+
+              @lock = ::Mutex.new
+            end
+
+            ##
+            # @return [Symbol]
+            #
+            def backend
+              Constants::Backends::THREAD_SAFE_HASH
+            end
+
+            ##
+            # @return [Boolean]
+            #
+            def empty?(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @return [Boolean]
+            #
+            def exist?(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @return [Object] Can be any type.
+            #
+            def read(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @return [Object] Can be any type.
+            #
+            def write(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @return [Object] Can be any type.
+            #
+            def fetch(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @return [Object] Can be any type.
+            #
+            def delete(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @return [ConvenientService::Support::Cache::Entities::Caches::Array]
+            #
+            def clear(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @return [ConvenientService::Support::Cache::Entities::Caches::Array]
+            #
+            def scope(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @return [ConvenientService::Support::Cache::Entities::Caches::Array]
+            #
+            def scope!(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @return [Object] Can be any type.
+            #
+            def default=(...)
+              @lock.synchronize { super }
+            end
+
+            ##
+            # @note NOT thread-safe.
+            #
+            # def ==(other)
+            #   # ...
+            # end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "caches/base"
 
 require_relative "caches/array"
 require_relative "caches/hash"
 
 require_relative "caches/thread_safe_array"
+require_relative "caches/thread_safe_hash"

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
     class Cache
@@ -19,7 +24,7 @@ module ConvenientService
 
           ##
           # @param other [Object] Can be any type.
-          # @return [Boolean]
+          # @return [Boolean, nil]
           #
           def ==(other)
             return unless other.instance_of?(self.class)
@@ -33,47 +38,62 @@ module ConvenientService
 
           ##
           # @param other [Object] Can be any type.
-          # @return [Boolean]
+          # @return [Boolean, nil]
           #
           # @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"
+          #   IMPORTANT: Do NOT delegate to `==` from `eql?`. When user overrides `==` then it can break `eql?`.
+          #   - https://shopify.engineering/implementing-equality-in-ruby
+          #   - https://github.com/ruby/ruby/blob/v3_3_0/hash.c#L3719
+          #   - https://belighted.com/blog/overriding-equals-equals
           #
-          #   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/
+          #   NOTE: Check specs to clearly understand when exactly Ruby calls `eql?`.
           #
           def eql?(other)
             return unless other.instance_of?(self.class)
 
-            hash == other.hash
+            return false if args != other.args
+            return false if kwargs != other.kwargs
+            return false if block&.source_location != other.block&.source_location
+
+            true
           end
 
           ##
           # @internal
-          #   NOTE: hash is overridden to treat blocks that were defined at the same location as equal.
+          #   NOTE: `#hash` is overridden to treat blocks that are 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
+          #
+          #   IMPORTANT: `Key` instances are used as Ruby hash keys. `#hash` is overridden in order to avoid the following case:
+          #
+          #     map = {}
+          #
+          #     ##
+          #     # 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
+          #
+          #     map[first_key] = "value"
+          #
+          #     map[second_key]
+          #     # => nil # This happens since keys have different hash numbers (`first_key.hash == second_key.hash` returns `false`).
+          #
+          #   NOTE: Ruby hash(map) and `Object#hash` are not the same things.
+          #   - https://github.com/ruby/ruby/blob/v3_3_0/hash.c#L3719
+          #   - https://shopify.engineering/implementing-equality-in-ruby
+          #
+          #   IMPORTANT: Delegate to `Array#hash` to calculate complex hash number. It is efficient and has lower probability of collision. Any custom hashing requires too much deep thinking.
+          #   - https://shopify.engineering/implementing-equality-in-ruby
+          #   - https://ruby-doc.org/core-2.7.1/Array.html#method-i-hash
+          #
+          #   NOTE: Common way to implement hash.
+          #   - https://shopify.engineering/implementing-equality-in-ruby
           #
           def hash
-            [args, kwargs, block&.source_location].hash
+            [self.class, args, kwargs, block&.source_location].hash
           end
 
           protected
@@ -92,7 +112,7 @@ module ConvenientService
 
           ##
           # @!attribute [r] block
-          #   @return [Proc]
+          #   @return [Proc, nil]
           #
           attr_reader :block
         end

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

@@ -1,4 +1,9 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "entities/caches"
 require_relative "entities/key"

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
     class Cache
@@ -11,7 +16,7 @@ module ConvenientService
           #
           def initialize_with_kwargs(backend:)
             message = <<~TEXT
-              Backend `#{backend}` is NOT supported.
+              Backend `#{backend.inspect}` is NOT supported.
 
               Supported backends are #{printable_backends}.
             TEXT
@@ -25,7 +30,7 @@ module ConvenientService
           # @return [String]
           #
           def printable_backends
-            Constants::Backends::ALL.map { |backend| "`:#{backend}`" }.join(", ")
+            Constants::Backends::ALL.map { |backend| "`#{backend.inspect}`" }.join(", ")
           end
         end
       end

data/lib/convenient_service/support/cache.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "cache/constants"
 require_relative "cache/entities"
 require_relative "cache/exceptions"
@@ -9,17 +14,26 @@ module ConvenientService
     class Cache
       class << self
         ##
-        # @param backend [Symbol]
         # @return [ConvenientService::Support::Cache::Entities::Caches::Base]
         #
-        def create(backend: Constants::Backends::HASH)
+        def new(...)
+          backed_by(Constants::Backends::DEFAULT).new(...)
+        end
+
+        ##
+        # @param backend [Symbol]
+        # @return [Class<ConvenientService::Support::Cache::Entities::Caches::Base>]
+        #
+        def backed_by(backend)
           case backend
           when Constants::Backends::ARRAY
-            Entities::Caches::Array.new
+            Entities::Caches::Array
           when Constants::Backends::HASH
-            Entities::Caches::Hash.new
+            Entities::Caches::Hash
           when Constants::Backends::THREAD_SAFE_ARRAY
-            Entities::Caches::ThreadSafeArray.new
+            Entities::Caches::ThreadSafeArray
+          when Constants::Backends::THREAD_SAFE_HASH
+            Entities::Caches::ThreadSafeHash
           else
             ::ConvenientService.raise Exceptions::NotSupportedBackend.new(backend: backend)
           end