safe_memoize 1.2.0 → 1.4.0

data/lib/safe_memoize/class_methods.rb

@@ -37,7 +37,33 @@ module SafeMemoize
     #   a supervisor +Ractor+ rather than a +Mutex+-protected ivar, making it accessible
     #   from worker Ractors. Requires +shared: true+. Cached values are deep-frozen via
     #   +Ractor.make_shareable+. Incompatible with +if:+, +unless:+, +max_size:+,
-    #   +ttl_refresh:+, +key:+, and +store:+.
+    #   +ttl_refresh:+, +key:+, +store:+, and +copy_on_read:+.
+    # @param namespace [String, nil] prefix prepended to every cache key for this method,
+    #   scoping it to a logical partition. Takes precedence over both the class-level
+    #   {#safe_memoize_namespace} and the global {SafeMemoize::Configuration#namespace}.
+    #   Useful for versioning a single method independently of its peers. Must not contain
+    #   the character +:+.
+    # @param cache_bust [Proc, Symbol, nil] callable invoked on the instance (via
+    #   +instance_exec+) on every cache lookup to obtain a version token. The token is
+    #   folded into the cache key alongside the normal arguments, so when the token
+    #   changes (e.g. an ActiveRecord +updated_at+ timestamp advances after a +save+)
+    #   the old key no longer matches any entry — the method is recomputed and the result
+    #   stored under the new key. Accepts any callable (+Proc+, +lambda+, +Method+) that
+    #   takes no arguments, or a +Symbol+ naming an instance method. Cannot be combined
+    #   with +key:+.
+    # @param shared_cache [String, nil] name of a globally-registered shared cache store
+    #   (see {SafeMemoize.shared_cache} and {SafeMemoize.register_shared_cache}). All
+    #   instances of any class that memoizes a method with the same +shared_cache:+ name
+    #   read and write the same backing store, enabling cross-class cache sharing.
+    #   The store is resolved at +memoize+ definition time; call
+    #   {SafeMemoize.register_shared_cache} before the class is loaded to supply a custom
+    #   adapter. Incompatible with +shared:+, +store:+, +fiber_local:+, +ractor_safe:+,
+    #   and +max_size:+. Composes naturally with +namespace:+, +ttl:+, +if:+, and +key:+.
+    # @param copy_on_read [Boolean] when +true+, every cache read returns a +dup+ (or
+    #   +deep_dup+ when available) of the stored value rather than the cached object
+    #   itself. Prevents callers from mutating shared cached state. Frozen and +nil+
+    #   values are returned as-is. Incompatible with +ractor_safe:+ (ractor values are
+    #   always frozen; use that guarantee instead).
     # @return [void]
     # @raise [ArgumentError] if the method does not exist, or option values are invalid
     #
@@ -52,28 +78,78 @@ module SafeMemoize
     # @example Conditional — only cache successful responses
     #   memoize :fetch, if: ->(v) { v[:status] == 200 }
     #
+    # @example Copy-on-read — protect mutable cached config
+    #   memoize :config, copy_on_read: true
+    #
     # @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, fiber_local: false, ractor_safe: false)
+    def memoize(method_name, ttl: UNSET, max_size: UNSET, ttl_refresh: UNSET, if: UNSET, unless: UNSET, shared: UNSET, key: UNSET, store: UNSET, fiber_local: UNSET, ractor_safe: UNSET, namespace: UNSET, shared_cache: UNSET, cache_bust: UNSET, copy_on_read: UNSET, **extension_options)
       method_name = method_name.to_sym
 
       unless method_defined?(method_name) || private_method_defined?(method_name) || protected_method_defined?(method_name)
         raise ArgumentError, "cannot memoize :#{method_name} — no instance method with that name is defined on #{self}"
       end
 
