safe_memoize 0.9.0 → 1.1.0

data/lib/safe_memoize/class_methods.rb

@@ -1,8 +1,52 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Class-level DSL added to any class that does +prepend SafeMemoize+.
   module ClassMethods
-    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil)
+    # Wraps an existing instance method with a thread-safe per-instance cache.
+    #
+    # Must be called *after* the method is defined. Raises +ArgumentError+ immediately
+    # at class-definition time if no such method exists.
+    #
+    # @param method_name [Symbol, String] name of the instance method to memoize
+    # @param ttl [Numeric, nil] seconds until the cached value expires; +nil+ means
+    #   the entry never expires. Falls back to {Configuration#default_ttl} when +nil+.
+    # @param max_size [Integer, nil] maximum number of cached entries per instance
+    #   for this method; the least-recently-used entry is evicted when the limit is
+    #   reached. Falls back to {Configuration#default_max_size} when +nil+.
+    # @param ttl_refresh [Boolean] when +true+, every cache *hit* resets the expiry
+    #   clock (sliding-window TTL). Requires +ttl:+ to be set.
+    # @param if [Proc, nil] callable predicate; the result is cached only when the
+    #   predicate returns truthy. Receives the computed return value as its argument.
+    # @param unless [Proc, nil] inverse of +:if+; the result is *not* cached when the
+    #   predicate returns truthy.
+    # @param shared [Boolean] when +true+, results are stored on the class rather than
+    #   per instance — all instances share one cache.
+    # @param key [Proc, nil] class-level custom cache key generator. Receives the same
+    #   arguments as the method and should return a single comparable value. Instance-level
+    #   keys set via {PublicCustomKeyMethods#memoize_with_custom_key} take priority.
+    # @param store [Stores::Base, nil] custom cache store adapter. Must be a
+    #   {Stores::Base} subclass instance. The store is shared across all instances of the
+    #   class. When +nil+, the default per-instance in-process hash is used.
+    #   Cannot be combined with +max_size:+ or +shared:+.
+    # @return [void]
+    # @raise [ArgumentError] if the method does not exist, or option values are invalid
+    #
+    # @example Zero-argument method
+    #   def expensive_query = db.run("SELECT …")
+    #   memoize :expensive_query
+    #
+    # @example With TTL and LRU cap
+    #   def fetch(id) = http_get(id)
+    #   memoize :fetch, ttl: 60, max_size: 500
+    #
+    # @example Conditional — only cache successful responses
+    #   memoize :fetch, if: ->(v) { v[:status] == 200 }
+    #
+    # @example With a custom store
+    #   STORE = SafeMemoize::Stores::Memory.new
+    #   memoize :fetch, store: STORE, ttl: 300
+    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil, store: nil)
       method_name = method_name.to_sym
 
       unless method_defined?(method_name) || private_method_defined?(method_name) || protected_method_defined?(method_name)
@@ -49,6 +93,26 @@ module SafeMemoize
       raise ArgumentError, ":unless must be callable" if cond_unless && !cond_unless.respond_to?(:call)
       raise ArgumentError, ":key must be callable" if key && !key.respond_to?(:call)
 
+      if store
+        raise ArgumentError, "store: must be a SafeMemoize::Stores::Base instance (got #{store.class})" unless store.is_a?(SafeMemoize::Stores::Base)
+        raise ArgumentError, "max_size: is not supported with store: — use the store adapter's own eviction" if max_size
+        raise ArgumentError, "shared: and store: cannot be combined" if shared
+      end
+
+      # Resolve effective store: explicit store: wins; global default applies when
+      # compatible (max_size: and shared: are incompatible — fall back silently).
+      effective_store = store
+      if effective_store.nil? && !max_size && !shared
+        global_default = SafeMemoize.configuration.default_store
+        if global_default
+          unless global_default.is_a?(SafeMemoize::Stores::Base)
+            raise ArgumentError,
+              "SafeMemoize.configuration.default_store must be a Stores::Base instance (got #{global_default.class})"
+          end
+          effective_store = global_default
+        end
+      end
+
       __safe_memo_class_key_generators__[method_name] = key if key
 
       # Normalize to a single "should cache?" predicate
