safe_memoize 1.2.0 → 1.4.0

data/lib/safe_memoize/inspection_methods.rb

@@ -13,7 +13,8 @@ module SafeMemoize
 
     def memo_matcher_for(method_name, args, kwargs)
       if args.empty? && kwargs.empty?
-        ->(key) { key[0] == method_name }
+        effective = resolve_memo_key_name(method_name)
+        ->(key) { key[0] == effective }
       else
         cache_key = compute_cache_key(method_name, args, kwargs)
         ->(key) { key == cache_key }
@@ -28,7 +29,8 @@ module SafeMemoize
       entries = cache.to_a
       return entries unless method_name
 
-      entries.select { |(cache_key, _)| cache_key[0] == method_name }
+      effective = resolve_memo_key_name(method_name)
+      entries.select { |(cache_key, _)| cache_key[0] == effective }
     end
 
     def safe_memo_count_for(method_name)
@@ -57,14 +59,14 @@ module SafeMemoize
       # Custom keys are [method, custom_key] (2 elements); default keys are
       # [method, args, kwargs] (3 elements). Detect and surface accordingly.
       if cache_key.length == 2
-        method_name, custom_key = cache_key
+        effective_name, custom_key = cache_key
         payload = {custom_key: custom_key}
       else
-        method_name, args, kwargs = cache_key
+        effective_name, args, kwargs = cache_key
         payload = {args: args, kwargs: kwargs}
       end
 
-      payload[:method] = method_name if include_method
+      payload[:method] = safe_memo_bare_method_name(effective_name) if include_method
       payload[:value] = memo_record_value(value) if include_value
       payload
     end
@@ -73,6 +75,33 @@ module SafeMemoize
       [method_name.to_sym, deep_freeze_copy(args), deep_freeze_copy(kwargs)]
     end
 
+    # Returns the active namespace string for a bare method name, or nil.
+    # Priority: per-method namespace: option > class safe_memoize_namespace > global.
+    #
+    # Uses instance_variable_get throughout so this is safe to call from worker
+    # Ractors (reads only; lazy-init ivars must not be triggered in that context).
+    def __safe_memo_resolve_namespace__(method_name)
+      ns_map = self.class.instance_variable_get(:@__safe_memo_method_namespaces__)
+      (ns_map && ns_map[method_name]) ||
+        self.class.instance_variable_get(:@__safe_memoize_namespace__) ||
+        SafeMemoize.instance_variable_get(:@configuration)&.namespace
+    end
+
+    # Returns the effective cache key sym for a bare method name, applying any
+    # active namespace (per-method > class-level > global).
+    def resolve_memo_key_name(method_name)
+      ns = __safe_memo_resolve_namespace__(method_name)
+      ns ? :"#{ns}:#{method_name}" : method_name
+    end
+
+    # Strips the namespace prefix from an effective key sym, returning the bare
+    # method name. When no namespace is present the sym is returned unchanged.
+    def safe_memo_bare_method_name(key_sym)
+      s = key_sym.to_s
+      colon_idx = s.index(":")
+      colon_idx ? s[(colon_idx + 1)..].to_sym : key_sym
+    end
+
     def deep_freeze_copy(obj)
       case obj
       when Array

data/lib/safe_memoize/public_methods.rb

@@ -214,7 +214,8 @@ module SafeMemoize
 
       with_memo_lock do
         cache = memo_cache_or_nil || {}
-        entries = method_name ? cache.select { |key, _| key[0] == method_name } : cache.dup
+        effective = method_name && resolve_memo_key_name(method_name)
+        entries = effective ? cache.select { |key, _| key[0] == effective } : cache.dup
         entries.select! { |_, record| memo_record_live?(record) }
         entries.transform_values { |record| memo_record_value(record) }
       end
@@ -401,7 +402,7 @@ module SafeMemoize
 
         age = (now - record[:cached_at]).round(6) if record[:cached_at]
 
-        metrics_key = safe_memo_cache_key(method_name, args, kwargs)
+        metrics_key = compute_cache_key(method_name, args, kwargs)
         entry_metrics = memo_metrics_store[metrics_key] || {hits: 0, misses: 0}
 
         custom_key = (cache_key.length == 2) ? cache_key[1] : nil