+      unless extension_options.empty?
+        extension_options.each_key do |opt|
+          raise ArgumentError, "unknown memoize option :#{opt} — no registered extension handles it" unless SafeMemoize.extension_for_option(opt)
+        end
+
+        injected = {}
+        extension_options.each do |opt, val|
+          result = SafeMemoize.extension_for_option(opt).process_memoize_option(opt, val, method_name, extension_options)
+          injected.merge!(result)
+        end
+
+        ttl = injected[:ttl] if injected.key?(:ttl)
+        max_size = injected[:max_size] if injected.key?(:max_size)
+        namespace = injected[:namespace] if injected.key?(:namespace)
+        store = injected[:store] if injected.key?(:store)
+        shared_cache = injected[:shared_cache] if injected.key?(:shared_cache)
+        cache_bust = injected[:cache_bust] if injected.key?(:cache_bust)
+      end
+
+      # :if and :unless are reserved Ruby keywords; use binding to extract them
+      cond_if = binding.local_variable_get(:if)
+      cond_unless = binding.local_variable_get(:unless)
+
+      # Apply class-level defaults (safe_memoize_options) for any still-unset options
+      if (cls_defaults = __safe_memoize_defaults__)
+        ttl = cls_defaults[:ttl] if ttl.equal?(UNSET) && cls_defaults.key?(:ttl)
+        max_size = cls_defaults[:max_size] if max_size.equal?(UNSET) && cls_defaults.key?(:max_size)
+        ttl_refresh = cls_defaults[:ttl_refresh] if ttl_refresh.equal?(UNSET) && cls_defaults.key?(:ttl_refresh)
+        cond_if = cls_defaults[:if] if cond_if.equal?(UNSET) && cls_defaults.key?(:if)
+        cond_unless = cls_defaults[:unless] if cond_unless.equal?(UNSET) && cls_defaults.key?(:unless)
+        key = cls_defaults[:key] if key.equal?(UNSET) && cls_defaults.key?(:key)
+        cache_bust = cls_defaults[:cache_bust] if cache_bust.equal?(UNSET) && cls_defaults.key?(:cache_bust)
+        copy_on_read = cls_defaults[:copy_on_read] if copy_on_read.equal?(UNSET) && cls_defaults.key?(:copy_on_read)
+        namespace = cls_defaults[:namespace] if namespace.equal?(UNSET) && cls_defaults.key?(:namespace)
+        store = cls_defaults[:store] if store.equal?(UNSET) && cls_defaults.key?(:store)
+      end
+
+      # Normalize remaining UNSET to original per-call defaults
+      ttl = nil if ttl.equal?(UNSET)
+      max_size = nil if max_size.equal?(UNSET)
+      ttl_refresh = false if ttl_refresh.equal?(UNSET)
+      shared = false if shared.equal?(UNSET)
+      key = nil if key.equal?(UNSET)
+      store = nil if store.equal?(UNSET)
+      fiber_local = false if fiber_local.equal?(UNSET)
+      ractor_safe = false if ractor_safe.equal?(UNSET)
+      namespace = nil if namespace.equal?(UNSET)
+      shared_cache = nil if shared_cache.equal?(UNSET)
+      cache_bust = nil if cache_bust.equal?(UNSET)
+      copy_on_read = false if copy_on_read.equal?(UNSET)
+      cond_if = nil if cond_if.equal?(UNSET)
+      cond_unless = nil if cond_unless.equal?(UNSET)
+
       visibility = memoized_method_visibility(method_name)
 
       config = SafeMemoize.configuration
       ttl = config.default_ttl if ttl.nil?
       max_size = config.default_max_size if max_size.nil?
 
-      # :if and :unless are reserved Ruby keywords, so they can't be referenced
-      # as local variables directly. binding.local_variable_get is the only way
-      # to read keyword arguments with those names inside the method body.
-      cond_if = binding.local_variable_get(:if)
-      cond_unless = binding.local_variable_get(:unless)
-
       ttl = if ttl.nil?
         nil
       else
@@ -102,6 +178,13 @@ 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 cache_bust
+        unless cache_bust.respond_to?(:call) || cache_bust.is_a?(Symbol)
+          raise ArgumentError, "cache_bust: must be a callable or Symbol (got #{cache_bust.class})"
+        end
+        raise ArgumentError, "cache_bust: and key: cannot be combined" if key
+      end
+
       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
@@ -120,6 +203,25 @@ module SafeMemoize
         raise ArgumentError, "ractor_safe: is incompatible with ttl_refresh:" if ttl_refresh
         raise ArgumentError, "ractor_safe: is incompatible with key:" if key
         raise ArgumentError, "ractor_safe: is incompatible with store:" if store