@@ -58,6 +122,49 @@ module SafeMemoize
         ->(result) { !cond_unless.call(result) }
       end
 
+      if effective_store
+        miss = SafeMemoize::Stores::Base::MISS
+
+        mod = Module.new do
+          define_method(method_name) do |*args, **kwargs, &block|
+            return super(*args, **kwargs, &block) if block
+
+            cache_key = compute_cache_key(method_name, args, kwargs)
+            cached = effective_store.read(cache_key)
+
+            unless cached.equal?(miss)
+              effective_store.write(cache_key, cached, expires_in: ttl) if ttl_refresh
+              record_cache_hit(method_name, args, kwargs)
+              call_memo_hooks(:on_hit, cache_key, {value: cached, expires_at: nil, cached_at: nil})
+              return cached
+            end
+
+            start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            value = Adapters::OpenTelemetry.trace(
+              SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name
+            ) { super(*args, **kwargs) }
+            elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            if !condition || condition.call(value)
+              effective_store.write(cache_key, value, expires_in: ttl)
+              call_memo_hooks(:on_store, cache_key, {value: value, expires_at: nil, cached_at: now})
+            end
+
+            record_cache_miss(method_name, args, kwargs, elapsed_time)
+            call_memo_hooks(:on_miss, cache_key, {value: value, expires_at: nil, cached_at: now})
+
+            value
+          end
+
+          send(visibility, method_name)
+        end
+
+        prepend mod
+
+        return
+      end
+
       if shared
         klass = self
         shared_mutex = klass.send(:__safe_memo_shared_mutex__)
@@ -196,6 +303,45 @@ module SafeMemoize
       prepend mod
     end
 
