safe_memoize 0.9.0 → 1.1.0

data/lib/safe_memoize/public_methods.rb

@@ -1,19 +1,36 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Public instance methods mixed into every class that prepends {SafeMemoize}.
   module PublicMethods
+    # Returns +true+ if the given call is currently cached (and not expired).
+    #
+    # Always returns +false+ when a block is provided, because block-taking methods
+    # cannot be safely keyed by arguments alone.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array] positional arguments used to look up the entry
+    # @param kwargs [Hash] keyword arguments used to look up the entry
+    # @return [Boolean]
     def memoized?(method_name, *args, **kwargs, &block)
       return false if block
 
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+      cache_key = compute_cache_key(method_name, args, kwargs)
 
       with_memo_lock do
         memo_cache_hit?(cache_key)
       end
     end
 
+    # Returns the number of seconds until the cached entry expires.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Float] seconds remaining (may be 0 if already expired)
+    # @return [nil] if the entry has no TTL or is not cached
     def memo_ttl_remaining(method_name, *args, **kwargs)
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+      cache_key = compute_cache_key(method_name, args, kwargs)
 
       with_memo_lock do
         record = memo_cache_record(cache_key)
@@ -27,6 +44,10 @@ module SafeMemoize
       end
     end
 
+    # Returns the number of live cached entries for a method (or all methods).
+    #
+    # @param method_name [Symbol, String, nil] when omitted, counts all methods
+    # @return [Integer]
     def memo_count(*method_name)
       scoped_method = safe_memo_scoped_method(method_name)
 
@@ -35,6 +56,13 @@ module SafeMemoize
       end
     end
 
+    # Returns metadata hashes describing each cached entry.
+    #
+    # Each hash contains +:args+, +:kwargs+ (or +:custom_key+ for custom-keyed entries),
+    # and +:method+ when no +method_name+ filter is applied.
+    #
+    # @param method_name [Symbol, String, nil] when omitted, returns entries for all methods
+    # @return [Array<Hash>]
     def memo_keys(*method_name)
       scoped_method = safe_memo_scoped_method(method_name)
 
@@ -43,6 +71,12 @@ module SafeMemoize
       end
     end
 
+    # Returns metadata hashes including the cached value for each entry.
+    #
+    # Each hash contains all fields from {#memo_keys} plus +:value+.
+    #
+    # @param method_name [Symbol, String, nil] when omitted, returns entries for all methods
+    # @return [Array<Hash>]
     def memo_values(*method_name)
       scoped_method = safe_memo_scoped_method(method_name)
 
@@ -51,42 +85,90 @@ module SafeMemoize
       end
     end
 
+    # Registers a hook that fires on every cache hit.
+    #
+    # @yield [cache_key, record] called synchronously inside the cache lock
+    # @yieldparam cache_key [Array] the internal cache key
+    # @yieldparam record [Hash] the cache record (+:value+, +:expires_at+, +:cached_at+)
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
     def on_memo_expire(&block)
       raise ArgumentError, "block required" unless block
 
       register_memo_hook(:on_expire, &block)
     end
 
+    # Registers a hook that fires when an LRU eviction occurs.
+    #
+    # @yield [cache_key, record]
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
     def on_memo_evict(&block)
       raise ArgumentError, "block required" unless block
 
       register_memo_hook(:on_evict, &block)
     end
 
+    # Registers a hook that fires on every cache hit.
+    #
+    # @yield [cache_key, record]
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
     def on_memo_hit(&block)
       raise ArgumentError, "block required" unless block
 
       register_memo_hook(:on_hit, &block)
     end
 
+    # Registers a hook that fires on every cache miss (before the value is stored).
+    #
+    # @yield [cache_key, record]
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
     def on_memo_miss(&block)
       raise ArgumentError, "block required" unless block
 
       register_memo_hook(:on_miss, &block)
     end
 
+    # Registers a hook that fires whenever a value is written to the cache
+    # (miss, {#warm_memo}, or {#load_memo}).
+    #
+    # @yield [cache_key, record]
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
     def on_memo_store(&block)
       raise ArgumentError, "block required" unless block
 
       register_memo_hook(:on_store, &block)
     end
 
+    # Removes all registered hooks, or only hooks of a specific type.
+    #
+    # @param hook_type [Symbol, nil] one of +:on_hit+, +:on_miss+, +:on_store+,
+    #   +:on_expire+, +:on_evict+; when +nil+ all hooks are cleared
+    # @return [void]
     def clear_memo_hooks(hook_type = nil)
       with_memo_lock do
         _clear_memo_hooks(hook_type)
       end
     end
 