+        raise ArgumentError, "ractor_safe: is incompatible with copy_on_read:" if copy_on_read
+      end
+
+      if namespace
+        raise ArgumentError, "namespace: must be a String (got #{namespace.class})" unless namespace.is_a?(String)
+        raise ArgumentError, "namespace: must not be empty" if namespace.empty?
+        raise ArgumentError, "namespace: must not contain ':'" if namespace.include?(":")
+        __safe_memo_method_namespaces__[method_name] = namespace
+      end
+
+      if shared_cache
+        raise ArgumentError, "shared_cache: must be a String (got #{shared_cache.class})" unless shared_cache.is_a?(String)
+        raise ArgumentError, "shared_cache: must not be empty" if shared_cache.empty?
+        raise ArgumentError, "shared_cache: and shared: cannot be combined" if shared
+        raise ArgumentError, "shared_cache: and store: cannot be combined" if store
+        raise ArgumentError, "shared_cache: and fiber_local: cannot be combined" if fiber_local
+        raise ArgumentError, "shared_cache: and ractor_safe: cannot be combined" if ractor_safe
+        raise ArgumentError, "max_size: is not supported with shared_cache: — use the store adapter's own eviction" if max_size
+        store = SafeMemoize.shared_cache(shared_cache)
       end
 
       # Resolve effective store: per-method store: wins; then class-level
@@ -143,6 +245,7 @@ module SafeMemoize
       end
 
       __safe_memo_class_key_generators__[method_name] = key if key
+      __safe_memo_class_cache_bust_generators__[method_name] = cache_bust if cache_bust
 
       # Normalize to a single "should cache?" predicate
       condition = if cond_if
@@ -151,6 +254,18 @@ module SafeMemoize
         ->(result) { !cond_unless.call(result) }
       end
 
+      # Build a value-duplication function for copy_on_read: true.
+      # Frozen and nil values are returned as-is; deep_dup is preferred when available
+      # (e.g. ActiveRecord objects) so nested mutable structures are also protected.
+      dup_fn = if copy_on_read
+        lambda do |v|
+          return v if v.nil? || v.frozen?
+          v.respond_to?(:deep_dup) ? v.deep_dup : v.dup
+        end
+      else
+        ->(v) { v }
+      end
+
       if effective_store
         miss = SafeMemoize::Stores::Base::MISS
 
@@ -163,9 +278,9 @@ module SafeMemoize
 
             unless cached.equal?(miss)
               effective_store.write(cache_key, cached, expires_in: ttl) if ttl_refresh
-              record_cache_hit(method_name, args, kwargs)
+              record_cache_hit(cache_key)
               call_memo_hooks(:on_hit, cache_key, {value: cached, expires_at: nil, cached_at: nil})
-              return cached
+              return dup_fn.call(cached)
             end
 
             start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -180,10 +295,10 @@ module SafeMemoize
               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)
+            record_cache_miss(cache_key, elapsed_time)
             call_memo_hooks(:on_miss, cache_key, {value: value, expires_at: nil, cached_at: now})
 
-            value
+            dup_fn.call(value)
           end
 
           send(visibility, method_name)
@@ -210,9 +325,9 @@ module SafeMemoize
                 lru[cache_key] = true
               end
               record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
-              record_cache_hit(method_name, args, kwargs)
+              record_cache_hit(cache_key)
               call_memo_hooks(:on_hit, cache_key, record)
-              memo_record_value(record)
+              dup_fn.call(memo_record_value(record))
             else
               call_memo_hooks(:on_expire, cache_key, record) if record
 
@@ -243,10 +358,10 @@ module SafeMemoize
                 call_memo_hooks(:on_store, cache_key, new_record)
               end
 
-              record_cache_miss(method_name, args, kwargs, elapsed_time)
+              record_cache_miss(cache_key, elapsed_time)
               call_memo_hooks(:on_miss, cache_key, new_record)
 
-              value
+              dup_fn.call(value)
             end
           end
 
@@ -288,9 +403,9 @@ module SafeMemoize
                   lru[cache_key] = true
                 end
                 record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
