safe_memoize 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c378e971e08b2de42905d7cb00f76b4312c7c7fd596857eb051ee311a0690aed
-  data.tar.gz: c0bae56bbdca32caa3b9fa4ff8f0707728e9571298a8dfcb377f9937fe0b8586
+  metadata.gz: 036e876f53d96a1c6ca54ae257bb631c30b0b973a0f0bed77b6fafd92f187c93
+  data.tar.gz: 2d09472476154ff424940a59666b5a891d95156d44a829025ad9929f92fed24d
 SHA512:
-  metadata.gz: 8185afdd3cf81fec90dc3dd02656f394d2d60385d6b6b015b66034c898600c8c68cd20712c5e4ad51ec0957f4bf168d01b5694b1cae036823d01ac17b9d87ffb
-  data.tar.gz: 2e37ee4fcf6b57d5deb2fa252b140cb1d1e20ff67d4ad06444ceae6e075eb7699a662010254a22d5322121febe7cc72a520947432ee16bf6077729f71fe758fb
+  metadata.gz: d0004ea27b6d21d3e32df92f782ddb0d4a768212d4344e3d4e4793d6eb44bb481b309a05a875bb166e1633f3be8c08e4580b006f512dd74723383e11516ff5c4
+  data.tar.gz: 6a81f21e5e4347a723305893cfcf3dbe8b4b71bdb0ef3767774276e7046893e5ec12471898b6ecfc87df135b0462691324fa16808369a5ad98fc6e54d6ce1a14

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [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

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/class_methods.rb

@@ -6,6 +6,9 @@ module SafeMemoize
       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)
 

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/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.6.0"
+  VERSION = "0.6.1"
 end

data/sig/safe_memoize.rbs

@@ -119,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

metadata

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