safe_memoize 0.8.0 → 1.0.0

data/lib/safe_memoize/cache_store_methods.rb

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

data/lib/safe_memoize/class_methods.rb

@@ -1,7 +1,43 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Class-level DSL added to any class that does +prepend SafeMemoize+.
   module ClassMethods
+    # 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.
+    # @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 }
     def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil)
       method_name = method_name.to_sym
 
@@ -88,7 +124,7 @@ module SafeMemoize
                 call_memo_hooks(:on_expire, cache_key, record) if record && !record_live
 
                 start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-                value = super(*args, **kwargs)
+                value = Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, klass.name) { super(*args, **kwargs) }
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
                 new_record = memo_record(value, expires_at: memo_expires_at(ttl))
@@ -147,7 +183,7 @@ module SafeMemoize
                 memo_record_value(record)
               else
                 start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-                value = super(*args, **kwargs)
+                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
 
                 new_record = memo_record(value, expires_at: memo_expires_at(ttl))
@@ -174,7 +210,9 @@ module SafeMemoize
 
             # Cache miss - compute and store
             start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            result = memo_fetch_or_store(cache_key, ttl: ttl) { super(*args, **kwargs) }
+            result = memo_fetch_or_store(cache_key, ttl: ttl) do
+              Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name) { super(*args, **kwargs) }
+            end
             elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
             with_memo_lock do
@@ -194,6 +232,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]
@@ -209,6 +286,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__ = {}
@@ -216,6 +295,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]
@@ -231,6 +316,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__ || {}
@@ -240,6 +330,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]
@@ -261,6 +358,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]
@@ -279,24 +382,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,14 +1,56 @@
 # 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
+    # @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
+
+    # @api private
     def initialize
       @default_ttl = nil
       @default_max_size = nil
       @on_deprecation = nil
       @on_hook_error = nil
+      @active_support_notifications = false
+      @statsd_client = nil
+      @opentelemetry_tracer = 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,7 +1,16 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module HooksMethods
+    NOTIFICATION_EVENT_NAMES = {
+      on_hit: "cache_hit.safe_memoize",
+      on_miss: "cache_miss.safe_memoize",
+      on_evict: "cache_evict.safe_memoize",
+      on_expire: "cache_expire.safe_memoize",
+      on_store: "cache_store.safe_memoize"
+    }.freeze
+
     private
 
     def memo_hook_store
@@ -29,6 +38,28 @@ module SafeMemoize
           warn "[SafeMemoize] Hook error in #{hook_type}: #{error.message}"
         end
       end
+
+      safe_memo_notify(hook_type, cache_key) if SafeMemoize.configuration.active_support_notifications
+
+      if (client = SafeMemoize.configuration.statsd_client)
+        Adapters::StatsD.dispatch(client, hook_type, cache_key, self.class.name)
+      end
+    end
+
+    def safe_memo_notify(hook_type, cache_key)
+      return unless defined?(ActiveSupport::Notifications)
+
+      asn = ActiveSupport::Notifications
+      return unless asn.respond_to?(:instrument)
+
+      event = NOTIFICATION_EVENT_NAMES[hook_type]
+      return unless event
+
+      asn.instrument(event, {
+        method: cache_key[0],
+        key: cache_key,
+        class: self.class.name
+      })
     end
 
     def _clear_memo_hooks(hook_type = nil)

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