-                record_cache_hit(method_name, args, kwargs)
+                record_cache_hit(cache_key)
                 call_memo_hooks(:on_hit, cache_key, record)
-                record[:value]
+                dup_fn.call(record[:value])
               else
                 call_memo_hooks(:on_expire, cache_key, record) if record && !record_live
 
@@ -319,10 +434,10 @@ module SafeMemoize
                   call_memo_hooks(:on_store, cache_key, new_record)
                 end
 
-                record_cache_miss(method_name, args, kwargs, elapsed_time)
+                record_cache_miss(cache_key, elapsed_time)
                 call_memo_hooks(:on_miss, cache_key, new_record)
 
-                value
+                dup_fn.call(value)
               end
             end
           end
@@ -349,9 +464,9 @@ module SafeMemoize
               if record
                 lru_touch(method_name, cache_key) if max_size
                 record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
-                record_cache_hit(method_name, args, kwargs)
+                record_cache_hit(cache_key)
                 call_memo_hooks(:on_hit, cache_key, record)
-                memo_record_value(record)
+                dup_fn.call(memo_record_value(record))
               else
                 start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
                 value = Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name) { super(*args, **kwargs) }
@@ -365,18 +480,18 @@ module SafeMemoize
                   lru_touch(method_name, cache_key) if max_size
                   call_memo_hooks(:on_store, cache_key, new_record)
                 end
-                record_cache_miss(method_name, args, kwargs, elapsed_time)
+                record_cache_miss(cache_key, elapsed_time)
                 call_memo_hooks(:on_miss, cache_key, new_record)
 
-                value
+                dup_fn.call(value)
               end
             end
           else
             # Fast path: check without lock
             if (record = memo_cache_record(cache_key))
-              record_cache_hit(method_name, args, kwargs)
+              record_cache_hit(cache_key)
               call_memo_hooks(:on_hit, cache_key, record)
-              return memo_record_value(record)
+              return dup_fn.call(memo_record_value(record))
             end
 
             # Cache miss - compute and store
@@ -387,13 +502,13 @@ module SafeMemoize
             elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
             with_memo_lock do
-              record_cache_miss(method_name, args, kwargs, elapsed_time)
+              record_cache_miss(cache_key, elapsed_time)
               new_record = memo_cache_record(cache_key)
               call_memo_hooks(:on_store, cache_key, new_record)
               call_memo_hooks(:on_miss, cache_key, new_record)
             end
 
-            result
+            dup_fn.call(result)
           end
         end
 
@@ -429,6 +544,66 @@ module SafeMemoize
       @__safe_memoize_store__ = store
     end
 
+    # Returns the class-level namespace prefix, or +nil+ if not set.
+    #
+    # When set, this prefix is prepended to every cache key produced by +memoize+
+    # calls on this class that do not specify their own +namespace:+ option.
+    # The global {SafeMemoize::Configuration#namespace} is the final fallback.
+    #
+    # @return [String, nil]
+    def safe_memoize_namespace
+      @__safe_memoize_namespace__
+    end
+
+    # Sets the class-level namespace prefix.
+    #
+    # @param ns [String, nil] a non-empty string without +:+, or +nil+ to clear
+    # @return [String, nil]
+    # @raise [ArgumentError] if +ns+ is not a valid namespace string
+    def safe_memoize_namespace=(ns)
+      if ns
+        raise ArgumentError, "safe_memoize_namespace= must be a String (got #{ns.class})" unless ns.is_a?(String)
+        raise ArgumentError, "safe_memoize_namespace= must not be empty" if ns.empty?
+        raise ArgumentError, "safe_memoize_namespace= must not contain ':'" if ns.include?(":")
+      end
+      @__safe_memoize_namespace__ = ns
+    end
+
+    # Sets class-wide default options applied to every subsequent {#memoize} call
+    # on this class. Per-call options take precedence; class defaults take
+    # precedence over global {SafeMemoize::Configuration} defaults.
+    #
+    # Call with no arguments (or an empty hash) to clear all class-level defaults.
+    #
+    # @example Apply a TTL and LRU cap to every memoized method on the class
+    #   class ApiClient
+    #     prepend SafeMemoize
+    #     safe_memoize_options ttl: 60, max_size: 200
+    #
+    #     def fetch(id) = http.get(id)
+    #     memoize :fetch                     # uses ttl: 60, max_size: 200
+    #
+    #     def list = http.get("/all")
+    #     memoize :list, ttl: 300            # uses max_size: 200, ttl: 300
+    #   end
+    #
+    # @example Protect all cached values from mutation
+    #   safe_memoize_options copy_on_read: true
+    #
+    # @param opts [Hash] any subset of {#memoize} options except mode-switch options
+    #   (+shared:+, +fiber_local:+, +ractor_safe:+, +shared_cache:+)
+    # @return [Hash] the stored defaults
+    # @raise [ArgumentError] for disallowed options
+    def safe_memoize_options(**opts)
+      disallowed = %i[shared fiber_local ractor_safe shared_cache]
+      bad = opts.keys & disallowed
+      unless bad.empty?
+        raise ArgumentError,
+          "safe_memoize_options does not accept #{bad.map { |k| ":#{k}" }.join(", ")} — pass mode-switch options per memoize call"
+      end
+      @__safe_memoize_defaults__ = opts.empty? ? nil : opts
+    end
+
     # Memoizes every eligible public instance method defined directly on the class.
     #
     # Accepts all options that {#memoize} accepts, plus +:except:+ and +:only:+.
