safe_memoize 0.8.0 → 1.0.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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Rails
+    # Rack middleware that resets all thread-tracked memoized instances at the
+    # end of each request. Useful for service objects that are instantiated
+    # per-request and register themselves via `SafeMemoize::Rails.track(self)`.
+    #
+    # Add to your Rack stack in config/application.rb:
+    #   config.middleware.use SafeMemoize::Rails::Middleware
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response triplet
+      def call(env)
+        @app.call(env)
+      ensure
+        SafeMemoize::Rails.reset_tracked!
+      end
+    end
+  end
+end

data/lib/safe_memoize/rails/request_scoped.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Rails
+    # Include in a Rails controller to automatically reset instance memos after
+    # each request. In non-controller classes (service objects, models), include
+    # it to gain `reset_request_memos` and call it manually at the end of a
+    # request or job.
+    #
+    # The class must also `prepend SafeMemoize` for `reset_all_memos` to exist.
+    #
+    # Example — controller:
+    #   class ApplicationController < ActionController::Base
+    #     prepend SafeMemoize
+    #     include SafeMemoize::Rails::RequestScoped
+    #   end
+    #
+    # Example — service object with middleware tracking:
+    #   class ReportService
+    #     prepend SafeMemoize
+    #     include SafeMemoize::Rails::RequestScoped
+    #
+    #     def initialize
+    #       SafeMemoize::Rails.track(self)
+    #     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
+    end
+  end
+end

data/lib/safe_memoize/rails.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "safe_memoize"
+require_relative "rails/request_scoped"
+require_relative "rails/middleware"
+
+module SafeMemoize
+  # Optional Rails integration. Not auto-required — add to your initializer:
+  #   require "safe_memoize/rails"
+  module Rails
+    # Register an instance to have its memos reset at the end of the current
+    # request (via Middleware). Thread-local; each thread maintains its own list.
+    def self.track(instance)
+      (Thread.current[:safe_memoize_tracked] ||= []) << instance
+    end
+
+    # Reset all tracked instances and clear the list. Called automatically by
+    # Middleware after each request. Safe to call with an empty list.
+    def self.reset_tracked!
+      instances = Thread.current[:safe_memoize_tracked] || []
+      instances.each do |instance|
+        instance.reset_all_memos if instance.respond_to?(:reset_all_memos)
+      end
+    ensure
+      Thread.current[:safe_memoize_tracked] = []
+    end
+  end
+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/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module SafeMemoize
-  VERSION = "0.8.0"
+  # The current gem version string.
+  VERSION = "1.0.0"
 end

data/lib/safe_memoize.rb

@@ -2,6 +2,8 @@
 
 require_relative "safe_memoize/version"
 require_relative "safe_memoize/configuration"
+require_relative "safe_memoize/adapters/statsd"
+require_relative "safe_memoize/adapters/opentelemetry"
 require_relative "safe_memoize/class_methods"
 require_relative "safe_memoize/public_methods"
 require_relative "safe_memoize/cache_store_methods"
@@ -15,27 +17,81 @@ require_relative "safe_memoize/public_custom_key_methods"
 require_relative "safe_memoize/lru_methods"
 require_relative "safe_memoize/instance_methods"
 
+# Thread-safe memoization for Ruby that correctly handles +nil+ and +false+ values.
+#
+# Prepend this module into any class, then call {ClassMethods#memoize} to wrap
+# instance methods with a per-instance cache backed by a +Mutex+.
+#
+# @example Basic usage
+#   class UserService
+#     prepend SafeMemoize
+#
+#     def current_user
+#       User.find_by(session_id: session_id)
+#     end
+#     memoize :current_user
+#   end
+#
+# @example With TTL and LRU cap
+#   class ApiClient
+#     prepend SafeMemoize
+#
+#     def fetch(id)
+#       http_get("/items/#{id}")
+#     end
+#     memoize :fetch, ttl: 60, max_size: 500
+#   end
+#
+# @see ClassMethods#memoize
+# @see https://github.com/eclectic-coding/safe_memoize README
 module SafeMemoize
+  # Base class for all SafeMemoize-specific exceptions.
+  # Rescue this to catch any error raised by the library itself.
   class Error < StandardError; end
 
   include InstanceMethods
 
+  # @api private
   def self.prepended(base)
     base.extend(ClassMethods)
   end
 
+  # Yields the global {Configuration} object for mutation.
+  #
+  # @example
+  #   SafeMemoize.configure do |c|
+  #     c.default_ttl = 300
+  #   end
+  #
+  # @yield [config] The current {Configuration} instance.
+  # @yieldparam config [Configuration]
+  # @return [void]
   def self.configure
     yield configuration
   end
 
+  # Returns the global {Configuration} instance, creating it on first access.
+  #
+  # @return [Configuration]
   def self.configuration
     @configuration ||= Configuration.new
   end
 
+  # Resets the global configuration to all defaults.
+  #
+  # Useful in test suites to prevent configuration leaking between examples.
+  #
+  # @return [Configuration] the new blank configuration
   def self.reset_configuration!
     @configuration = Configuration.new
   end
 
+  # Emits a structured deprecation warning through the configured handler.
+  #
+  # @param subject [String] short identifier of the deprecated symbol
+  # @param message [String] migration instructions
+  # @param horizon [String] version when the symbol will be removed (e.g. +"v2.0.0"+)
+  # @return [void]
   def self.deprecate(subject, message:, horizon:)
     text = "[SafeMemoize] #{subject} is deprecated and will be removed in #{horizon}. #{message}"
     handler = configuration.on_deprecation