+    # Memoizes every eligible public instance method defined directly on the class.
+    #
+    # Accepts all options that {#memoize} accepts, plus +:except:+ and +:only:+.
+    # Raises +ArgumentError+ when both +:only:+ and +:except:+ are given.
+    #
+    # @param except [Array<Symbol, String>] method names to skip
+    # @param only [Array<Symbol, String>] when non-empty, only these methods are memoized
+    # @param include_protected [Boolean] also memoize +protected+ methods
+    # @param include_private [Boolean] also memoize +private+ methods
+    # @param options [Hash] any additional options forwarded to {#memoize}
+    # @return [void]
+    # @raise [ArgumentError] if both +:only:+ and +:except:+ are given
+    def memoize_all(except: [], only: [], include_protected: false, include_private: false, **options)
+      raise ArgumentError, "cannot specify both :only and :except" if only.any? && except.any?
+
+      excluded = Array(except).map(&:to_sym)
+      included = Array(only).map(&:to_sym)
+
+      methods = public_instance_methods(false)
+      methods |= protected_instance_methods(false) if include_protected
+      methods |= private_instance_methods(false) if include_private
+
+      methods.each do |method_name|
+        next if excluded.include?(method_name)
+        next if included.any? && !included.include?(method_name)
+
+        memoize(method_name, **options)
+      end
+    end
+
+    # Clears one or all entries from the class-level shared cache.
+    #
+    # With no positional args after +method_name+, clears *all* shared entries for
+    # that method. With args/kwargs, clears only the matching entry.
+    #
+    # @param method_name [Symbol, String] the memoized method
+    # @param args [Array] positional arguments identifying the entry to clear
+    # @param kwargs [Hash] keyword arguments identifying the entry to clear
+    # @return [void]
     def reset_shared_memo(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       specific_key = (args.empty? && kwargs.empty?) ? nil : [method_name, args, kwargs]
@@ -211,6 +357,8 @@ module SafeMemoize
       end
     end
 
+    # Clears the entire class-level shared cache for this class.
+    # @return [void]
     def reset_all_shared_memos
       __safe_memo_shared_mutex__.synchronize do
         @__safe_memo_shared_cache__ = {}
@@ -218,6 +366,12 @@ module SafeMemoize
       end
     end
 
+    # Returns +true+ if a live shared cache entry exists for the given call signature.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array] positional arguments
+    # @param kwargs [Hash] keyword arguments
+    # @return [Boolean]
     def shared_memoized?(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       cache_key = [method_name, args, kwargs]
@@ -233,6 +387,11 @@ module SafeMemoize
       end
     end
 
+    # Returns the number of live entries in the class-level shared cache.
+    #
+    # @param method_name [Symbol, String, nil] when given, counts only entries for
+    #   that method; when +nil+, counts all methods.
+    # @return [Integer]
     def shared_memo_count(method_name = nil)
       __safe_memo_shared_mutex__.synchronize do
         cache = @__safe_memo_shared_cache__ || {}
@@ -242,6 +401,13 @@ module SafeMemoize
       end
     end
 
+    # Returns how many seconds ago the shared entry was cached, or +nil+ if not cached
+    # or already expired.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Float, nil]
     def shared_memo_age(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       cache_key = [method_name, args, kwargs]
@@ -263,6 +429,12 @@ module SafeMemoize
       end
     end
 
+    # Returns +true+ if the shared entry exists but its TTL has elapsed.
+    #
+    # @param method_name [Symbol, String]
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Boolean]
     def shared_memo_stale?(method_name, *args, **kwargs)
       method_name = method_name.to_sym
       cache_key = [method_name, args, kwargs]
@@ -281,24 +453,6 @@ module SafeMemoize
       end
     end
 
-    def memoize_all(except: [], only: [], include_protected: false, include_private: false, **options)
-      raise ArgumentError, "cannot specify both :only and :except" if only.any? && except.any?
-
-      excluded = Array(except).map(&:to_sym)
-      included = Array(only).map(&:to_sym)
-
-      methods = public_instance_methods(false)
-      methods |= protected_instance_methods(false) if include_protected
-      methods |= private_instance_methods(false) if include_private
-
-      methods.each do |method_name|
-        next if excluded.include?(method_name)
-        next if included.any? && !included.include?(method_name)
-
-        memoize(method_name, **options)
-      end
-    end
-
     private
 
     def __safe_memo_shared_cache__

data/lib/safe_memoize/configuration.rb

@@ -1,10 +1,54 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Global configuration for SafeMemoize.
+  #
+  # Obtain an instance via {SafeMemoize.configure} or {SafeMemoize.configuration}.
+  #
+  # @example
+  #   SafeMemoize.configure do |c|
+  #     c.default_ttl = 300
+  #     c.default_max_size = 100
+  #     c.on_hook_error = ->(err, type, key) { Bugsnag.notify(err) }
+  #   end
   class Configuration
-    attr_accessor :default_ttl, :default_max_size, :on_deprecation, :on_hook_error,
-      :active_support_notifications, :statsd_client, :opentelemetry_tracer
+    # @return [Numeric, nil] Default TTL (seconds) applied to every {ClassMethods#memoize}
+    #   call that does not specify its own +ttl:+. +nil+ means no expiry.
+    attr_accessor :default_ttl
 
+    # @return [Integer, nil] Default LRU size cap applied to every {ClassMethods#memoize}
+    #   call that does not specify its own +max_size:+. +nil+ means unlimited.
+    attr_accessor :default_max_size
+
+    # @return [Proc, nil] Custom handler for deprecation warnings.
+    #   Receives a single +String+ message. When +nil+, warnings are written to +$stderr+.
+    attr_accessor :on_deprecation
+
+    # @return [Proc, nil] Custom handler for errors raised inside lifecycle hooks.
+    #   Receives +(Exception, Symbol hook_type, cache_key)+. When +nil+, a warning is
+    #   written to +$stderr+ and the error is swallowed.
+    attr_accessor :on_hook_error
+
+    # @return [Boolean] When +true+, SafeMemoize emits +ActiveSupport::Notifications+
+    #   events for cache hits, misses, stores, evictions, and expirations.
+    #   Requires +activesupport+ to be loaded; has zero overhead when it is not.
+    attr_accessor :active_support_notifications
+
+    # @return [Object, nil] Any StatsD-compatible client (responds to +#increment+).
+    #   When set, {Adapters::StatsD} routes lifecycle events to this client.
+    attr_accessor :statsd_client
+
+    # @return [Object, nil] An OpenTelemetry tracer (responds to +#in_span+).
+    #   When set, {Adapters::OpenTelemetry} wraps each cache-miss computation in a span.
+    attr_accessor :opentelemetry_tracer
+
+    # @return [Stores::Base, nil] Default cache store applied to every {ClassMethods#memoize}
+    #   call that does not specify its own +store:+. +nil+ uses the built-in per-instance
+    #   hash cache. Methods using +max_size:+ or +shared:+ are incompatible with an external
+    #   store and will silently continue using the per-instance hash even when this is set.
+    attr_accessor :default_store
+
+    # @api private
     def initialize
       @default_ttl = nil
       @default_max_size = nil
@@ -13,6 +57,7 @@ module SafeMemoize
       @active_support_notifications = false
       @statsd_client = nil
       @opentelemetry_tracer = nil
+      @default_store = nil
     end
   end
 end

data/lib/safe_memoize/custom_key_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module CustomKeyMethods
     private
 

data/lib/safe_memoize/hooks_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module HooksMethods
     NOTIFICATION_EVENT_NAMES = {
       on_hit: "cache_hit.safe_memoize",

data/lib/safe_memoize/inspection_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module InspectionMethods
     private
 
@@ -14,7 +15,7 @@ module SafeMemoize
       if args.empty? && kwargs.empty?
         ->(key) { key[0] == method_name }
       else
-        cache_key = safe_memo_cache_key(method_name, args, kwargs)
+        cache_key = compute_cache_key(method_name, args, kwargs)
         ->(key) { key == cache_key }
       end
     end

data/lib/safe_memoize/instance_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module InstanceMethods
     include PublicMethods
     include CacheStoreMethods

data/lib/safe_memoize/lru_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module LruMethods
     private
 

data/lib/safe_memoize/public_custom_key_methods.rb

@@ -1,13 +1,36 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Instance-level custom cache key registration.
   module PublicCustomKeyMethods
+    # Registers a per-instance custom key generator for a memoized method.
+    #
+    # The block receives the same arguments as the method and should return a
+    # single value used as the cache key. Two calls that produce the same key
+    # value share one cached result, regardless of their raw arguments.
+    #
+    # Instance-level keys take priority over the class-level +key:+ option set
+    # in {ClassMethods#memoize}.
+    #
+    # @param method_name [Symbol, String]
+    # @yield [*args, **kwargs] called with the method's arguments on each invocation
+    # @yieldreturn [Object] the key value (must be comparable with +==+)
+    # @return [void]
+    # @raise [ArgumentError] if no block is given
+    #
+    # @example Collapse all option hashes that share the same user ID
+    #   obj.memoize_with_custom_key(:fetch) { |user_id, _options| user_id }
     def memoize_with_custom_key(method_name, &key_generator)
       raise ArgumentError, "block required for key generation" unless key_generator
 
       register_custom_key(method_name, &key_generator)
     end
 
+    # Removes the custom key generator for one method, or all generators.
+    #
+    # @param method_name [Symbol, String, nil] when given, removes only that method's
+    #   generator; when +nil+, removes all generators on this instance
+    # @return [void]
     def clear_custom_keys(method_name = nil)
       if method_name
         with_memo_lock do