safe_memoize 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64bc56c4cd1fc255353c579f2e740b88516bafc0bfbd9365f605b1ef8af36b6f
-  data.tar.gz: b37f9d850b6d599fda50ef47f4a3e03b21484040a9efabaabba63d9891d0be6f
+  metadata.gz: 036e876f53d96a1c6ca54ae257bb631c30b0b973a0f0bed77b6fafd92f187c93
+  data.tar.gz: 2d09472476154ff424940a59666b5a891d95156d44a829025ad9929f92fed24d
 SHA512:
-  metadata.gz: aab068ebb5b277b6b74f79ea2226c81efe3eb620a3b54630339238c3fd536797261af12e84ed446ccd325cf5902180f3c9bd2b00c2ba591a589c829d6223ea30
-  data.tar.gz: c75b60edcc7a189d0e062eb470b64874de56a916ac8369ceb1a7992bc23e7ec1a2303550f620da0be35fc75ad2d28419faba0ddc0c089a5875203004af73272e
+  metadata.gz: d0004ea27b6d21d3e32df92f782ddb0d4a768212d4344e3d4e4793d6eb44bb481b309a05a875bb166e1633f3be8c08e4580b006f512dd74723383e11516ff5c4
+  data.tar.gz: 6a81f21e5e4347a723305893cfcf3dbe8b4b71bdb0ef3767774276e7046893e5ec12471898b6ecfc87df135b0462691324fa16808369a5ad98fc6e54d6ce1a14

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.6.1] - 2026-05-17
+
+- Fix `memo_keys` and `memo_values` showing `args: custom_key, kwargs: nil` for methods using `memoize_with_custom_key` — now surfaces as `custom_key:`
+- Refactor `cache_stats` / `cache_stats_for` to share aggregation logic via private helpers
+
+## [0.6.0] - 2026-05-17
+
+- Fix TTL clock starting at `memoize` definition time instead of first method call
+- Fix metrics key silently dropping kwargs, causing methods that differ only in kwargs to share a metrics bucket
+- Fix stale LRU references remaining after expired entries are pruned
+- Add `ttl:` option to `warm_memo` so warmed entries can be given an expiry
+- Add `max_size:` support for `shared: true` memoization (class-level LRU eviction)
+- Add `ttl_refresh: true` option on `memoize` for sliding window TTL — resets expiry on every cache hit
+- Add `include_protected:` and `include_private:` options to `memoize_all`
+- Add `memo_ttl_remaining` for TTL introspection — returns seconds until expiry, `nil` for no TTL, `0` for uncached/expired
+
 ## [0.5.0] - 2026-05-17
 
 - Drop support for Ruby 3.2 (EOL); minimum required version is now Ruby 3.3
@@ -15,7 +31,7 @@
   - All instances share one cache; the method is computed only once regardless of how many objects exist
   - Class-level invalidation: `reset_shared_memo`, `reset_all_shared_memos`
   - Class-level inspection: `shared_memoized?`, `shared_memo_count`
