safe_memoize 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcdb1584d3b3306021fa9e49007f686f561cd2658ea811e97fc18d89e36cb20e
-  data.tar.gz: bc69db3f6d77baf031c6a1b92004ca2b4d5c60346b9546ec29388231e2d3d782
+  metadata.gz: 41e3b8e3232ef52d536166c4e701a99a8d7a1e86e2c6d07493d1838d904dbef6
+  data.tar.gz: dac922ad348d3ccf14d8946035b5a0e7709cacc899dcc6e0713da77c980ac6ca
 SHA512:
-  metadata.gz: f1a8bb8cd2ee519a39b90ed96ebac7a700d759e05bc0561225663ee24b6f595660f25da36dda2db4509fb521a9048a38b904760a06e2d09c2347fd52f5011db0
-  data.tar.gz: dc1d3b24ecc9fe4a747f1ba12f2a9af335d61f671f1261203a43ff831fc7460dce8e1adf2142c771ff93d5f278127f9a9a54fe408b4361a8a585cebce8ba65a0
+  metadata.gz: a7f263ac2b16ff248ccf6afa158aaaae5a7fd69cadef68ff6926c3d96257378df8d4295f2eac8278a68de12492128282c1ffea42da95c178de7e5619981c8634
+  data.tar.gz: b50610d8ac36d0c7ff4fe9ed174a7f7864654f4178bc5778a9555eda1d934320b7ee0bcf4de53919e9dfacc35d06d8320f0b9dc8e8a25d6fab6808dfb0c0aab4

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 ## [Unreleased]
 
+## [0.7.0] - 2026-05-18
+
+- Add `memo_preload` to batch-warm multiple cache entries in one call
+  - `obj.memo_preload(:find, [1], [2], [3])` calls the memoized method for each arg set and caches all results
+  - Returns an array of results in the same order as the input arg sets
+  - Computes each entry only once — subsequent calls return from cache
+- Add `on_memo_store` hook that fires whenever a value is written to the cache
+  - Fires on every cache miss (fast path and LRU path)
+  - Also fires when entries are written via `warm_memo` or `load_memo`
+  - Does not fire on cache hits or when a conditional `:if`/`:unless` prevents storing
+  - Fires on the calling instance for `shared: true` misses
+  - Completes the full lifecycle hook set: `on_store`, `on_hit`, `on_miss`, `on_expire`, `on_evict`
+- Add per-method `cache_metrics_reset(:method)` to clear stats for a single method without wiping the rest
+  - `cache_metrics_reset` (no args) still clears all metrics as before
+- Add `SafeMemoize.configure` for global default options
+  - `SafeMemoize.configure { |c| c.default_ttl = 60 }` applies a TTL to all subsequently memoized methods
+  - `SafeMemoize.configure { |c| c.default_max_size = 100 }` sets a global LRU size limit
+  - Per-call options (`ttl:`, `max_size:`) override the global defaults
+  - `SafeMemoize.reset_configuration!` restores defaults to `nil`
+- Add `memo_touch` to reset the expiry clock on a cached entry without recomputing
+  - `memo_touch(:method, *args)` extends the entry's TTL from now using the original TTL window
+  - `memo_touch(:method, *args, ttl: 30)` sets a new TTL explicitly
+  - Returns `true` on success, `false` if the entry is not cached or already expired
+- Add `shared_memo_age` class method to inspect how long ago a shared entry was cached
+- Add `shared_memo_stale?` class method to check whether a shared entry's TTL has elapsed
+- Update RBS type signatures for all new methods and the `Configuration` class
+- Add `key:` option to `memoize` for class-level cache key generation
+  - `memoize :method, key: ->(a, b) { a }` defines a key generator at the class level — calls whose key block returns the same value share one cache entry
+  - Instance-level `memoize_with_custom_key` still takes priority over `key:`
+  - Composes with all existing options (`ttl:`, `max_size:`, `shared:`, `if:`, etc.)
+  - Raises `ArgumentError` if `key:` is not callable
+- Add `shared:` support to `memoize_all` (was already functional via `**options` passthrough; now tested and documented)
+- Add `memo_refresh` to force-recompute a cached entry and store the new value in one call
+- Add `memo_age` to return how many seconds ago an entry was cached (`nil` if not cached or expired)
+- Add `memo_stale?` to check whether a cached entry exists but its TTL has elapsed
+
 ## [0.6.3] - 2026-05-18
 
 - Upgrade `softprops/action-gh-release` from v2 to v3 to resolve Node.js 20 deprecation warning in release workflow