+    # Pre-populates a cache entry with the value returned by the block without
+    # calling the memoized method itself.
+    #
+    # Useful for warming caches from a serialized snapshot or an external source.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array] positional arguments that identify the cache slot
+    # @param ttl [Numeric, nil] optional expiry for the warmed entry
+    # @param kwargs [Hash] keyword arguments that identify the cache slot
+    # @yield [] must return the value to store
+    # @return [Object] the value returned by the block
+    # @raise [ArgumentError] if no block is given
+    #
+    # @example
+    #   obj.warm_memo(:find, 42) { User.new(id: 42, name: "cached") }
     def warm_memo(method_name, *args, ttl: nil, **kwargs, &block)
       raise ArgumentError, "block required" unless block
 
@@ -104,6 +186,17 @@ module SafeMemoize
       value
     end
 
+    # Calls the memoized method for each argument set and caches all results.
+    #
+    # Equivalent to calling the method for each arg set individually, but expressed
+    # as a single call for clarity.
+    #
+    # @param method_name [Symbol, String]
+    # @param arg_sets [Array<Array>] each element is an argument list for one call
+    # @return [Array] cached values in input order
+    #
+    # @example
+    #   obj.memo_preload(:find, [1], [2], [3])
     def memo_preload(method_name, *arg_sets)
       method_name = method_name.to_sym
       arg_sets.map do |args|
@@ -111,6 +204,11 @@ module SafeMemoize
       end
     end
 
+    # Exports live cache entries as a plain hash suitable for serialization.
+    #
+    # @param method_name [Symbol, String, nil] when given, exports only entries for
+    #   that method; when +nil+, exports all methods
+    # @return [Hash] mapping cache keys to their cached values (expired entries excluded)
     def dump_memo(method_name = nil)
       method_name = method_name&.to_sym
 
@@ -122,6 +220,14 @@ module SafeMemoize
       end
     end
 
+    # Restores cache entries from a snapshot produced by {#dump_memo}.
+    #
+    # Existing entries are not cleared; snapshot keys are merged in.
+    # Each restored entry fires the +:on_store+ hook.
+    #
+    # @param snapshot [Hash] a hash previously returned by {#dump_memo}
+    # @return [nil]
+    # @raise [ArgumentError] if +snapshot+ is not a +Hash+
     def load_memo(snapshot)
       raise ArgumentError, "snapshot must be a Hash" unless snapshot.is_a?(Hash)
 
@@ -137,9 +243,17 @@ module SafeMemoize
       nil
     end
 
+    # Resets the expiry clock on a live cached entry without recomputing its value.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param ttl [Numeric, nil] new TTL to apply; when +nil+, uses the original TTL
+    #   derived from the entry's +cached_at+ and +expires_at+ timestamps
+    # @param kwargs [Hash]
+    # @return [Boolean] +true+ if the entry existed and was touched; +false+ otherwise
     def memo_touch(method_name, *args, ttl: nil, **kwargs)
       method_name = method_name.to_sym
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+      cache_key = compute_cache_key(method_name, args, kwargs)
 
       with_memo_lock do
         cache = memo_cache_or_nil
@@ -162,14 +276,27 @@ module SafeMemoize
       end
     end
 
