safe_memoize 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 945c98062bb51a6f19e3f229da2f8315680f1aea9ac290d1e9d60924ff6a6b6d
-  data.tar.gz: aa74ec52245abaf6fb6835446546cb269b919e07d98088b5f15f589543c1c2f7
+  metadata.gz: 85a5a69a8dbeb570065995485ece70d230e18cbf8b39fa204f261174707d7525
+  data.tar.gz: f83e4d9b0efb5552e6bf81d2924d0098caddef6748a734c382d0bae10b27ad06
 SHA512:
-  metadata.gz: a2fd80a5146bf93a91a36e4449abc4e83d3687d6dbbf91b6323150847b5909b6f69ff25ef75e1804c2217a2652ca148357eaf19dccd7cdc3c2cf60ef255a5121
-  data.tar.gz: d415cc760c97f1e8d3e50f33802279c065c6c56e7f89cc553717538824663b47ff974a9cbe57ccb064638d630892a837eb10cd7602db1a8c50618a52e040fe05
+  metadata.gz: 0a0b5d2017ddd2061ced9215747b1f38ebbaa408f5f7196e5db4c0fd9a4fb5b25c33cdd7766c001dad6596b07f93d3f6c9211bdcdccc4fc9643d1f824b849d51
+  data.tar.gz: '09df76d2d919373d9c7a31c77698378454bb996c39554296105dfd3ffc47d7e907ede4cfd6259d3e43ffbf9dda30296564f480b004e1b3676293d7a0f9fd2fd4'

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [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

@@ -28,6 +28,11 @@ SafeMemoize uses `Hash#key?` to distinguish "not yet cached" from "cached nil/fa
 - 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
+- Optional LRU cache size limit per method via `max_size:`
+- Conditional caching via `if:` and `unless:` predicates
+- Lifecycle hooks for hit, eviction, and expiration events
+- Per-instance cache metrics (hit rate, miss rate, computation time)
+- Custom cache key generation per method
 - Block arguments bypass cache (blocks aren't comparable)
 
 ## Installation
@@ -130,6 +135,44 @@ 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_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_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 +188,111 @@ 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
+```
+
+### 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 +311,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)
       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,6 +18,28 @@ 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
+
+      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
 
       mod = Module.new do
@@ -24,22 +49,50 @@ 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
+                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] = memo_record(value, expires_at: expires_at)
+                  lru_touch(method_name, cache_key) if max_size
+                end
+                record_cache_miss(method_name, args, elapsed_time)
 
-          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
 
-          result
+            # 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)
+            end
+
+            result
+          end
         end
 
         send(visibility, 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: []}
     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]
       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: []}
       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,6 +48,12 @@ 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 clear_memo_hooks(hook_type = nil)
       with_memo_lock do
         _clear_memo_hooks(hook_type)
@@ -81,6 +87,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.3.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

@@ -13,7 +13,7 @@ module SafeMemoize
   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)?) -> void
 
     private
 
@@ -27,6 +27,7 @@ module SafeMemoize
     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 clear_memo_hooks: (Symbol? hook_type) -> void
     def reset_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
     def reset_all_memos: () -> void
@@ -73,11 +74,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] }?
 
     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] }
     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 +119,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 +140,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.3.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -33,6 +33,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