-  - Supports `ttl:`, `if:`, and `unless:` options
+    - Supports `ttl:`, `if:`, and `unless:` options
   - Instance hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`) fire on the calling instance
 - Add `memoize_all` to memoize every public method defined on the class in one call
   - Accepts all options supported by `memoize` (`ttl:`, `max_size:`, `if:`, `unless:`)

data/README.md

@@ -4,7 +4,7 @@ Thread-safe memoization for Ruby that correctly handles `nil` and `false` values
 
 SafeMemoize is a production-ready, zero-dependency memoization library for Ruby. It wraps methods with a `prepend`-based cache that handles everything the standard `||=` idiom gets wrong: `nil` and `false` return values are cached correctly, per-argument result maps eliminate redundant computation for parameterized methods, and a per-instance `Mutex` with double-check locking makes the whole thing safe under concurrent load.
 
-Beyond the basics, SafeMemoize ships with TTL expiration, LRU cache size capping, conditional caching via `if:`/`unless:` predicates, lifecycle hooks for cache hits, evictions, and expirations, per-instance metrics (hit rate, miss rate, average computation time), targeted and bulk cache invalidation, custom cache key generators, and rich introspection helpers (`memoized?`, `memo_count`, `memo_keys`, `memo_values`). It preserves method visibility (public, protected, and private) and requires no runtime dependencies.
+Beyond the basics, SafeMemoize ships with TTL expiration (including sliding window refresh via `ttl_refresh:`), LRU cache size capping, conditional caching via `if:`/`unless:` predicates, lifecycle hooks for cache hits, evictions, and expirations, per-instance metrics (hit rate, miss rate, average computation time), targeted and bulk cache invalidation, custom cache key generators, and rich introspection helpers (`memoized?`, `memo_count`, `memo_keys`, `memo_values`, `memo_ttl_remaining`). It preserves method visibility (public, protected, and private) and requires no runtime dependencies.
 
 ## The Problem
 
@@ -31,14 +31,16 @@ SafeMemoize uses `Hash#key?` to distinguish "not yet cached" from "cached nil/fa
 - [Includes a `memo_keys` helper for inspecting cached signatures](#cache-inspection)
 - [Includes a `memo_values` helper for inspecting cached signatures and values](#cache-inspection)
 - [Optional TTL expiration support for cached entries](#ttl-expiration)
+- [Sliding window TTL via `ttl_refresh: true`](#sliding-window-ttl)
 - [Optional LRU cache size limit per method via `max_size:`](#lru-cache-size-limit)
 - [Conditional caching via `if:` and `unless:` predicates](#conditional-caching)
 - [Lifecycle hooks for hit, miss, eviction, and expiration events](#lifecycle-hooks)
 - [Per-instance cache metrics (hit rate, miss rate, computation time)](#cache-metrics)
 - [Cache warm-up, export, and restore (`warm_memo`, `dump_memo`, `load_memo`)](#cache-warm-up-and-persistence)
-- [Class-level shared cache via `shared: true`](#shared-cache)
-- [Bulk memoization via `memoize_all`](#bulk-memoization)
+- [Class-level shared cache via `shared: true` with optional LRU](#shared-cache)
+- [Bulk memoization via `memoize_all` (public, protected, and private)](#bulk-memoization)
 - [Custom cache key generation per method](#custom-cache-keys)
+- [TTL introspection via `memo_ttl_remaining`](#cache-inspection)
 
 ## Installation
 
@@ -203,6 +205,23 @@ end
 
 With a TTL, cached values expire automatically after the given number of seconds. The next call recomputes and refreshes the cache.
 
+### Sliding window TTL
+
+Add `ttl_refresh: true` to reset the expiry clock on every cache hit, so the entry only expires after a full TTL of inactivity:
+
+```ruby
+class SessionService
+  prepend SafeMemoize
+
+  def user_data(user_id)
+    fetch_from_db(user_id)
+  end
+  memoize :user_data, ttl: 300, ttl_refresh: true
+end
+```
+
+Without `ttl_refresh:`, the entry expires 300 seconds after it was first cached. With it, the clock resets on every read — the entry is evicted only if the method goes 300 seconds without being called. `ttl_refresh: true` requires `ttl:` to be set and works with both per-instance and `shared: true` memoization.
+
 ### LRU cache size limit
 
 Pass `max_size:` to cap how many entries a method can hold. When the limit is reached the least-recently-used entry is evicted to make room:
@@ -282,6 +301,12 @@ obj.warm_memo(:find, 42) { cached_user }
 obj.warm_memo(:search, "ruby", page: 2) { cached_results }
 ```
 
+Pass `ttl:` to give the warmed entry an expiry:
+
+```ruby
+obj.warm_memo(:current_quote, ttl: 60) { cached_quote }
+```
+
 Useful for seeding the cache from a persistent store on startup, or overriding a cached value in tests.
 
 #### Exporting and restoring the cache
@@ -349,9 +374,15 @@ ConfigService.shared_memo_count                       # Total shared cached entr
 ConfigService.shared_memo_count(:find)                # Entries for one method
 ```
 
-`shared: true` supports `ttl:`, `if:`, and `unless:` options. `max_size:` is not supported (shared LRU may be added in a future release).
+`shared: true` supports `ttl:`, `ttl_refresh:`, `if:`, `unless:`, and `max_size:` options.
+
+Pass `max_size:` to cap how many entries are kept across all instances. Eviction is LRU, tracked at the class level:
+
+```ruby
+memoize :find, shared: true, max_size: 500
+```
 
-Hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`) fire on the calling instance as usual.
+Hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`, `on_memo_evict`) fire on the calling instance as usual.
 
 ### Bulk memoization
 
@@ -391,7 +422,15 @@ Use `except:` to skip specific methods:
 memoize_all except: [:version, :name]
 ```
 
-Only public methods defined directly on the class are memoized — inherited, private, and protected methods are not affected.
+By default only public methods defined directly on the class are memoized. Use `include_protected:` or `include_private:` to opt those visibilities in:
+
+```ruby
+memoize_all include_protected: true
+memoize_all include_private: true
+memoize_all include_protected: true, include_private: true
+```
+
+Inherited methods are never affected regardless of visibility.
 
 ### Custom cache keys
 
@@ -447,6 +486,10 @@ obj.memo_keys                             # All cached signatures with method, a
 obj.memo_keys(:search)                    # Cached signatures for one method
 obj.memo_values                           # Cached signatures and values for all methods
 obj.memo_values(:search)                  # Cached signatures and values for one method
+
+obj.memo_ttl_remaining(:current_quote)           # => 47.231 (seconds until expiry)
+obj.memo_ttl_remaining(:current_user)            # => nil    (no TTL set)
+obj.memo_ttl_remaining(:find, 42)                # => 0      (not cached or already expired)
 ```
 
 ### Cache metrics

data/lib/safe_memoize/cache_metrics_methods.rb

@@ -8,15 +8,15 @@ module SafeMemoize
       @__safe_memo_metrics__ ||= {}
     end
 
-    def record_cache_hit(method_name, args)
-      cache_key = safe_memo_cache_key(method_name, args, {})
+    def record_cache_hit(method_name, args, kwargs)
+      cache_key = safe_memo_cache_key(method_name, args, kwargs)
       metrics = memo_metrics_store
       metrics[cache_key] ||= {hits: 0, misses: 0, total_time: 0.0}
       metrics[cache_key][:hits] += 1
     end
 
-    def record_cache_miss(method_name, args, computation_time)
-      cache_key = safe_memo_cache_key(method_name, args, {})
+    def record_cache_miss(method_name, args, kwargs, computation_time)
+      cache_key = safe_memo_cache_key(method_name, args, kwargs)
       metrics = memo_metrics_store
       metrics[cache_key] ||= {hits: 0, misses: 0, total_time: 0.0}
       metrics[cache_key][:misses] += 1

data/lib/safe_memoize/cache_record_methods.rb

@@ -42,6 +42,7 @@ module SafeMemoize
       cache.delete_if do |cache_key, record|
         if !memo_record_live?(record)
           call_memo_hooks(:on_expire, cache_key, record)
+          lru_remove(cache_key[0], cache_key)
           true
         else
           false

data/lib/safe_memoize/cache_store_methods.rb

@@ -39,7 +39,7 @@ module SafeMemoize
       memo_record_value(record)
     end
 
-    def memo_fetch_or_store(cache_key, expires_at: nil)
+    def memo_fetch_or_store(cache_key, ttl: nil)
       memo_mutex!.synchronize do
         @__safe_memo_cache__ ||= {}
 
@@ -49,7 +49,7 @@ module SafeMemoize
           memo_record_value(record)
         else
           value = yield
-          @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: expires_at)
+          @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: memo_expires_at(ttl))
 
           value
         end

data/lib/safe_memoize/class_methods.rb

@@ -2,16 +2,20 @@
 
 module SafeMemoize
   module ClassMethods
-    def memoize(method_name, ttl: nil, max_size: nil, if: nil, unless: nil, shared: false)
+    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false)
       method_name = method_name.to_sym
       visibility = memoized_method_visibility(method_name)
 
+      # :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
+
         ttl = Float(ttl)
         raise ArgumentError, "ttl must be non-negative" if ttl < 0
 
@@ -27,7 +31,7 @@ module SafeMemoize
         max_size
       end
 
-      raise ArgumentError, "max_size: is not supported with shared: true" if shared && max_size
+      raise ArgumentError, "ttl_refresh: requires a ttl: to be set" if ttl_refresh && ttl.nil?
 
       if cond_if && cond_unless
         raise ArgumentError, "cannot specify both :if and :unless"
@@ -42,8 +46,6 @@ module SafeMemoize
         ->(result) { !cond_unless.call(result) }
       end
 
-      expires_at = ttl && Process.clock_gettime(Process::CLOCK_MONOTONIC) + ttl
-
       if shared
         klass = self
         shared_mutex = klass.send(:__safe_memo_shared_mutex__)
@@ -61,7 +63,13 @@ module SafeMemoize
               record_live = record && (record[:expires_at].nil? || record[:expires_at] > now)
 
               if record_live
-                record_cache_hit(method_name, args)
+                if max_size
+                  lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {}
+                  lru.delete(cache_key)
+                  lru[cache_key] = true
+                end
+                record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
+                record_cache_hit(method_name, args, kwargs)
                 call_memo_hooks(:on_hit, cache_key, record)
                 record[:value]
               else
@@ -71,10 +79,27 @@ module SafeMemoize
                 value = super(*args, **kwargs)
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-                new_record = {value: value, expires_at: expires_at}
-                shared_cache[cache_key] = new_record unless condition && !condition.call(value)
+                new_record = {value: value, expires_at: memo_expires_at(ttl)}
 
-                record_cache_miss(method_name, args, elapsed_time)
+                if !condition || condition.call(value)
+                  if max_size
+                    lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {}
+                    lru.delete_if { |key, _| !shared_cache.key?(key) }
+                    if lru.size >= max_size
+                      lru_key = lru.keys.first
+                      lru.delete(lru_key)
+                      evicted = shared_cache.delete(lru_key)
+                      call_memo_hooks(:on_evict, lru_key, evicted) if evicted
+                    end
+                  end
+                  shared_cache[cache_key] = new_record
+                  if max_size
+                    lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {}
+                    lru[cache_key] = true
+                  end
+                end
+
+                record_cache_miss(method_name, args, kwargs, elapsed_time)
                 call_memo_hooks(:on_miss, cache_key, new_record)
 
                 value
@@ -97,13 +122,14 @@ module SafeMemoize
 
           cache_key = compute_cache_key(method_name, args, kwargs)
 
-          if max_size || condition
-            # Locked path: used when LRU tracking or conditional storage is needed.
+          if max_size || condition || ttl_refresh
+            # Locked path: used when LRU tracking, conditional storage, or TTL refresh is needed.
             memo_mutex!.synchronize do
               record = memo_cache_record(cache_key)
               if record
                 lru_touch(method_name, cache_key) if max_size
-                record_cache_hit(method_name, args)
+                record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
+                record_cache_hit(method_name, args, kwargs)
                 call_memo_hooks(:on_hit, cache_key, record)
                 memo_record_value(record)
               else
@@ -111,14 +137,14 @@ module SafeMemoize
                 value = super(*args, **kwargs)
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-                new_record = memo_record(value, expires_at: expires_at)
+                new_record = memo_record(value, expires_at: memo_expires_at(ttl))
                 if !condition || condition.call(value)
                   lru_evict_if_over_limit(method_name, max_size) if max_size
                   @__safe_memo_cache__ ||= {}
                   @__safe_memo_cache__[cache_key] = new_record
                   lru_touch(method_name, cache_key) if max_size
                 end
-                record_cache_miss(method_name, args, elapsed_time)
+                record_cache_miss(method_name, args, kwargs, elapsed_time)
                 call_memo_hooks(:on_miss, cache_key, new_record)
 
                 value
@@ -127,18 +153,18 @@ module SafeMemoize
           else
             # Fast path: check without lock
             if (record = memo_cache_record(cache_key))
-              record_cache_hit(method_name, args)
+              record_cache_hit(method_name, args, kwargs)
               call_memo_hooks(:on_hit, cache_key, record)
               return memo_record_value(record)
             end
 
             # Cache miss - compute and store
             start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            result = memo_fetch_or_store(cache_key, expires_at: expires_at) { super(*args, **kwargs) }
+            result = memo_fetch_or_store(cache_key, ttl: ttl) { super(*args, **kwargs) }
             elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
             with_memo_lock do
-              record_cache_miss(method_name, args, elapsed_time)
+              record_cache_miss(method_name, args, kwargs, elapsed_time)
               new_record = memo_cache_record(cache_key)
               call_memo_hooks(:on_miss, cache_key, new_record)
             end
@@ -155,21 +181,23 @@ module SafeMemoize
 
     def reset_shared_memo(method_name, *args, **kwargs)
       method_name = method_name.to_sym
-      matcher = if args.empty? && kwargs.empty?
-        ->(key) { key[0] == method_name }
-      else
-        cache_key = [method_name, args, kwargs]
-        ->(key) { key == cache_key }
-      end
+      specific_key = (args.empty? && kwargs.empty?) ? nil : [method_name, args, kwargs]
 
       __safe_memo_shared_mutex__.synchronize do
-        __safe_memo_shared_cache__.delete_if { |key, _| matcher.call(key) }
+        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_lru_order__.delete(method_name)
+        end
       end
     end
 
     def reset_all_shared_memos
       __safe_memo_shared_mutex__.synchronize do
         @__safe_memo_shared_cache__ = {}
+        @__safe_memo_shared_lru_order__ = {}
       end
     end
 
@@ -197,9 +225,14 @@ module SafeMemoize
       end
     end
 
-    def memoize_all(except: [], **options)
+    def memoize_all(except: [], include_protected: false, include_private: false, **options)
       excluded = Array(except).map(&:to_sym)
-      public_instance_methods(false).each do |method_name|
+
+      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)
 
         memoize(method_name, **options)
@@ -216,6 +249,10 @@ module SafeMemoize
       @__safe_memo_shared_mutex__ ||= Mutex.new
     end
 
+    def __safe_memo_shared_lru_order__
+      @__safe_memo_shared_lru_order__ ||= {}
+    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/inspection_methods.rb

@@ -53,9 +53,16 @@ module SafeMemoize
     end
 
     def memo_projection(cache_key, value, include_method:, include_value:)
-      method_name, args, kwargs = cache_key
+      # 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
+        payload = {custom_key: custom_key}
+      else
+        method_name, args, kwargs = cache_key
+        payload = {args: args, kwargs: kwargs}
+      end
 
-      payload = {args: args, kwargs: kwargs}
       payload[:method] = method_name if include_method
       payload[:value] = memo_record_value(value) if include_value
       payload

data/lib/safe_memoize/lru_methods.rb

@@ -38,6 +38,11 @@ module SafeMemoize
       call_memo_hooks(:on_evict, lru_cache_key, record) if record
     end
 
+    # Remove a single cache key from LRU tracking. Called when an entry expires.
+    def lru_remove(method_name, cache_key)
+      lru_order_store[method_name]&.delete(cache_key)
+    end
+
     # Clear all LRU tracking state. Called by reset_all_memos.
     def lru_clear_all
       @__safe_memo_lru_order__ = {}

data/lib/safe_memoize/public_methods.rb

@@ -12,6 +12,21 @@ module SafeMemoize
       end
     end
 
+    def memo_ttl_remaining(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 0 unless record
+
+        expires_at = record[:expires_at]
+        return nil unless expires_at
+
+        remaining = expires_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        (remaining > 0) ? remaining.round(6) : 0
+      end
+    end
+
     def memo_count(*method_name)
       scoped_method = safe_memo_scoped_method(method_name)
 
@@ -66,7 +81,7 @@ module SafeMemoize
       end
     end
 
-    def warm_memo(method_name, *args, **kwargs, &block)
+    def warm_memo(method_name, *args, ttl: nil, **kwargs, &block)
       raise ArgumentError, "block required" unless block
 
       method_name = method_name.to_sym
@@ -75,7 +90,7 @@ module SafeMemoize
 
       with_memo_lock do
         @__safe_memo_cache__ ||= {}
-        @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: nil)
+        @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: memo_expires_at(ttl))
       end
 
       value

data/lib/safe_memoize/public_metrics_methods.rb

@@ -5,53 +5,9 @@ module SafeMemoize
     def cache_stats
       with_memo_lock do
         metrics = memo_metrics_store
+        return empty_stats if metrics.empty?
 
-        if metrics.empty?
-          return {
-            total_hits: 0,
-            total_misses: 0,
-            hit_rate: 0.0,
-            miss_rate: 0.0,
-            average_computation_time: 0.0,
-            entries: []
-          }
-        end
-
-        total_hits = metrics.values.sum { |m| m[:hits] }
-        total_misses = metrics.values.sum { |m| m[:misses] }
-        total_time = metrics.values.sum { |m| m[:total_time] }
-        total_calls = total_hits + total_misses
-
-        hit_rate = total_calls.zero? ? 0.0 : (total_hits.to_f / total_calls * 100).round(2)
-        miss_rate = total_calls.zero? ? 0.0 : (total_misses.to_f / total_calls * 100).round(2)
-        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
-          entry_hit_rate = if (stats[:hits] + stats[:misses]).zero?
-            0.0
-          else
-            (stats[:hits].to_f / (stats[:hits] + stats[:misses]) * 100).round(2)
-          end
-
-          {
-            method: method_name,
-            args: args,
-            hits: stats[:hits],
-            misses: stats[:misses],
-            hit_rate: entry_hit_rate,
-            computation_time: stats[:total_time].round(6)
-          }
-        end
-
-        {
-          total_hits: total_hits,
-          total_misses: total_misses,
-          hit_rate: hit_rate,
-          miss_rate: miss_rate,
-          average_computation_time: avg_time,
-          entries: entries
-        }
+        aggregate_metrics(metrics, include_method: true)
       end
     end
 
@@ -59,67 +15,19 @@ module SafeMemoize
       method_name = method_name.to_sym
 
       with_memo_lock do
-        metrics = memo_metrics_store
-        method_metrics = metrics.select { |key, _| key[0] == method_name }
-
-        if method_metrics.empty?
-          return {
-            method: method_name,
-            total_hits: 0,
-            total_misses: 0,
-            hit_rate: 0.0,
-            miss_rate: 0.0,
-            average_computation_time: 0.0,
-            entries: []
-          }
-        end
-
-        total_hits = method_metrics.values.sum { |m| m[:hits] }
-        total_misses = method_metrics.values.sum { |m| m[:misses] }
-        total_time = method_metrics.values.sum { |m| m[:total_time] }
-        total_calls = total_hits + total_misses
-
-        hit_rate = total_calls.zero? ? 0.0 : (total_hits.to_f / total_calls * 100).round(2)
-        miss_rate = total_calls.zero? ? 0.0 : (total_misses.to_f / total_calls * 100).round(2)
-        avg_time = total_misses.zero? ? 0.0 : (total_time / total_misses).round(6)
-
-        entries = method_metrics.map do |cache_key, stats|
-          _method, args, _kwargs = cache_key
-          entry_hit_rate = if (stats[:hits] + stats[:misses]).zero?
-            0.0
-          else
-            (stats[:hits].to_f / (stats[:hits] + stats[:misses]) * 100).round(2)
-          end
-
-          {
-            args: args,
-            hits: stats[:hits],
-            misses: stats[:misses],
-            hit_rate: entry_hit_rate,
-            computation_time: stats[:total_time].round(6)
-          }
-        end
+        metrics = memo_metrics_store.select { |key, _| key[0] == method_name }
+        return empty_stats.merge(method: method_name) if metrics.empty?
 
-        {
-          method: method_name,
-          total_hits: total_hits,
-          total_misses: total_misses,
-          hit_rate: hit_rate,
-          miss_rate: miss_rate,
-          average_computation_time: avg_time,
-          entries: entries
-        }
+        aggregate_metrics(metrics, include_method: false).merge(method: method_name)
       end
     end
 
     def cache_hit_rate
-      stats = cache_stats
-      stats[:hit_rate]
+      cache_stats[:hit_rate]
     end
 
     def cache_miss_rate
-      stats = cache_stats
-      stats[:miss_rate]
+      cache_stats[:miss_rate]
     end
 
     def cache_metrics_reset
@@ -127,5 +35,43 @@ module SafeMemoize
         _reset_cache_metrics
       end
     end
+
+    private
+
+    def aggregate_metrics(metrics, include_method:)
+      total_hits = metrics.values.sum { |m| m[:hits] }
+      total_misses = metrics.values.sum { |m| m[:misses] }
+      total_time = metrics.values.sum { |m| m[:total_time] }
+      total_calls = total_hits + total_misses
+
+      hit_rate = total_calls.zero? ? 0.0 : (total_hits.to_f / total_calls * 100).round(2)
+      miss_rate = total_calls.zero? ? 0.0 : (total_misses.to_f / total_calls * 100).round(2)
+      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
+        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
+      end
+
+      {
+        total_hits: total_hits,
+        total_misses: total_misses,
+        hit_rate: hit_rate,
+        miss_rate: miss_rate,
+        average_computation_time: avg_time,
+        entries: entries
+      }
+    end
+
+    def empty_stats
+      {total_hits: 0, total_misses: 0, hit_rate: 0.0, miss_rate: 0.0,
+       average_computation_time: 0.0, entries: []}
+    end
   end
 end

data/lib/safe_memoize/version.rb

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

data/sig/safe_memoize.rbs

@@ -11,12 +11,13 @@ module SafeMemoize
   @__safe_memo_mutex__: Mutex?
   @__safe_memo_shared_cache__: Hash[memo_key, memo_record]?
   @__safe_memo_shared_mutex__: Mutex?
+  @__safe_memo_shared_lru_order__: Hash[Symbol, Hash[memo_key, true]]?
 
   def self.prepended: (Class base) -> void
 
   module ClassMethods
-    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool) -> void
-    def memoize_all: (?except: Array[Symbol | String], ?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) -> 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 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
@@ -26,6 +27,7 @@ module SafeMemoize
 
     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 memoized_method_visibility: (Symbol method_name) -> Symbol
   end
 
@@ -33,6 +35,7 @@ module SafeMemoize
     @__safe_memo_cache__: Hash[memo_key, memo_record]?
 
     def memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> bool
+    def memo_ttl_remaining: (Symbol | String method_name, *untyped args, **untyped kwargs) -> (Float | Integer | nil)
     def memo_count: (*untyped method_name) -> Integer
     def memo_keys: (*untyped method_name) -> Array[untyped]
     def memo_values: (*untyped method_name) -> Array[untyped]
@@ -41,7 +44,7 @@ module SafeMemoize
     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 clear_memo_hooks: (Symbol? hook_type) -> void
-    def warm_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) { () -> untyped } -> untyped
+    def warm_memo: (Symbol | String method_name, *untyped args, ?ttl: Numeric?, **untyped kwargs) { () -> untyped } -> untyped
     def dump_memo: (?Symbol | String method_name) -> Hash[memo_key, untyped]
     def load_memo: (Hash[memo_key, untyped] snapshot) -> nil
     def reset_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
@@ -59,7 +62,7 @@ module SafeMemoize
     def memo_cache_hit?: (memo_key cache_key) -> bool
     def memo_cache_record: (memo_key cache_key) -> memo_record?
     def memo_cache_read: (memo_key cache_key) -> untyped?
-    def memo_fetch_or_store: (memo_key cache_key) { () -> untyped } -> untyped
+    def memo_fetch_or_store: (memo_key cache_key, ?ttl: Float?) { () -> untyped } -> untyped
     def memo_mutex!: () -> Mutex
     def with_memo_cache: { (Hash[memo_key, memo_record] cache) -> untyped } -> untyped?
   end
@@ -105,8 +108,8 @@ module SafeMemoize
     private
 
     def memo_metrics_store: () -> Hash[memo_key, { hits: Integer, misses: Integer, total_time: Float }]
-    def record_cache_hit: (Symbol method_name, Array[untyped] args) -> void
-    def record_cache_miss: (Symbol method_name, Array[untyped] args, Float computation_time) -> void
+    def record_cache_hit: (Symbol method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> void
+    def record_cache_miss: (Symbol method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs, Float computation_time) -> void
     def _reset_cache_metrics: () -> void
   end
 
@@ -116,6 +119,11 @@ module SafeMemoize
     def cache_hit_rate: () -> Float
     def cache_miss_rate: () -> Float
     def cache_metrics_reset: () -> void
+
+    private
+
+    def aggregate_metrics: (Hash[memo_key, untyped] metrics, include_method: bool) -> Hash[Symbol, untyped]
+    def empty_stats: () -> Hash[Symbol, untyped]
   end
 
   module CustomKeyMethods
@@ -142,6 +150,7 @@ module SafeMemoize
     def lru_order_store: () -> Hash[Symbol, Hash[memo_key, true]]
     def lru_touch: (Symbol method_name, memo_key cache_key) -> void
     def lru_evict_if_over_limit: (Symbol method_name, Integer max_size) -> void
+    def lru_remove: (Symbol method_name, memo_key cache_key) -> void
     def lru_clear_all: () -> void
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Chuck Smith