data/lib/safe_memoize/public_metrics_methods.rb

@@ -26,7 +26,8 @@ module SafeMemoize
       method_name = method_name.to_sym
 
       with_memo_lock do
-        metrics = memo_metrics_store.select { |key, _| key[0] == method_name }
+        effective = resolve_memo_key_name(method_name)
+        metrics = memo_metrics_store.select { |key, _| key[0] == effective }
         return empty_stats.merge(method: method_name) if metrics.empty?
 
         aggregate_metrics(metrics, include_method: false).merge(method: method_name)
@@ -73,13 +74,13 @@ module SafeMemoize
       avg_time = total_misses.zero? ? 0.0 : (total_time / total_misses).round(6)
 
       entries = metrics.map do |cache_key, stats|
-        method_name, args, _kwargs = cache_key
+        effective_name, args, _kwargs = cache_key
         entry_calls = stats[:hits] + stats[:misses]
         entry_hit_rate = entry_calls.zero? ? 0.0 : (stats[:hits].to_f / entry_calls * 100).round(2)
 
         entry = {args: args, hits: stats[:hits], misses: stats[:misses],
                  hit_rate: entry_hit_rate, computation_time: stats[:total_time].round(6)}
-        entry[:method] = method_name if include_method
+        entry[:method] = safe_memo_bare_method_name(effective_name) if include_method
         entry
       end
 

data/lib/safe_memoize/version.rb

@@ -2,5 +2,5 @@
 
 module SafeMemoize
   # The current gem version string.
-  VERSION = "1.2.0"
+  VERSION = "1.4.0"
 end

data/lib/safe_memoize.rb

@@ -2,6 +2,7 @@
 
 require_relative "safe_memoize/version"
 require_relative "safe_memoize/configuration"
+require_relative "safe_memoize/extension"
 require_relative "safe_memoize/stores/base"
 require_relative "safe_memoize/stores/memory"
 require_relative "safe_memoize/adapters/statsd"
@@ -54,6 +55,19 @@ module SafeMemoize
   # Rescue this to catch any error raised by the library itself.
   class Error < StandardError; end
 
+  # @api private — sentinel distinguishing "not passed" from explicit nil/false in memoize kwargs
+  UNSET = Object.new.freeze
+
+  # @api private
+  SHARED_CACHE_REGISTRY = {}
+  # @api private
+  SHARED_CACHE_MUTEX = Mutex.new
+
+  # @api private
+  EXTENSION_REGISTRY = {}
+  # @api private
+  EXTENSION_MUTEX = Mutex.new
+
   include InstanceMethods
 
   # @api private
@@ -102,4 +116,131 @@ module SafeMemoize
     handler = configuration.on_deprecation
     handler ? handler.call(text) : warn(text)
   end