@@ -470,14 +645,15 @@ module SafeMemoize
     # @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]
+      effective = __safe_memo_effective_key_name__(method_name)
+      specific_key = (args.empty? && kwargs.empty?) ? nil : [effective, args, kwargs]
 
       __safe_memo_shared_mutex__.synchronize do
         if specific_key
           __safe_memo_shared_cache__.delete(specific_key)
           __safe_memo_shared_lru_order__[method_name]&.delete(specific_key)
         else
-          __safe_memo_shared_cache__.delete_if { |key, _| key[0] == method_name }
+          __safe_memo_shared_cache__.delete_if { |key, _| key[0] == effective }
           __safe_memo_shared_lru_order__.delete(method_name)
         end
       end
@@ -500,7 +676,8 @@ module SafeMemoize
     # @return [Boolean]
     def shared_memoized?(method_name, *args, **kwargs)
       method_name = method_name.to_sym
-      cache_key = [method_name, args, kwargs]
+      effective = __safe_memo_effective_key_name__(method_name)
+      cache_key = [effective, args, kwargs]
 
       __safe_memo_shared_mutex__.synchronize do
         cache = @__safe_memo_shared_cache__
@@ -523,7 +700,12 @@ module SafeMemoize
         cache = @__safe_memo_shared_cache__ || {}
         now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         live = cache.reject { |_, r| r[:expires_at] && r[:expires_at] <= now }
-        method_name ? live.count { |key, _| key[0] == method_name.to_sym } : live.count
+        if method_name
+          effective = __safe_memo_effective_key_name__(method_name.to_sym)
+          live.count { |key, _| key[0] == effective }
+        else
+          live.count
+        end
       end
     end
 
@@ -536,7 +718,8 @@ module SafeMemoize
     # @return [Float, nil]
     def shared_memo_age(method_name, *args, **kwargs)
       method_name = method_name.to_sym
-      cache_key = [method_name, args, kwargs]
+      effective = __safe_memo_effective_key_name__(method_name)
+      cache_key = [effective, args, kwargs]
 
       __safe_memo_shared_mutex__.synchronize do
         cache = @__safe_memo_shared_cache__
@@ -563,7 +746,8 @@ module SafeMemoize
     # @return [Boolean]
     def shared_memo_stale?(method_name, *args, **kwargs)
       method_name = method_name.to_sym
-      cache_key = [method_name, args, kwargs]
+      effective = __safe_memo_effective_key_name__(method_name)
+      cache_key = [effective, args, kwargs]
 
       __safe_memo_shared_mutex__.synchronize do
         cache = @__safe_memo_shared_cache__
@@ -597,6 +781,29 @@ module SafeMemoize
       @__safe_memo_class_key_generators__ ||= {}
     end
 