data/lib/safe_memoize/cache_metrics_methods.rb

@@ -26,5 +26,11 @@ module SafeMemoize
     def _reset_cache_metrics
       @__safe_memo_metrics__ = {}
     end
+
+    def _reset_cache_metrics_for(method_name)
+      return unless defined?(@__safe_memo_metrics__) && @__safe_memo_metrics__
+
+      @__safe_memo_metrics__.delete_if { |key, _| key[0] == method_name }
+    end
   end
 end

data/lib/safe_memoize/cache_record_methods.rb

@@ -22,7 +22,7 @@ module SafeMemoize
     end
 
     def memo_record(value, expires_at:)
-      {value: value, expires_at: expires_at}
+      {value: value, expires_at: expires_at, cached_at: Process.clock_gettime(Process::CLOCK_MONOTONIC)}
     end
 
     def memo_record_value(record)

data/lib/safe_memoize/class_methods.rb

@@ -2,10 +2,14 @@
 
 module SafeMemoize
   module ClassMethods
-    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false)
+    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
       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.
@@ -38,6 +42,9 @@ module SafeMemoize
       end
       raise ArgumentError, ":if must be callable" if cond_if && !cond_if.respond_to?(:call)
       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)
+
+      __safe_memo_class_key_generators__[method_name] = key if key
 
       # Normalize to a single "should cache?" predicate
       condition = if cond_if
@@ -79,7 +86,7 @@ module SafeMemoize
                 value = super(*args, **kwargs)
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-                new_record = {value: value, expires_at: memo_expires_at(ttl)}
+                new_record = memo_record(value, expires_at: memo_expires_at(ttl))
 
                 if !condition || condition.call(value)
                   if max_size
@@ -97,6 +104,7 @@ module SafeMemoize
                     lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {}
                     lru[cache_key] = true
                   end
+                  call_memo_hooks(:on_store, cache_key, new_record)
                 end
 
                 record_cache_miss(method_name, args, kwargs, elapsed_time)
@@ -143,6 +151,7 @@ module SafeMemoize
                   @__safe_memo_cache__ ||= {}
                   @__safe_memo_cache__[cache_key] = new_record
                   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)
                 call_memo_hooks(:on_miss, cache_key, new_record)
