safe_memoize 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 945c98062bb51a6f19e3f229da2f8315680f1aea9ac290d1e9d60924ff6a6b6d
-  data.tar.gz: aa74ec52245abaf6fb6835446546cb269b919e07d98088b5f15f589543c1c2f7
+  metadata.gz: eb68ddebb035ad2262b063ca010d757692802d7c4ab42a8c99beffabbcc01eb2
+  data.tar.gz: 7d154bb103d0659956959ab7e6943e6959f01738d8491e5bbe2a911ef07e43e6
 SHA512:
-  metadata.gz: a2fd80a5146bf93a91a36e4449abc4e83d3687d6dbbf91b6323150847b5909b6f69ff25ef75e1804c2217a2652ca148357eaf19dccd7cdc3c2cf60ef255a5121
-  data.tar.gz: d415cc760c97f1e8d3e50f33802279c065c6c56e7f89cc553717538824663b47ff974a9cbe57ccb064638d630892a837eb10cd7602db1a8c50618a52e040fe05
+  metadata.gz: ca92fa2b915bd9a2b921143c1ce3ee1044509456688a57fc225319ee99ab4cd01c2d5ae9036f810d2a9df518127c55c114e72987fb604458ec051967b30bd367
+  data.tar.gz: d5e6296c817536ef739b05cbc9b550c8e429450d8558bf65307188cfc2f778246f9d7318ffd39e7525278fa584b069a6143c3f6b1ed349ab4bc7d34e5ba67507

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-17
+
+- Add `warm_memo`, `dump_memo`, and `load_memo` for cache warm-up and persistence
+  - `warm_memo(:method, *args, **kwargs) { value }` — pre-populates a cache entry via block without calling the method
+  - `dump_memo` / `dump_memo(:method)` — exports live cached entries as a plain `{[method, args, kwargs] => value}` hash
+  - `load_memo(snapshot)` — merges a snapshot into the cache; loaded entries have no TTL
+  - Expired entries are excluded from `dump_memo` output
+- Add `shared: true` option on `memoize` to store results on the class instead of per-instance
+  - 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
+  - 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:`)
+  - `except:` option to skip specific methods by name
+  - Only affects public methods defined directly on the class
+- Add `on_memo_miss` hook that fires on every cache miss, completing the full lifecycle hook set alongside `on_memo_hit`, `on_memo_evict`, and `on_memo_expire`
+
+## [0.3.0] - 2026-05-15
+
+- Add `on_memo_hit` hook that fires on every cache hit, completing the lifecycle API alongside `on_memo_expire` and `on_memo_evict`
+- Add conditional memoization via `if:` and `unless:` options on `memoize`
+  - `if: ->(result) { ... }` — only caches when the lambda returns truthy
+  - `unless: ->(result) { ... }` — skips caching when the lambda returns truthy
+  - Uncached calls recompute on every invocation until the condition is met
+  - Compatible with `ttl:`, `max_size:`, hooks, and all inspection APIs
+- Add LRU cache size limit via `max_size:` option on `memoize`
+  - Evicts the least-recently-used entry per method when the limit is reached
+  - Cache hits promote entries to most-recently-used, preventing premature eviction
+  - Fires the existing `on_evict` hook for LRU-evicted entries
+  - Self-healing: stale LRU references left by `reset_memo` are pruned automatically
+  - Compatible with `ttl:` option and all existing inspection/reset APIs
+  - Thread-safe under concurrent access
+
 ## [0.2.0] - 2026-05-14
 
 - Add optional TTL expiration support for memoized entries

data/README.md

@@ -2,6 +2,10 @@
 
 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.
+
 ## The Problem
 
 Ruby's common memoization pattern breaks with falsy values:
@@ -16,19 +20,25 @@ SafeMemoize uses `Hash#key?` to distinguish "not yet cached" from "cached nil/fa
 
 ## Features
 