+    def __safe_memo_method_namespaces__
+      @__safe_memo_method_namespaces__ ||= {}
+    end
+
+    def __safe_memo_class_cache_bust_generators__
+      @__safe_memo_class_cache_bust_generators__ ||= {}
+    end
+
+    def __safe_memoize_defaults__
+      @__safe_memoize_defaults__
+    end
+
+    # Resolves the effective first-element key sym for a given bare method name,
+    # applying the active namespace. Used by class-level cache operations where
+    # instance methods (compute_cache_key) are unavailable.
+    def __safe_memo_effective_key_name__(method_name)
+      ns_map = @__safe_memo_method_namespaces__
+      ns = (ns_map && ns_map[method_name]) ||
+        @__safe_memoize_namespace__ ||
+        SafeMemoize.configuration.namespace
+      ns ? :"#{ns}:#{method_name}" : method_name
+    end
+
     def memoized_method_visibility(method_name)
       return :private if private_method_defined?(method_name)
       return :protected if protected_method_defined?(method_name)
@@ -627,7 +834,7 @@ module SafeMemoize
             response = Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
 
             if response[:hit]
-              record_cache_hit(method_name, args, kwargs)
+              record_cache_hit(cache_key)
               call_memo_hooks(:on_hit, cache_key, response[:record])
               return response[:record][:value]
             end
@@ -653,7 +860,7 @@ module SafeMemoize
             stored = Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
             stored_record = stored[:stored]
 
-            record_cache_miss(method_name, args, kwargs, elapsed_time)
+            record_cache_miss(cache_key, elapsed_time)
             call_memo_hooks(:on_store, cache_key, stored_record)
             call_memo_hooks(:on_miss, cache_key, stored_record)
 

data/lib/safe_memoize/configuration.rb

@@ -48,6 +48,13 @@ module SafeMemoize
     #   store and will silently continue using the per-instance hash even when this is set.
     attr_accessor :default_store
 
+    # @return [String, nil] Global namespace prefix applied to every cache key produced by
+    #   {ClassMethods#memoize}. Useful for versioned deployments (change the namespace to
+    #   bust all in-flight cached values) and multi-tenant setups (scope keys to a tenant
+    #   identifier). A class-level {ClassMethods#safe_memoize_namespace} or a per-method
+    #   +namespace:+ option takes precedence over this value. +nil+ means no prefix.
+    attr_accessor :namespace
+
     # @api private
     def initialize
       @default_ttl = nil
@@ -58,6 +65,7 @@ module SafeMemoize
       @statsd_client = nil
       @opentelemetry_tracer = nil
       @default_store = nil
+      @namespace = nil
     end
   end
 end

data/lib/safe_memoize/custom_key_methods.rb

@@ -19,14 +19,23 @@ module SafeMemoize
     def compute_cache_key(method_name, args, kwargs)
       method_name = method_name.to_sym
 
+      ns = __safe_memo_resolve_namespace__(method_name)
+      effective_name = ns ? :"#{ns}:#{method_name}" : method_name
+
       # Instance-level key generator takes priority over class-level
       key_block = custom_key_store[method_name] ||
         self.class.send(:__safe_memo_class_key_generators__)[method_name]
 
       if key_block
-        [method_name, key_block.call(*args, **kwargs)]
+        [effective_name, key_block.call(*args, **kwargs)]
       else
-        safe_memo_cache_key(method_name, args, kwargs)
+        bust_block = self.class.send(:__safe_memo_class_cache_bust_generators__)[method_name]
+        if bust_block
+          token = bust_block.is_a?(Symbol) ? send(bust_block) : instance_exec(&bust_block)
+          [effective_name, [deep_freeze_copy(args), deep_freeze_copy(kwargs), token]]
+        else
+          safe_memo_cache_key(effective_name, args, kwargs)
+        end
       end
     end
 