@@ -166,6 +175,7 @@ module SafeMemoize
             with_memo_lock do
               record_cache_miss(method_name, args, kwargs, 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
 
@@ -225,6 +235,45 @@ module SafeMemoize
       end
     end
 
+    def shared_memo_age(method_name, *args, **kwargs)
+      method_name = method_name.to_sym
+      cache_key = [method_name, args, kwargs]
+
+      __safe_memo_shared_mutex__.synchronize do
+        cache = @__safe_memo_shared_cache__
+        return nil unless cache
+
+        record = cache[cache_key]
+        return nil unless record
+
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return nil if record[:expires_at] && record[:expires_at] <= now
+
+        cached_at = record[:cached_at]
+        return nil unless cached_at
+
+        (now - cached_at).round(6)
+      end
+    end
+
+    def shared_memo_stale?(method_name, *args, **kwargs)
+      method_name = method_name.to_sym
+      cache_key = [method_name, args, kwargs]
+
+      __safe_memo_shared_mutex__.synchronize do
+        cache = @__safe_memo_shared_cache__
+        return false unless cache
+
+        record = cache[cache_key]
+        return false unless record
+
+        expires_at = record[:expires_at]
+        return false unless expires_at
+
+        expires_at <= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+
     def memoize_all(except: [], include_protected: false, include_private: false, **options)
       excluded = Array(except).map(&:to_sym)
 
@@ -253,6 +302,10 @@ module SafeMemoize
       @__safe_memo_shared_lru_order__ ||= {}
     end
 
+    def __safe_memo_class_key_generators__
+      @__safe_memo_class_key_generators__ ||= {}
+    end
+
     def memoized_method_visibility(method_name)
       return :private if private_method_defined?(method_name)
       return :protected if protected_method_defined?(method_name)

data/lib/safe_memoize/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  class Configuration
+    attr_accessor :default_ttl, :default_max_size
+
+    def initialize
+      @default_ttl = nil
+      @default_max_size = nil
+    end
+  end
+end

data/lib/safe_memoize/custom_key_methods.rb

@@ -18,16 +18,13 @@ module SafeMemoize
     def compute_cache_key(method_name, args, kwargs)
       method_name = method_name.to_sym
 
-      # Check if a custom key generator is registered
-      custom_key_block = custom_key_store[method_name]
-
-      if custom_key_block
-        # Call the custom key generator with args and kwargs
-        custom_key = custom_key_block.call(*args, **kwargs)
-        # Wrap in a standard format: [method, custom_key]
-        [method_name, custom_key]
+      # 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)]
       else
-        # Use default key generation
         safe_memo_cache_key(method_name, args, kwargs)
       end
     end

data/lib/safe_memoize/hooks_methods.rb

@@ -5,13 +5,13 @@ module SafeMemoize
     private
 
     def memo_hook_store
-      @__safe_memo_hooks__ ||= {on_expire: [], on_evict: [], on_hit: [], on_miss: []}
+      @__safe_memo_hooks__ ||= {on_expire: [], on_evict: [], on_hit: [], on_miss: [], on_store: []}
     end
 
     def register_memo_hook(hook_type, &block)
       raise ArgumentError, "block required" unless block
 
-      valid_hooks = [:on_expire, :on_evict, :on_hit, :on_miss]
+      valid_hooks = [:on_expire, :on_evict, :on_hit, :on_miss, :on_store]
       raise ArgumentError, "invalid hook type: #{hook_type}" unless valid_hooks.include?(hook_type)
 
       memo_hook_store[hook_type] << block
@@ -26,7 +26,7 @@ module SafeMemoize
       if hook_type
         memo_hook_store[hook_type] = []
       else
-        @__safe_memo_hooks__ = {on_expire: [], on_evict: [], on_hit: [], on_miss: []}
+        @__safe_memo_hooks__ = {on_expire: [], on_evict: [], on_hit: [], on_miss: [], on_store: []}
       end
     end
   end

data/lib/safe_memoize/public_methods.rb

@@ -75,6 +75,12 @@ module SafeMemoize
       register_memo_hook(:on_miss, &block)
     end
 
+    def on_memo_store(&block)
+      raise ArgumentError, "block required" unless block
+
+      register_memo_hook(:on_store, &block)
+    end
+
     def clear_memo_hooks(hook_type = nil)
       with_memo_lock do
         _clear_memo_hooks(hook_type)
@@ -90,12 +96,21 @@ module SafeMemoize
 
       with_memo_lock do
         @__safe_memo_cache__ ||= {}
-        @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: memo_expires_at(ttl))
+        record = memo_record(value, expires_at: memo_expires_at(ttl))
+        @__safe_memo_cache__[cache_key] = record
+        call_memo_hooks(:on_store, cache_key, record)
       end
 
       value
     end
 