+
+  # Returns the named shared cache store, creating a new in-process
+  # {Stores::Memory} instance if one has not been registered under +name+.
+  #
+  # Use {register_shared_cache} to supply a custom adapter (e.g. Redis) before
+  # any class that references the same name is loaded.
+  #
+  # @param name [String] the logical cache name
+  # @return [Stores::Base]
+  def self.shared_cache(name)
+    SHARED_CACHE_MUTEX.synchronize do
+      SHARED_CACHE_REGISTRY[name] ||= Stores::Memory.new
+    end
+  end
+
+  # Registers a custom store under +name+, replacing any existing entry.
+  #
+  # Must be called *before* any class that references +name+ via +shared_cache:+
+  # is loaded, because the store is captured at +memoize+ definition time.
+  #
+  # @param name [String] the logical cache name
+  # @param store [Stores::Base] any {Stores::Base} subclass instance
+  # @return [Stores::Base] the registered store
+  # @raise [ArgumentError] if +store+ is not a {Stores::Base} instance
+  def self.register_shared_cache(name, store)
+    unless store.is_a?(Stores::Base)
+      raise ArgumentError, "store must be a SafeMemoize::Stores::Base instance (got #{store.class})"
+    end
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY[name] = store }
+  end
+
+  # Clears all entries in the named shared cache without removing it from the
+  # registry. A no-op when no cache is registered under +name+.
+  #
+  # @param name [String]
+  # @return [void]
+  def self.clear_shared_cache(name)
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY[name]&.clear }
+  end
+
+  # Removes the named shared cache from the registry entirely.
+  # Subsequent +shared_cache(name)+ calls will create a fresh store.
+  #
+  # @param name [String]
+  # @return [Stores::Base, nil] the removed store, or +nil+ if not present
+  def self.drop_shared_cache(name)
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY.delete(name) }
+  end
+
+  # Returns a snapshot of the current registry as a plain +Hash+.
+  #
+  # @return [Hash{String => Stores::Base}]
+  def self.shared_caches
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY.dup }
+  end
+
+  # Removes all named shared caches from the registry.
+  #
+  # Useful in test suite +after+ hooks to prevent state leaking between examples.
+  #
+  # @return [void]
+  def self.reset_shared_caches!
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY.clear }
+  end
+
+  # Registers an extension under +name+.
+  #
+  # An extension is any Ruby object that optionally responds to the
+  # {Extension} interface: {Extension#handled_options}, {Extension#process_memoize_option},
+  # and {Extension#dispatch_cache_event}. Use {Extension} as a mixin to get a
+  # convenient DSL for defining these.
+  #
+  # @param name [Symbol, String] a unique identifier for this extension
+  # @param extension [Object] the extension object or module
+  # @return [Object] the registered extension
+  def self.register_extension(name, extension)
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY[name.to_sym] = extension }
+  end
+
+  # Removes an extension from the registry.
+  #
+  # @param name [Symbol, String]
+  # @return [Object, nil] the removed extension, or +nil+ if not present
+  def self.unregister_extension(name)
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.delete(name.to_sym) }
+  end
+
+  # Returns a snapshot of all registered extensions as a +Hash+.
+  #
+  # @return [Hash{Symbol => Object}]
+  def self.extensions
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.dup }
+  end
+
+  # Removes all registered extensions.
+  #
+  # Useful in test suite +after+ hooks to prevent state leaking between examples.
+  #
+  # @return [void]
+  def self.reset_extensions!
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.clear }
+  end
+
+  # Returns the first registered extension that declares it handles +option_name+,
+  # or +nil+ if none does.
+  #
+  # @param option_name [Symbol]
+  # @return [Object, nil]
+  def self.extension_for_option(option_name)
+    sym = option_name.to_sym
+    EXTENSION_MUTEX.synchronize do
+      EXTENSION_REGISTRY.values.find do |ext|
+        ext.respond_to?(:handled_options) && ext.handled_options.include?(sym)
+      end
+    end
+  end
+
+  # Dispatches a cache lifecycle event to all registered extensions that
+  # respond to +dispatch_cache_event+.
+  #
+  # @api private
+  def self.dispatch_extension_events(event_type, klass, method_name, cache_key, record)
+    exts = EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.values.dup }
+    exts.each do |ext|
+      ext.dispatch_cache_event(event_type, klass, method_name, cache_key, record) if ext.respond_to?(:dispatch_cache_event)
+    end
+  end
 end

data/sig/safe_memoize.rbs

@@ -18,11 +18,37 @@ module SafeMemoize
   @__safe_memo_shared_mutex__: Mutex?
   @__safe_memo_shared_lru_order__: Hash[Symbol, Hash[memo_key, true]]?
 
+  UNSET: untyped
+  SHARED_CACHE_REGISTRY: Hash[String, Stores::Base]
+  SHARED_CACHE_MUTEX: Mutex
+  EXTENSION_REGISTRY: Hash[Symbol, untyped]
+  EXTENSION_MUTEX: Mutex
+
   def self.prepended: (Class base) -> void
   def self.configure: () { (Configuration) -> void } -> void
   def self.configuration: () -> Configuration
   def self.reset_configuration!: () -> Configuration
   def self.deprecate: (String subject, message: String, horizon: String) -> void