-- Correctly memoizes `nil` and `false` return values
-- Caches per unique arguments (positional and keyword)
-- Thread-safe via double-check locking
-- Zero runtime dependencies
-- Simple `prepend` + `memoize` API
-- Preserves public, protected, and private method visibility
-- Supports targeted cache invalidation by argument combination
-- Includes a `memoized?` helper for cache inspection
-- Includes a `memo_count` helper for cache size stats
-- Includes a `memo_keys` helper for inspecting cached signatures
-- Includes a `memo_values` helper for inspecting cached signatures and values
-- Optional TTL expiration support for cached entries
-- Block arguments bypass cache (blocks aren't comparable)
+- [Correctly memoizes `nil` and `false` return values](#nil-and-false-safety)
+- [Caches per unique arguments (positional and keyword)](#with-arguments)
+- [Thread-safe via double-check locking](#how-it-works)
+- [Simple `prepend` + `memoize` API](#usage)
+- [Preserves public, protected, and private method visibility](#works-with-private-methods)
+- [Supports targeted cache invalidation by argument combination](#cache-reset)
+- [Includes a `memoized?` helper for cache inspection](#cache-inspection)
+- [Includes a `memo_count` helper for cache size stats](#cache-inspection)
+- [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)
+- [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)
+- [Custom cache key generation per method](#custom-cache-keys)
 
 ## Installation
 
@@ -130,6 +140,54 @@ obj.reset_memo(:search, "ruby", page: 2)       # Clears one positional/keyword c
 obj.reset_all_memos                             # Clears all memoized values
 ```
 
+### Lifecycle hooks
+
+Register callbacks that fire when cached entries are evicted or expire.
+
+**`on_memo_evict`** fires when an entry is removed via `reset_memo`, `reset_all_memos`, or LRU eviction:
+
+```ruby
+obj.on_memo_evict do |cache_key, record|
+  Rails.logger.info("Evicted #{cache_key[0]}(#{cache_key[1].join(", ")}), was: #{record[:value].inspect}")
+end
+```
+
+**`on_memo_miss`** fires on every cache miss (i.e. the first call or after invalidation):
+
+```ruby
+obj.on_memo_miss do |cache_key, record|
+  Rails.logger.debug("Cache miss: #{cache_key[0]}(#{cache_key[1].join(", ")})")
+end
+```
+
+**`on_memo_hit`** fires on every cache hit:
+
+```ruby
+obj.on_memo_hit do |cache_key, record|
+  StatsD.increment("cache.hit", tags: ["method:#{cache_key[0]}"])
+end
+```
+
+**`on_memo_expire`** fires when a TTL entry is detected as expired (on the next call or during inspection):
+
+```ruby
+obj.on_memo_expire do |cache_key, record|
+  Rails.logger.debug("TTL expired: #{cache_key[0]}")
+end
+```
+
+Multiple hooks of the same type can be registered and all will fire. Remove them with `clear_memo_hooks`:
+
+```ruby
+obj.clear_memo_hooks(:on_miss)    # Clears miss hooks only
+obj.clear_memo_hooks(:on_hit)     # Clears hit hooks only
+obj.clear_memo_hooks(:on_evict)   # Clears evict hooks only
+obj.clear_memo_hooks(:on_expire)  # Clears expire hooks only
+obj.clear_memo_hooks              # Clears all hooks
+```
+
+Hooks are per-instance and do not affect other objects of the same class.
+
 ### TTL expiration
 
 ```ruby
@@ -145,6 +203,234 @@ end
 
 With a TTL, cached values expire automatically after the given number of seconds. The next call recomputes and refreshes the cache.
 
+### 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:
+
+```ruby
+class ProductService
+  prepend SafeMemoize
+
+  def find(id)
+    Product.find(id)
+  end
+  memoize :find, max_size: 100
+end
+```
+
+Cache hits count as recent access, so a frequently-read entry will never be the one evicted:
+
+```ruby
+svc = ProductService.new
+svc.find(1)   # miss — cached
+svc.find(2)   # miss — cached
+svc.find(1)   # hit  — promotes 1 to most-recently-used; 2 is now LRU
+svc.find(3)   # miss — evicts 2 (LRU), caches 3
+```
+
+`max_size:` combines with `ttl:` — LRU eviction applies within the TTL window, and entries also expire normally when the TTL elapses:
+
+```ruby
+memoize :find, max_size: 50, ttl: 300
+```
+
+The `on_evict` hook fires for LRU-evicted entries the same way it does for manual `reset_memo` calls.
+
+### Conditional caching
+
+Use `if:` to cache a result only when the predicate returns truthy, or `unless:` to skip caching when it returns truthy. Calls that don't satisfy the condition recompute every time until they do.
+
+```ruby
+class UserService
+  prepend SafeMemoize
+
+  # Don't cache nil — retries on every call until a user is found
+  def find(id)
+    User.find_by(id: id)
+  end
+  memoize :find, if: ->(result) { !result.nil? }
+end
+```
+
+```ruby
+class DataService
+  prepend SafeMemoize
+
+  # Don't cache error responses
+  def fetch(key)
+    api_client.get(key)
+  end
+  memoize :fetch, unless: ->(result) { result.is_a?(ErrorResponse) }
+end
+```
+
+Both options accept any callable and compose with `ttl:` and `max_size:`:
+
+```ruby
+memoize :find, if: ->(result) { !result.nil? }, ttl: 60, max_size: 500
+```
+
+### Cache warm-up and persistence
+
+#### Warming individual entries
+
+Use `warm_memo` to pre-populate a cache entry without calling the method. The block provides the value:
+
+```ruby
+obj.warm_memo(:current_user) { User.find(session[:user_id]) }
+obj.warm_memo(:find, 42) { cached_user }
+obj.warm_memo(:search, "ruby", page: 2) { cached_results }
+```
+
+Useful for seeding the cache from a persistent store on startup, or overriding a cached value in tests.
+
+#### Exporting and restoring the cache
+
+`dump_memo` exports all live cached entries as a plain hash keyed by `[method, args, kwargs]`:
+
+```ruby
+snapshot = obj.dump_memo              # All methods
+snapshot = obj.dump_memo(:find)       # One method only
+# => { [:find, [1], {}] => <User>, [:find, [2], {}] => <User>, ... }
+```
+
+`load_memo` restores entries from a snapshot — merging into the existing cache without evicting unrelated entries:
+
+```ruby
+obj.load_memo(snapshot)
+```
+
+Together they enable cross-request or cross-process cache persistence:
+
+```ruby
+# On shutdown — save to Redis
+redis.set("cache:#{user_id}", Marshal.dump(obj.dump_memo))
+
+# On boot — restore from Redis
+raw = redis.get("cache:#{user_id}")
+obj.load_memo(Marshal.load(raw)) if raw
+```
+
+Loaded entries have no TTL — they persist until explicitly reset. Expired entries are excluded from `dump_memo` output, so snapshots never contain stale data.
+
+### Shared cache
+
+Pass `shared: true` to store results on the class instead of per-instance. All instances share one cache, so the method is computed only once regardless of how many objects exist.
+
+```ruby
+class ConfigService
+  prepend SafeMemoize
+
+  def database_url
+    ENV.fetch("DATABASE_URL")
+  end
+
+  def feature_flags
+    fetch_flags_from_api
+  end
+
+  memoize :database_url, shared: true
+  memoize :feature_flags, shared: true, ttl: 300
+end
+
+ConfigService.new.database_url  # computes
+ConfigService.new.database_url  # returns cached — no recomputation
+```
+
+Class-level invalidation and inspection:
+
+```ruby
+ConfigService.reset_shared_memo(:feature_flags)       # Clears all entries for one method
+ConfigService.reset_shared_memo(:find, user_id)       # Clears one argument combination
+ConfigService.reset_all_shared_memos                  # Clears all shared cached entries
+ConfigService.shared_memoized?(:database_url)         # => true
+ConfigService.shared_memoized?(:find, user_id)        # Checks one argument combination
+ConfigService.shared_memo_count                       # Total shared cached entries
+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).
+
+Hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`) fire on the calling instance as usual.
+
+### Bulk memoization
+
+Use `memoize_all` to memoize every public method defined on the class in one call:
+
+```ruby
+class ConfigService
+  prepend SafeMemoize
+
+  def database_url
+    ENV.fetch("DATABASE_URL")
+  end
+
+  def redis_url
+    ENV.fetch("REDIS_URL")
+  end
+
+  def feature_flags
+    fetch_flags_from_api
+  end
+
+  memoize_all
+end
+```
+
+All options accepted by `memoize` can be passed as shared options:
+
+```ruby
+memoize_all ttl: 60
+memoize_all max_size: 100
+memoize_all if: ->(result) { !result.nil? }
+```
+
+Use `except:` to skip specific methods:
+
+```ruby
+memoize_all except: [:version, :name]
+```
+
+Only public methods defined directly on the class are memoized — inherited, private, and protected methods are not affected.
+
+### Custom cache keys
+
+By default the cache key is derived from the method name and all arguments. Use `memoize_with_custom_key` on an instance to control exactly what makes two calls equivalent:
+
+```ruby
+class ReportService
+  prepend SafeMemoize
+
+  def generate(user_id, options)
+    build_report(user_id, options)
+  end
+  memoize :generate
+end
+
+svc = ReportService.new
+
+# Cache only by user_id — ignore the options hash entirely
+svc.memoize_with_custom_key(:generate) { |user_id, _options| user_id }
+
+svc.generate(42, {format: :pdf})  # computes and caches
+svc.generate(42, {format: :csv})  # cache hit — same user_id, options ignored
+```
+
+The block can return any comparable value — a scalar, array, or hash:
+
+```ruby
+svc.memoize_with_custom_key(:generate) do |user_id, options|
+  {user: user_id, locale: options[:locale]}
+end
+```
+
+Custom key generators are per-instance and can be cleared at any time:
+
+```ruby
+svc.clear_custom_keys(:generate)  # Remove generator for one method
+svc.clear_custom_keys             # Remove all custom key generators
+```
+
 ### Cache inspection
 
 ```ruby
@@ -163,6 +449,33 @@ obj.memo_values                           # Cached signatures and values for all
 obj.memo_values(:search)                  # Cached signatures and values for one method
 ```
 
+### Cache metrics
+
+Each instance tracks hits, misses, and computation time automatically.
+
+```ruby
+obj.cache_stats
+# => {
+#      total_hits: 42,
+#      total_misses: 8,
+#      hit_rate: 84.0,
+#      miss_rate: 16.0,
+#      average_computation_time: 0.012345,
+#      entries: [
+#        { method: :find, args: [1], hits: 10, misses: 1,
+#          hit_rate: 90.91, computation_time: 0.005 },
+#        ...
+#      ]
+#    }
+
+obj.cache_stats_for(:find)   # Stats scoped to one method
+obj.cache_hit_rate           # => 84.0  (percentage)
+obj.cache_miss_rate          # => 16.0  (percentage)
+obj.cache_metrics_reset      # Clears all collected metrics
+```
+
+Metrics are per-instance and reset independently from the cache itself — clearing metrics does not evict cached values.
+
 ## How It Works
 
 SafeMemoize uses Ruby's `prepend` mechanism. When you call `memoize :method_name`, it creates an anonymous module with a wrapper method and prepends it onto your class. The wrapper calls `super` to invoke the original method and stores the result in a per-instance hash. Thread safety is achieved with a per-instance `Mutex` using double-check locking.

data/lib/safe_memoize/class_methods.rb

@@ -2,10 +2,13 @@
 
 module SafeMemoize
   module ClassMethods
-    def memoize(method_name, ttl: nil)
+    def memoize(method_name, ttl: nil, max_size: nil, if: nil, unless: nil, shared: false)
       method_name = method_name.to_sym
       visibility = memoized_method_visibility(method_name)
 
+      cond_if = binding.local_variable_get(:if)
+      cond_unless = binding.local_variable_get(:unless)
+
       ttl = if ttl.nil?
         nil
       else
@@ -15,8 +18,78 @@ module SafeMemoize
         ttl
       end
 
+      max_size = if max_size.nil?
+        nil
+      else
+        raise ArgumentError, "max_size must be a positive integer" unless max_size.is_a?(Integer)
+        raise ArgumentError, "max_size must be positive" unless max_size > 0
+
+        max_size
+      end
+
+      raise ArgumentError, "max_size: is not supported with shared: true" if shared && max_size
+
+      if cond_if && cond_unless
+        raise ArgumentError, "cannot specify both :if and :unless"
+      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)
+
+      # Normalize to a single "should cache?" predicate
+      condition = if cond_if
+        cond_if
+      elsif cond_unless
+        ->(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__)
+
+        mod = Module.new do
+          define_method(method_name) do |*args, **kwargs, &block|
+            return super(*args, **kwargs, &block) if block
+
+            cache_key = compute_cache_key(method_name, args, kwargs)
+
+            shared_mutex.synchronize do
+              shared_cache = klass.send(:__safe_memo_shared_cache__)
+              record = shared_cache[cache_key]
+              now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              record_live = record && (record[:expires_at].nil? || record[:expires_at] > now)
+
+              if record_live
+                record_cache_hit(method_name, args)
+                call_memo_hooks(:on_hit, cache_key, record)
+                record[:value]
+              else
+                call_memo_hooks(:on_expire, cache_key, record) if record && !record_live
+
+                start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                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)
+
+                record_cache_miss(method_name, args, elapsed_time)
+                call_memo_hooks(:on_miss, cache_key, new_record)
+
+                value
+              end
+            end
+          end
+
+          send(visibility, method_name)
+        end
+
+        prepend mod
+
+        return
+      end
+
       mod = Module.new do
         define_method(method_name) do |*args, **kwargs, &block|
           # Blocks bypass cache entirely — they aren't comparable
@@ -24,22 +97,54 @@ module SafeMemoize
 
           cache_key = compute_cache_key(method_name, args, kwargs)
 
-          # Fast path: check without lock
-          if (record = memo_cache_record(cache_key))
-            record_cache_hit(method_name, args)
-            return memo_record_value(record)
-          end
+          if max_size || condition
+            # Locked path: used when LRU tracking or conditional storage 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)
+                call_memo_hooks(:on_hit, cache_key, record)
+                memo_record_value(record)
+              else
+                start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                value = super(*args, **kwargs)
+                elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-          # 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) }
-          elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+                new_record = memo_record(value, expires_at: expires_at)
+                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)
+                call_memo_hooks(:on_miss, cache_key, new_record)
 
-          with_memo_lock do
-            record_cache_miss(method_name, args, elapsed_time)
-          end
+                value
+              end
+            end
+          else
+            # Fast path: check without lock
+            if (record = memo_cache_record(cache_key))
+              record_cache_hit(method_name, args)
+              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) }
+            elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+            with_memo_lock do
+              record_cache_miss(method_name, args, elapsed_time)
+              new_record = memo_cache_record(cache_key)
+              call_memo_hooks(:on_miss, cache_key, new_record)
+            end
 
-          result
+            result
+          end
         end
 
         send(visibility, method_name)
@@ -48,8 +153,69 @@ module SafeMemoize
       prepend mod
     end
 
+    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
+
+      __safe_memo_shared_mutex__.synchronize do
+        __safe_memo_shared_cache__.delete_if { |key, _| matcher.call(key) }
+      end
+    end
+
+    def reset_all_shared_memos
+      __safe_memo_shared_mutex__.synchronize do
+        @__safe_memo_shared_cache__ = {}
+      end
+    end
+
+    def shared_memoized?(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
+
+        record[:expires_at].nil? || record[:expires_at] > Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    def shared_memo_count(method_name = nil)
+      __safe_memo_shared_mutex__.synchronize do
+        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
+      end
+    end
+
+    def memoize_all(except: [], **options)
+      excluded = Array(except).map(&:to_sym)
+      public_instance_methods(false).each do |method_name|
+        next if excluded.include?(method_name)
+
+        memoize(method_name, **options)
+      end
+    end
+
     private
 
+    def __safe_memo_shared_cache__
+      @__safe_memo_shared_cache__ ||= {}
+    end
+
+    def __safe_memo_shared_mutex__
+      @__safe_memo_shared_mutex__ ||= Mutex.new
+    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/hooks_methods.rb

@@ -5,13 +5,13 @@ module SafeMemoize
     private
 
     def memo_hook_store
-      @__safe_memo_hooks__ ||= {on_expire: [], on_evict: []}
+      @__safe_memo_hooks__ ||= {on_expire: [], on_evict: [], on_hit: [], on_miss: []}
     end
 
     def register_memo_hook(hook_type, &block)
       raise ArgumentError, "block required" unless block
 
-      valid_hooks = [:on_expire, :on_evict]
+      valid_hooks = [:on_expire, :on_evict, :on_hit, :on_miss]
       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: []}
+        @__safe_memo_hooks__ = {on_expire: [], on_evict: [], on_hit: [], on_miss: []}
       end
     end
   end

data/lib/safe_memoize/instance_methods.rb

@@ -11,5 +11,6 @@ module SafeMemoize
     include PublicMetricsMethods
     include CustomKeyMethods
     include PublicCustomKeyMethods
+    include LruMethods
   end
 end

data/lib/safe_memoize/lru_methods.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module LruMethods
+    private
+
+    # Per-method LRU order: { method_name => { cache_key => true, ... } }
+    # Ruby Hash insertion order gives LRU for free: oldest key first, newest last.
+    def lru_order_store
+      @__safe_memo_lru_order__ ||= {}
+    end
+
+    # Mark +cache_key+ as most recently used for +method_name+.
+    def lru_touch(method_name, cache_key)
+      method_store = lru_order_store[method_name] ||= {}
+      method_store.delete(cache_key)
+      method_store[cache_key] = true
+    end
+
+    # Evict the least-recently-used entry for +method_name+ when at +max_size+.
+    # Must be called while holding the mutex.
+    def lru_evict_if_over_limit(method_name, max_size)
+      method_store = lru_order_store[method_name]
+      return unless method_store && !method_store.empty?
+
+      cache = @__safe_memo_cache__
+
+      # Prune stale LRU references left behind by reset_memo calls.
+      method_store.delete_if { |key, _| !cache&.key?(key) }
+
+      return if method_store.size < max_size
+
+      lru_cache_key = method_store.keys.first
+      return unless lru_cache_key
+
+      method_store.delete(lru_cache_key)
+      record = cache&.delete(lru_cache_key)
+      call_memo_hooks(:on_evict, lru_cache_key, record) if record
+    end
+
+    # Clear all LRU tracking state. Called by reset_all_memos.
+    def lru_clear_all
+      @__safe_memo_lru_order__ = {}
+    end
+  end
+end

data/lib/safe_memoize/public_methods.rb

@@ -48,12 +48,63 @@ module SafeMemoize
       register_memo_hook(:on_evict, &block)
     end
 
+    def on_memo_hit(&block)
+      raise ArgumentError, "block required" unless block
+
+      register_memo_hook(:on_hit, &block)
+    end
+
+    def on_memo_miss(&block)
+      raise ArgumentError, "block required" unless block
+
+      register_memo_hook(:on_miss, &block)
+    end
+
     def clear_memo_hooks(hook_type = nil)
       with_memo_lock do
         _clear_memo_hooks(hook_type)
       end
     end
 
+    def warm_memo(method_name, *args, **kwargs, &block)
+      raise ArgumentError, "block required" unless block
+
+      method_name = method_name.to_sym
+      cache_key = compute_cache_key(method_name, args, kwargs)
+      value = block.call
+
+      with_memo_lock do
+        @__safe_memo_cache__ ||= {}
+        @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: nil)
+      end
+
+      value
+    end
+
+    def dump_memo(method_name = nil)
+      method_name = method_name&.to_sym
+
+      with_memo_lock do
+        cache = memo_cache_or_nil || {}
+        entries = method_name ? cache.select { |key, _| key[0] == method_name } : cache.dup
+        entries.select! { |_, record| memo_record_live?(record) }
+        entries.transform_values { |record| memo_record_value(record) }
+      end
+    end
+
+    def load_memo(snapshot)
+      raise ArgumentError, "snapshot must be a Hash" unless snapshot.is_a?(Hash)
+
+      with_memo_lock do
+        @__safe_memo_cache__ ||= {}
+        snapshot.each do |cache_key, value|
+          @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: nil)
+        end
+      end
+
+      nil
+    end
+
     def reset_memo(method_name, *args, **kwargs)
       method_name = method_name.to_sym
 
@@ -81,6 +132,7 @@ module SafeMemoize
           end
         end
         @__safe_memo_cache__ = {}
+        lru_clear_all
       end
     end
   end

data/lib/safe_memoize/version.rb

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

data/lib/safe_memoize.rb

@@ -11,6 +11,7 @@ require_relative "safe_memoize/cache_metrics_methods"
 require_relative "safe_memoize/public_metrics_methods"
 require_relative "safe_memoize/custom_key_methods"
 require_relative "safe_memoize/public_custom_key_methods"
+require_relative "safe_memoize/lru_methods"
 require_relative "safe_memoize/instance_methods"
 
 module SafeMemoize

data/sig/safe_memoize.rbs

@@ -9,25 +9,41 @@ module SafeMemoize
 
   @__safe_memo_cache__: Hash[memo_key, memo_record]?
   @__safe_memo_mutex__: Mutex?
+  @__safe_memo_shared_cache__: Hash[memo_key, memo_record]?
+  @__safe_memo_shared_mutex__: Mutex?
 
   def self.prepended: (Class base) -> void
 
   module ClassMethods
-    def memoize: (Symbol | String method_name, ?ttl: Numeric?) -> void
+    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 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
 
     private
 
+    def __safe_memo_shared_cache__: () -> Hash[memo_key, memo_record]
+    def __safe_memo_shared_mutex__: () -> Mutex
     def memoized_method_visibility: (Symbol method_name) -> Symbol
   end
 
   module PublicMethods
+    @__safe_memo_cache__: Hash[memo_key, memo_record]?
+
     def memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> bool
     def memo_count: (*untyped method_name) -> Integer
     def memo_keys: (*untyped method_name) -> Array[untyped]
     def memo_values: (*untyped method_name) -> Array[untyped]
     def on_memo_expire: { (memo_key cache_key, memo_record record) -> untyped } -> void
     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 clear_memo_hooks: (Symbol? hook_type) -> void
+    def warm_memo: (Symbol | String method_name, *untyped args, **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
     def reset_all_memos: () -> void
   end
@@ -73,11 +89,11 @@ module SafeMemoize
   end
 
   module HooksMethods
-    @__safe_memo_hooks__: { on_expire: Array[Proc], on_evict: Array[Proc] }?
+    @__safe_memo_hooks__: { on_expire: Array[Proc], on_evict: Array[Proc], on_hit: Array[Proc], on_miss: Array[Proc] }?
 
     private
 
-    def memo_hook_store: () -> { on_expire: Array[Proc], on_evict: Array[Proc] }
+    def memo_hook_store: () -> { on_expire: Array[Proc], on_evict: Array[Proc], on_hit: Array[Proc], on_miss: 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,6 +134,17 @@ module SafeMemoize
     def clear_custom_keys: (Symbol | String? method_name) -> void
   end
 
+  module LruMethods
+    @__safe_memo_lru_order__: Hash[Symbol, Hash[memo_key, true]]?
+
+    private
+
+    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_clear_all: () -> void
+  end
+
   module InstanceMethods
     include PublicMethods
     include CacheStoreMethods
@@ -128,6 +155,7 @@ module SafeMemoize
     include PublicMetricsMethods
     include CustomKeyMethods
     include PublicCustomKeyMethods
+    include LruMethods
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -9,9 +9,16 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A prepend-based memoization module for Ruby that safely caches nil and
-  false return values, supports method arguments, and provides thread safety via double-check
-  locking.
+description: 'SafeMemoize is a production-ready, zero-dependency memoization library
+  for Ruby. It uses Ruby''s prepend mechanism to wrap methods with a thread-safe cache
+  (Mutex + double-check locking) that correctly handles nil and false return values
+  — fixing the silent bug in the common ||= pattern. Results are cached per unique
+  argument combination, so parameterized methods only compute each variant once. Additional
+  features include TTL expiration, LRU cache size limiting, conditional caching via
+  if:/unless: predicates, lifecycle hooks for hit/eviction/expiration events, per-instance
+  metrics (hit rate, miss rate, computation time), targeted cache invalidation, custom
+  cache key generators, and introspection helpers. Method visibility (public, protected,
+  private) is fully preserved.'
 email:
 - eclectic-coding@users.noreply.github.com
 executables: []
@@ -33,6 +40,7 @@ files:
 - lib/safe_memoize/hooks_methods.rb
 - lib/safe_memoize/inspection_methods.rb
 - lib/safe_memoize/instance_methods.rb
+- lib/safe_memoize/lru_methods.rb
 - lib/safe_memoize/public_custom_key_methods.rb
 - lib/safe_memoize/public_methods.rb
 - lib/safe_memoize/public_metrics_methods.rb