data/lib/safe_memoize/extension.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  # Mixin for defining SafeMemoize extensions.
+  #
+  # Extend this module in any Ruby module or class that you want to register
+  # as a SafeMemoize extension. It provides a DSL for declaring custom
+  # +memoize+ options and global cache lifecycle event handlers.
+  #
+  # @example Defining an extension
+  #   module MyExtension
+  #     extend SafeMemoize::Extension
+  #
+  #     handles_option :active_record_bust do |value, method_name, _options|
+  #       { cache_bust: -> { send(:updated_at) } }
+  #     end
+  #
+  #     on_cache_event :miss do |klass, method_name, _cache_key, _record|
+  #       Rails.logger.debug "cache miss: #{klass}##{method_name}"
+  #     end
+  #   end
+  #
+  #   SafeMemoize.register_extension(:active_record_bust, MyExtension)
+  module Extension
+    # Declares a custom +memoize+ option handled by this extension.
+    #
+    # The block is called at +memoize+ definition time whenever +option_name+
+    # appears in the +memoize+ keyword arguments. It receives the option value,
+    # the method name being memoized, and the full hash of other extension options
+    # passed to that +memoize+ call. It must return a +Hash+ of standard
+    # {ClassMethods#memoize} options to inject (e.g. +{ cache_bust: ... }+), or
+    # +nil+/empty hash for no injection.
+    #
+    # @param option_name [Symbol]
+    # @yieldparam value [Object] the option value supplied by the caller
+    # @yieldparam method_name [Symbol] the method being memoized
+    # @yieldparam all_options [Hash] other extension options in the same +memoize+ call
+    # @yieldreturn [Hash, nil] standard memoize options to inject
+    # @return [void]
+    def handles_option(option_name, &processor)
+      @__handled_options__ ||= {}
+      @__handled_options__[option_name.to_sym] = processor
+    end
+
+    # Registers a global cache lifecycle event handler.
+    #
+    # The block fires after every matching cache event across *all* memoized
+    # methods on all classes. Multiple event types can be listed in a single
+    # call. Valid types are +:on_hit+, +:on_miss+, +:on_store+, +:on_expire+,
+    # and +:on_evict+.
+    #
+    # Handlers execute on the main Ractor only; they are silently skipped from
+    # worker Ractors.
+    #
+    # @param event_types [Array<Symbol>] one or more of +:on_hit+, +:on_miss+,
+    #   +:on_store+, +:on_expire+, +:on_evict+
+    # @yieldparam klass [Class] the class whose instance triggered the event
+    # @yieldparam method_name [Symbol] bare method name (namespace stripped)
+    # @yieldparam cache_key [Array] the full cache key
+    # @yieldparam record [Hash, nil] the cache record (+value+, +expires_at+, +cached_at+)
+    # @return [void]
+    def on_cache_event(*event_types, &handler)
+      @__event_handlers__ ||= {}
+      event_types.each { |type| (@__event_handlers__[type.to_sym] ||= []) << handler }
+    end
+
+    # @api private
+    def handled_options
+      @__handled_options__&.keys || []
+    end
+
+    # @api private
+    def process_memoize_option(option_name, value, method_name, all_options)
+      processor = @__handled_options__&.[](option_name.to_sym)
+      result = processor&.call(value, method_name, all_options)
+      result.is_a?(Hash) ? result : {}
+    end
+
+    # @api private
+    def dispatch_cache_event(event_type, klass, method_name, cache_key, record)
+      return unless @__event_handlers__
+
+      (@__event_handlers__[event_type] || []).each do |handler|
+        handler.call(klass, method_name, cache_key, record)
+      end
+    end
+  end
+end

data/lib/safe_memoize/fiber_local_methods.rb

@@ -42,7 +42,8 @@ module SafeMemoize
       return unless cache
 
       if args.empty? && kwargs.empty?
-        cache.delete_if { |key, _| key[0] == method_name }
+        effective = resolve_memo_key_name(method_name)
+        cache.delete_if { |key, _| key[0] == effective }
         fiber_memo_lru_or_nil&.delete(method_name)
       else
         cache_key = compute_cache_key(method_name, args, kwargs)

data/lib/safe_memoize/hooks_methods.rb

@@ -49,6 +49,8 @@ module SafeMemoize
       if (client = SafeMemoize.configuration.statsd_client)
         Adapters::StatsD.dispatch(client, hook_type, cache_key, self.class.name)
       end
+
+      SafeMemoize.dispatch_extension_events(hook_type, self.class, safe_memo_bare_method_name(cache_key[0]), cache_key, record)
     end
 
     def safe_memo_notify(hook_type, cache_key)