+    # Clears the cached entry and immediately re-calls the method to populate a
+    # fresh value.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Object] the freshly computed and cached value
     def memo_refresh(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       reset_memo(method_name, *args, **kwargs)
       send(method_name, *args, **kwargs)
     end
 
+    # Returns how many seconds ago the entry was cached, or +nil+ if not cached.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Float, nil]
     def memo_age(method_name, *args, **kwargs)
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+      cache_key = compute_cache_key(method_name, args, kwargs)
 
       with_memo_lock do
         record = memo_cache_record(cache_key)
@@ -182,8 +309,14 @@ module SafeMemoize
       end
     end
 
+    # Returns +true+ if the entry exists but its TTL has elapsed.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Boolean]
     def memo_stale?(method_name, *args, **kwargs)
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+      cache_key = compute_cache_key(method_name, args, kwargs)
 
       with_memo_lock do
         cache = memo_cache_or_nil
@@ -196,6 +329,16 @@ module SafeMemoize
       end
     end
 
+    # Removes one or all cached entries for a method.
+    #
+    # When called with only +method_name+, all entries for that method are cleared.
+    # When called with +method_name+ *and* arguments, only the exact matching entry
+    # is cleared. Each evicted entry fires the +:on_evict+ hook.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array] positional arguments identifying a specific entry
+    # @param kwargs [Hash] keyword arguments identifying a specific entry
+    # @return [void]
     def reset_memo(method_name, *args, **kwargs)
       method_name = method_name.to_sym
 
@@ -215,6 +358,10 @@ module SafeMemoize
       end
     end
 
+    # Clears all cached entries for every method on this instance.
+    # Each evicted entry fires the +:on_evict+ hook.
+    #
+    # @return [void]
     def reset_all_memos
       with_memo_lock do
         if defined?(@__safe_memo_cache__) && @__safe_memo_cache__
@@ -227,6 +374,16 @@ module SafeMemoize
       end
     end
 
+    # Returns a detailed snapshot of a single cached entry, or +nil+ if not cached.
+    #
+    # All reads are performed inside a single mutex hold.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Hash, nil] hash with keys +:cached+, +:value+, +:hits+, +:misses+,
+    #   +:ttl_remaining+, +:age+, +:custom_key+, +:lru_position+; or +nil+ when
+    #   the entry is not present
     def memo_inspect(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       cache_key = compute_cache_key(method_name, args, kwargs)

data/lib/safe_memoize/public_metrics_methods.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Per-instance cache metrics: hit/miss counts and average computation time.
   module PublicMetricsMethods
+    # Returns aggregate metrics across all memoized methods on this instance.
+    #
+    # @return [Hash] with keys +:total_hits+, +:total_misses+, +:hit_rate+,
+    #   +:miss_rate+, +:average_computation_time+, and +:entries+ (one entry
+    #   per cached argument combination)
     def cache_stats
       with_memo_lock do
         metrics = memo_metrics_store
@@ -11,6 +17,11 @@ module SafeMemoize
       end
     end
 
+    # Returns metrics for a single memoized method.
+    #
+    # @param method_name [Symbol, String]
+    # @return [Hash] same shape as {#cache_stats} but scoped to one method,
+    #   with an extra +:method+ key
     def cache_stats_for(method_name)
       method_name = method_name.to_sym
 
@@ -22,14 +33,23 @@ module SafeMemoize
       end
     end
 
+    # Returns the overall cache hit rate as a percentage (0.0–100.0).
+    # @return [Float]
     def cache_hit_rate
       cache_stats[:hit_rate]
     end
 
+    # Returns the overall cache miss rate as a percentage (0.0–100.0).
+    # @return [Float]
     def cache_miss_rate
       cache_stats[:miss_rate]
     end
 
+    # Resets hit/miss counters, either for one method or for all methods.
+    #
+    # @param method_name [Symbol, String, nil] when given, resets only that method's
+    #   metrics; when +nil+, resets all
+    # @return [void]
     def cache_metrics_reset(method_name = nil)
       with_memo_lock do
         if method_name

data/lib/safe_memoize/rails/middleware.rb

@@ -13,6 +13,8 @@ module SafeMemoize
         @app = app
       end
 
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response triplet
       def call(env)
         @app.call(env)
       ensure

data/lib/safe_memoize/rails/request_scoped.rb

@@ -25,10 +25,13 @@ module SafeMemoize
     #     end
     #   end
     module RequestScoped
+      # @api private
       def self.included(base)
         base.after_action :reset_all_memos if base.respond_to?(:after_action)
       end
 
+      # Resets all memoized values on this instance. Delegates to {PublicMethods#reset_all_memos}.
+      # @return [void]
       def reset_request_memos
         reset_all_memos
       end

data/lib/safe_memoize/release_tooling.rb

@@ -3,6 +3,7 @@
 require "date"
 
 module SafeMemoize
+  # @api private
   module ReleaseTooling
     module_function
 

data/lib/safe_memoize/stores/base.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Stores
+    # Abstract base class for SafeMemoize cache store adapters.
+    #
+    # Subclass this and implement all abstract methods to plug in a custom backend
+    # (Redis, Memcached, Rails.cache, etc.). The {Stores::Memory} class is the
+    # built-in reference implementation.
+    #
+    # @abstract
+    #
+    # @example Minimal inline implementation
+    #   class MyStore < SafeMemoize::Stores::Base
+    #     def initialize = (@h = {})
+    #     def read(key) = @h.fetch(key, MISS)
+    #     def write(key, value, expires_in: nil) = (@h[key] = value)
+    #     def delete(key) = @h.delete(key)
+    #     def clear = @h.clear
+    #     def keys = @h.keys
+    #   end
+    class Base
+      # Sentinel returned by {#read} to signal a cache miss.
+      #
+      # Distinct from +nil+ and +false+, which are valid cached values.
+      MISS = Object.new.freeze
+
+      # Read a value from the store.
+      #
+      # @param key [Object] cache key
+      # @return [Object] the stored value, or {MISS} if absent or expired
+      # @abstract
+      def read(key)
+        raise NotImplementedError, "#{self.class}#read must be implemented"
+      end
+
+      # Write a value to the store.
+      #
+      # @param key [Object] cache key
+      # @param value [Object] value to cache (may be +nil+ or +false+)
+      # @param expires_in [Numeric, nil] seconds until expiry; +nil+ means no expiry
+      # @return [void]
+      # @abstract
+      def write(key, value, expires_in: nil)
+        raise NotImplementedError, "#{self.class}#write must be implemented"
+      end
+
+      # Delete a single entry.
+      #
+      # @param key [Object] cache key
+      # @return [void]
+      # @abstract
+      def delete(key)
+        raise NotImplementedError, "#{self.class}#delete must be implemented"
+      end
+
+      # Remove all entries from the store.
+      #
+      # @return [void]
+      # @abstract
+      def clear
+        raise NotImplementedError, "#{self.class}#clear must be implemented"
+      end
+
+      # Return all live (non-expired) keys.
+      #
+      # @return [Array<Object>]
+      # @abstract
+      def keys
+        raise NotImplementedError, "#{self.class}#keys must be implemented"
+      end
+
+      # Check whether a live entry exists for the given key.
+      #
+      # The default delegates to {#read}; subclasses may override for stores
+      # with a native existence check.
+      #
+      # @param key [Object]
+      # @return [Boolean]
+      def exist?(key)
+        read(key) != MISS
+      end
+    end
+  end
+end

data/lib/safe_memoize/stores/memory.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Stores
+    # Default in-process cache store backed by a plain +Hash+.
+    #
+    # Thread-safe via an internal +Mutex+. Supports per-entry TTL with lazy
+    # expiry: stale entries are not proactively removed but are treated as
+    # misses on read and excluded from {#keys}.
+    class Memory < Base
+      def initialize
+        @data = {}
+        @mutex = Mutex.new
+      end
+
+      # @param key [Object]
+      # @return [Object] stored value, or {MISS} if absent or expired
+      def read(key)
+        @mutex.synchronize do
+          entry = @data[key]
+          return MISS unless entry
+          return MISS if expired?(entry)
+
+          entry[:value]
+        end
+      end
+
+      # @param key [Object]
+      # @param value [Object]
+      # @param expires_in [Numeric, nil] seconds until expiry
+      # @return [void]
+      def write(key, value, expires_in: nil)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        expires_at = expires_in ? now + expires_in.to_f : nil
+
+        @mutex.synchronize do
+          @data[key] = {value: value, expires_at: expires_at, cached_at: now}
+        end
+      end
+
+      # @param key [Object]
+      # @return [void]
+      def delete(key)
+        @mutex.synchronize { @data.delete(key) }
+      end
+
+      # Removes all entries.
+      # @return [void]
+      def clear
+        @mutex.synchronize { @data.clear }
+      end
+
+      # Returns all live (non-expired) keys.
+      # @return [Array<Object>]
+      def keys
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @mutex.synchronize do
+          @data.filter_map { |k, entry| k unless entry[:expires_at] && entry[:expires_at] <= now }
+        end
+      end
+
+      private
+
+      def expired?(entry)
+        expires_at = entry[:expires_at]
+        expires_at && expires_at <= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/safe_memoize/stores/rails_cache.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "safe_memoize"
+
+module SafeMemoize
+  module Stores
+    # Cache store adapter backed by any +ActiveSupport::Cache::Store+.
+    #
+    # Not auto-required. Add to your Rails initializer:
+    #   require "safe_memoize/stores/rails_cache"
+    #
+    # Compatible with any +ActiveSupport::Cache::Store+ implementation
+    # (+MemoryStore+, +FileStore+, +MemCacheStore+, +RedisCacheStore+, etc.)
+    # and with +Rails.cache+ directly.
+    #
+    # Because +ActiveSupport::Cache+ returns +nil+ for both a cache miss and
+    # a cached +nil+ value, this adapter wraps every value in a two-element
+    # sentinel envelope before writing. The envelope is transparent to callers.
+    #
+    # TTL is forwarded as +expires_in:+ to the cache, so the underlying store
+    # manages expiry natively — there is no lazy-expiry overhead on read.
+    #
+    # {#clear} uses +delete_matched+ scoped to the adapter's namespace, so it
+    # never clears entries belonging to other parts of the application. The
+    # backend must respond to +delete_matched+ (all standard Rails cache stores
+    # do); a +NotImplementedError+ is raised if it does not.
+    #
+    # {#keys} returns an empty array — +ActiveSupport::Cache::Store+ does not
+    # expose a standard key enumeration API. Override the method if your
+    # backend supports it.
+    #
+    # @example Basic setup
+    #   # config/initializers/safe_memoize.rb
+    #   require "safe_memoize/stores/rails_cache"
+    #
+    #   MEMO_STORE = SafeMemoize::Stores::RailsCache.new(Rails.cache)
+    #
+    #   class MyService
+    #     prepend SafeMemoize
+    #     def fetch(id) = http_get(id)
+    #     memoize :fetch, store: MEMO_STORE, ttl: 300
+    #   end
+    #
+    # @example Dedicated cache store (recommended for production)
+    #   MEMO_STORE = SafeMemoize::Stores::RailsCache.new(
+    #     ActiveSupport::Cache::RedisCacheStore.new(url: ENV["REDIS_URL"]),
+    #     namespace: "myapp:memo"
+    #   )
+    class RailsCache < Base
+      # Tag prepended to every stored value so cached +nil+/+false+ are
+      # distinguishable from a cache miss.
+      VALUE_TAG = "safe_memoize:v1"
+
+      # @param cache [ActiveSupport::Cache::Store] the cache store to use;
+      #   typically +Rails.cache+ or a dedicated store instance
+      # @param namespace [String] key prefix used to scope all entries;
+      #   defaults to +"safe_memoize"+
+      def initialize(cache, namespace: "safe_memoize")
+        @cache = cache
+        @namespace = namespace
+      end
+
+      # @param key [Object] cache key (serialized with Marshal + Base64)
+      # @return [Object] the stored value, or {MISS} if absent or unrecognised
+      def read(key)
+        raw = @cache.read(cache_key(key))
+        return MISS unless raw.is_a?(Array) && raw.length == 2 && raw[0] == VALUE_TAG
+
+        raw[1]
+      end
+
+      # @param key [Object] cache key
+      # @param value [Object] value to store (may be +nil+ or +false+)
+      # @param expires_in [Numeric, nil] TTL in seconds forwarded to the cache
+      #   as +expires_in:+; +nil+ means no expiry
+      # @return [void]
+      def write(key, value, expires_in: nil)
+        opts = expires_in ? {expires_in: expires_in} : {}
+        @cache.write(cache_key(key), [VALUE_TAG, value], **opts)
+      end
+
+      # @param key [Object]
+      # @return [void]
+      def delete(key)
+        @cache.delete(cache_key(key))
+      end
+
+      # Removes all entries written by this adapter (scoped to the namespace).
+      #
+      # Delegates to +delete_matched+ on the underlying store; raises
+      # +NotImplementedError+ if the store does not support it.
+      #
+      # @return [void]
+      # @raise [NotImplementedError] if the backing store does not respond to
+      #   +delete_matched+
+      def clear
+        unless @cache.respond_to?(:delete_matched)
+          raise NotImplementedError,
+            "#{@cache.class} does not support delete_matched — " \
+            "implement clear manually or use a store that supports it (e.g. MemoryStore, RedisCacheStore)"
+        end
+        @cache.delete_matched(/\A#{Regexp.escape(@namespace)}:/)
+      end
+
+      # Returns an empty array.
+      #
+      # +ActiveSupport::Cache::Store+ does not expose a key enumeration API.
+      # Override this method if your backend supports key listing.
+      #
+      # @return [Array]
+      def keys
+        []
+      end
+
+      # @param key [Object]
+      # @return [Boolean]
+      def exist?(key)
+        @cache.exist?(cache_key(key))
+      end
+
+      private
+
+      def cache_key(key)
+        "#{@namespace}:#{[Marshal.dump(key)].pack("m0")}"
+      end
+    end
+  end
+end