+    def memo_preload(method_name, *arg_sets)
+      method_name = method_name.to_sym
+      arg_sets.map do |args|
+        send(method_name, *Array(args))
+      end
+    end
+
     def dump_memo(method_name = nil)
       method_name = method_name&.to_sym
 
@@ -113,13 +128,74 @@ module SafeMemoize
       with_memo_lock do
         @__safe_memo_cache__ ||= {}
         snapshot.each do |cache_key, value|
-          @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: nil)
+          record = memo_record(value, expires_at: nil)
+          @__safe_memo_cache__[cache_key] = record
+          call_memo_hooks(:on_store, cache_key, record)
         end
       end
 
       nil
     end
 
+    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)
+
+      with_memo_lock do
+        cache = memo_cache_or_nil
+        return false unless cache
+
+        record = cache[cache_key]
+        return false unless record && memo_record_live?(record)
+
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        effective_ttl = if ttl
+          ttl
+        elsif record[:expires_at] && record[:cached_at]
+          record[:expires_at] - record[:cached_at]
+        end
+
+        record[:expires_at] = effective_ttl ? now + effective_ttl : nil
+        record[:cached_at] = now
+        true
+      end
+    end
+
+    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
+
+    def memo_age(method_name, *args, **kwargs)
+      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+
+      with_memo_lock do
+        record = memo_cache_record(cache_key)
+        return nil unless record
+
+        cached_at = record[:cached_at]
+        return nil unless cached_at
+
+        (Process.clock_gettime(Process::CLOCK_MONOTONIC) - cached_at).round(6)
+      end
+    end
+
+    def memo_stale?(method_name, *args, **kwargs)
+      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+
+      with_memo_lock do
+        cache = memo_cache_or_nil
+        return false unless cache
+
+        record = cache[cache_key]
+        return false unless record
+
+        !memo_record_live?(record)
+      end
+    end
+
     def reset_memo(method_name, *args, **kwargs)
       method_name = method_name.to_sym
 

data/lib/safe_memoize/public_metrics_methods.rb

@@ -30,9 +30,13 @@ module SafeMemoize
       cache_stats[:miss_rate]
     end
 
-    def cache_metrics_reset
+    def cache_metrics_reset(method_name = nil)
       with_memo_lock do
-        _reset_cache_metrics
+        if method_name
+          _reset_cache_metrics_for(method_name.to_sym)
+        else
+          _reset_cache_metrics
+        end
       end
     end
 

data/lib/safe_memoize/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SafeMemoize
-  VERSION = "0.6.3"
+  VERSION = "0.7.0"
 end

data/lib/safe_memoize.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "safe_memoize/version"
+require_relative "safe_memoize/configuration"
 require_relative "safe_memoize/class_methods"
 require_relative "safe_memoize/public_methods"
 require_relative "safe_memoize/cache_store_methods"
@@ -22,4 +23,16 @@ module SafeMemoize
   def self.prepended(base)
     base.extend(ClassMethods)
   end
+
+  def self.configure
+    yield configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
 end

data/sig/safe_memoize.rbs

@@ -5,7 +5,7 @@ module SafeMemoize
   type default_memo_key = [Symbol, Array[untyped], Hash[Symbol, untyped]]
   type custom_memo_key = [Symbol, untyped]
   type memo_key = default_memo_key | custom_memo_key
-  type memo_record = { value: untyped, expires_at: Float? }
+  type memo_record = { value: untyped, expires_at: Float?, cached_at: Float }
 
   @__safe_memo_cache__: Hash[memo_key, memo_record]?
   @__safe_memo_mutex__: Mutex?
@@ -14,20 +14,33 @@ module SafeMemoize
   @__safe_memo_shared_lru_order__: Hash[Symbol, Hash[memo_key, true]]?
 
   def self.prepended: (Class base) -> void
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.configuration: () -> Configuration
+  def self.reset_configuration!: () -> Configuration
+
+  class Configuration
+    attr_accessor default_ttl: Numeric?
+    attr_accessor default_max_size: Integer?
+
+    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) -> void
-    def memoize_all: (?except: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?) -> 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)?) -> void
+    def memoize_all: (?except: 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)?) -> 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
     def shared_memo_count: (?Symbol | String method_name) -> Integer