+  def self.shared_cache: (String name) -> Stores::Base
+  def self.register_shared_cache: (String name, Stores::Base store) -> Stores::Base
+  def self.clear_shared_cache: (String name) -> void
+  def self.drop_shared_cache: (String name) -> Stores::Base?
+  def self.shared_caches: () -> Hash[String, Stores::Base]
+  def self.reset_shared_caches!: () -> void
+  def self.register_extension: (Symbol | String name, untyped extension) -> untyped
+  def self.unregister_extension: (Symbol | String name) -> untyped?
+  def self.extensions: () -> Hash[Symbol, untyped]
+  def self.reset_extensions!: () -> void
+  def self.extension_for_option: (Symbol option_name) -> untyped?
+  def self.dispatch_extension_events: (Symbol event_type, Class klass, Symbol method_name, untyped cache_key, untyped record) -> void
+
+  module Extension
+    def handles_option: (Symbol option_name) { (untyped value, Symbol method_name, Hash[Symbol, untyped] all_options) -> Hash[Symbol, untyped]? } -> void
+    def on_cache_event: (*Symbol event_types) { (Class klass, Symbol method_name, untyped cache_key, untyped record) -> void } -> void
+    def handled_options: () -> Array[Symbol]
+    def process_memoize_option: (Symbol option_name, untyped value, Symbol method_name, Hash[Symbol, untyped] all_options) -> Hash[Symbol, untyped]
+    def dispatch_cache_event: (Symbol event_type, Class klass, Symbol method_name, untyped cache_key, untyped record) -> void
+  end
 
   class Configuration
     attr_accessor default_ttl: Numeric?
@@ -33,15 +59,19 @@ module SafeMemoize
     attr_accessor statsd_client: untyped
     attr_accessor opentelemetry_tracer: untyped
     attr_accessor default_store: Stores::Base?
+    attr_accessor namespace: String?
 
     def initialize: () -> void
   end
 
   module ClassMethods
-    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?store: Stores::Base?, ?fiber_local: bool, ?ractor_safe: bool) -> void
+    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?store: Stores::Base?, ?fiber_local: bool, ?ractor_safe: bool, ?namespace: String?, ?shared_cache: String?, ?cache_bust: (^() -> untyped) | Symbol | nil, ?copy_on_read: bool, **untyped extension_options) -> void
     def safe_memoize_store: () -> Stores::Base?
     def safe_memoize_store=: (Stores::Base?) -> Stores::Base?
-    def memoize_all: (?except: Array[Symbol | String], ?only: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?fiber_local: bool) -> void
+    def safe_memoize_namespace: () -> String?
+    def safe_memoize_namespace=: (String?) -> String?
+    def safe_memoize_options: (**untyped opts) -> Hash[Symbol, untyped]?
+    def memoize_all: (?except: Array[Symbol | String], ?only: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?fiber_local: bool, ?namespace: String?, ?shared_cache: String?, ?copy_on_read: bool) -> void
     def reset_shared_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
     def reset_all_shared_memos: () -> void
     def shared_memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
@@ -55,6 +85,9 @@ module SafeMemoize
     def __safe_memo_shared_mutex__: () -> Mutex
     def __safe_memo_shared_lru_order__: () -> Hash[Symbol, Hash[memo_key, true]]
     def __safe_memo_class_key_generators__: () -> Hash[Symbol, Proc]
+    def __safe_memo_method_namespaces__: () -> Hash[Symbol, String]
+    def __safe_memo_class_cache_bust_generators__: () -> Hash[Symbol, Proc | Symbol]
+    def __safe_memoize_defaults__: () -> Hash[Symbol, untyped]?
     def memoized_method_visibility: (Symbol method_name) -> Symbol
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -39,6 +39,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/FUNDING.yml"
 - ".github/workflows/ci.yml"
 - ".github/workflows/release.yml"
 - ".yardopts"
@@ -61,6 +62,7 @@ files:
 - lib/safe_memoize/class_methods.rb
 - lib/safe_memoize/configuration.rb
 - lib/safe_memoize/custom_key_methods.rb
+- lib/safe_memoize/extension.rb
 - lib/safe_memoize/fiber_local_methods.rb
 - lib/safe_memoize/hooks_methods.rb
 - lib/safe_memoize/inspection_methods.rb