+    def shared_memo_age: (Symbol | String method_name, *untyped args, **untyped kwargs) -> Float?
+    def shared_memo_stale?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
 
     private
 
     def __safe_memo_shared_cache__: () -> Hash[memo_key, memo_record]
     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 memoized_method_visibility: (Symbol method_name) -> Symbol
   end
 
@@ -43,10 +56,16 @@ module SafeMemoize
     def on_memo_evict: { (memo_key cache_key, memo_record record) -> untyped } -> void
     def on_memo_hit: { (memo_key cache_key, memo_record record) -> untyped } -> void
     def on_memo_miss: { (memo_key cache_key, memo_record record) -> untyped } -> void
+    def on_memo_store: { (memo_key cache_key, memo_record record) -> untyped } -> void
     def clear_memo_hooks: (Symbol? hook_type) -> void
     def warm_memo: (Symbol | String method_name, *untyped args, ?ttl: Numeric?, **untyped kwargs) { () -> untyped } -> untyped
+    def memo_preload: (Symbol | String method_name, *Array[untyped] arg_sets) -> Array[untyped]
     def dump_memo: (?Symbol | String method_name) -> Hash[memo_key, untyped]
     def load_memo: (Hash[memo_key, untyped] snapshot) -> nil
+    def memo_touch: (Symbol | String method_name, *untyped args, ?ttl: Numeric?, **untyped kwargs) -> bool
+    def memo_refresh: (Symbol | String method_name, *untyped args, **untyped kwargs) -> untyped
+    def memo_age: (Symbol | String method_name, *untyped args, **untyped kwargs) -> Float?
+    def memo_stale?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
     def reset_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
     def reset_all_memos: () -> void
   end
@@ -92,11 +111,11 @@ module SafeMemoize
   end
 
   module HooksMethods
-    @__safe_memo_hooks__: { on_expire: Array[Proc], on_evict: Array[Proc], on_hit: Array[Proc], on_miss: Array[Proc] }?
+    @__safe_memo_hooks__: { on_expire: Array[Proc], on_evict: Array[Proc], on_hit: Array[Proc], on_miss: Array[Proc], on_store: Array[Proc] }?
 
     private
 
-    def memo_hook_store: () -> { on_expire: Array[Proc], on_evict: Array[Proc], on_hit: Array[Proc], on_miss: Array[Proc] }
+    def memo_hook_store: () -> { on_expire: Array[Proc], on_evict: Array[Proc], on_hit: Array[Proc], on_miss: Array[Proc], on_store: Array[Proc] }
     def register_memo_hook: (Symbol hook_type) { (memo_key cache_key, memo_record record) -> untyped } -> void
     def call_memo_hooks: (Symbol hook_type, memo_key cache_key, memo_record record) -> void
     def _clear_memo_hooks: (Symbol? hook_type) -> void
@@ -118,7 +137,7 @@ module SafeMemoize
     def cache_stats_for: (Symbol | String method_name) -> Hash[Symbol, untyped]
     def cache_hit_rate: () -> Float
     def cache_miss_rate: () -> Float
-    def cache_metrics_reset: () -> void
+    def cache_metrics_reset: (?Symbol | String method_name) -> void
 
     private
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.7.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -50,6 +50,7 @@ files:
 - lib/safe_memoize/cache_record_methods.rb
 - lib/safe_memoize/cache_store_methods.rb
 - lib/safe_memoize/class_methods.rb
+- lib/safe_memoize/configuration.rb
 - lib/safe_memoize/custom_key_methods.rb
 - lib/safe_memoize/hooks_methods.rb
 - lib/safe_memoize/inspection_methods.rb