safe_memoize 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00d20095844739078f88cd287d4389b749f9953b9b6055939d733f2da139c19d
-  data.tar.gz: 5c4336dbe5e3ee1e1e2b822b92a3abd4f6d5452dedd36d99706c54eb8528ed7a
+  metadata.gz: 85a5a69a8dbeb570065995485ece70d230e18cbf8b39fa204f261174707d7525
+  data.tar.gz: f83e4d9b0efb5552e6bf81d2924d0098caddef6748a734c382d0bae10b27ad06
 SHA512:
-  metadata.gz: 5d14486d2a280e2e243e2c54184875d175447f8dc921ff9e152374e9f8327061b0b4ce6de0e9213871000c0950a8cab146db7d303a0de8242d081c30e54c53ce
-  data.tar.gz: 67be0eb15e01782f7dc6b0a35cb79c24677f8d56ebf042a9dfdd49d9ec88a44c08711af24063150688c0b1ad9047c70a6c3754fd1cc662ba54a83000c1c5247a
+  metadata.gz: 0a0b5d2017ddd2061ced9215747b1f38ebbaa408f5f7196e5db4c0fd9a4fb5b25c33cdd7766c001dad6596b07f93d3f6c9211bdcdccc4fc9643d1f824b849d51
+  data.tar.gz: '09df76d2d919373d9c7a31c77698378454bb996c39554296105dfd3ffc47d7e907ede4cfd6259d3e43ffbf9dda30296564f480b004e1b3676293d7a0f9fd2fd4'

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 ## [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
+- Add cache invalidation/expiration hooks for custom handlers
+  - `on_memo_expire` hook fires when TTL entries expire
+  - `on_memo_evict` hook fires when manually resetting cache entries
+  - `clear_memo_hooks` to remove registered hooks
+- Add cache statistics and monitoring capabilities
+  - `cache_stats` for comprehensive cache metrics
+  - `cache_stats_for(method_name)` for per-method statistics
+  - `cache_hit_rate` and `cache_miss_rate` for performance analysis
+  - `cache_metrics_reset` to clear collected metrics
+- Add manual cache key generation support
+  - `memoize_with_custom_key` to define custom cache key logic
+  - `clear_custom_keys` to remove custom key generators
+  - Support for complex and computed keys based on arguments
+
 ## [0.1.2] - 2026-05-13
 
 - Preserve public, protected, and private visibility for memoized methods

data/README.md

@@ -27,6 +27,12 @@ SafeMemoize uses `Hash#key?` to distinguish "not yet cached" from "cached nil/fa
 - 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
+- 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
@@ -129,6 +135,164 @@ 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
+class QuoteService
+  prepend SafeMemoize
+
+  def current_quote
+    fetch_quote_from_api
+  end
+  memoize :current_quote, ttl: 60
+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
@@ -147,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/cache_metrics_methods.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module CacheMetricsMethods
+    private
+
+    def memo_metrics_store
+      @__safe_memo_metrics__ ||= {}
+    end
+
+    def record_cache_hit(method_name, args)
+      cache_key = safe_memo_cache_key(method_name, args, {})
+      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, {})
+      metrics = memo_metrics_store
+      metrics[cache_key] ||= {hits: 0, misses: 0, total_time: 0.0}
+      metrics[cache_key][:misses] += 1
+      metrics[cache_key][:total_time] += computation_time
+    end
+
+    def _reset_cache_metrics
+      @__safe_memo_metrics__ = {}
+    end
+  end
+end

data/lib/safe_memoize/cache_record_methods.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module CacheRecordMethods
+    private
+
+    def memo_ttl(ttl)
+      return nil if ttl.nil?
+
+      ttl = Float(ttl)
+      raise ArgumentError, "ttl must be non-negative" if ttl < 0
+
+      ttl
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "ttl must be a non-negative number"
+    end
+
+    def memo_expires_at(ttl)
+      return nil unless ttl
+
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) + ttl
+    end
+
+    def memo_record(value, expires_at:)
+      {value: value, expires_at: expires_at}
+    end
+
+    def memo_record_value(record)
+      record[:value]
+    end
+
+    def memo_record_live?(record)
+      return false unless record
+
+      expires_at = record[:expires_at]
+      return true unless expires_at
+
+      expires_at > Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def memo_prune_expired_entries!(cache)
+      cache.delete_if do |cache_key, record|
+        if !memo_record_live?(record)
+          call_memo_hooks(:on_expire, cache_key, record)
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/safe_memoize/cache_store_methods.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module CacheStoreMethods
+    private
+
+    def with_memo_lock
+      if defined?(@__safe_memo_mutex__) && @__safe_memo_mutex__
+        @__safe_memo_mutex__.synchronize { yield }
+      else
+        yield
+      end
+    end
+
+    def memo_cache_or_nil
+      return nil unless defined?(@__safe_memo_cache__)
+
+      @__safe_memo_cache__
+    end
+
+    def memo_cache_hit?(cache_key)
+      !!memo_cache_record(cache_key)
+    end
+
+    def memo_cache_record(cache_key)
+      cache = memo_cache_or_nil
+      return nil unless cache
+
+      record = cache[cache_key]
+      return nil unless memo_record_live?(record)
+
+      record
+    end
+
+    def memo_cache_read(cache_key)
+      record = memo_cache_record(cache_key)
+      return nil unless record
+
+      memo_record_value(record)
+    end
+
+    def memo_fetch_or_store(cache_key, expires_at: nil)
+      memo_mutex!.synchronize do
+        @__safe_memo_cache__ ||= {}
+
+        record = @__safe_memo_cache__[cache_key]
+
+        if memo_record_live?(record)
+          memo_record_value(record)
+        else
+          value = yield
+          @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: expires_at)
+
+          value
+        end
+      end
+    end
+
+    def memo_mutex!
+      @__safe_memo_mutex__ ||= Mutex.new
+    end
+
+    def with_memo_cache
+      cache = memo_cache_or_nil
+      return nil unless cache
+
+      yield cache
+    end
+  end
+end

data/lib/safe_memoize/class_methods.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module ClassMethods
+    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
+        ttl = Float(ttl)
+        raise ArgumentError, "ttl must be non-negative" if ttl < 0
+
+        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
+        define_method(method_name) do |*args, **kwargs, &block|
+          # Blocks bypass cache entirely — they aren't comparable
+          return super(*args, **kwargs, &block) if block
+
+          cache_key = compute_cache_key(method_name, args, kwargs)
+
+          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
+
+                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)
+
+                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)
+            end
+
+            result
+          end
+        end
+
+        send(visibility, method_name)
+      end
+
+      prepend mod
+    end
+
+    private
+
+    def memoized_method_visibility(method_name)
+      return :private if private_method_defined?(method_name)
+      return :protected if protected_method_defined?(method_name)
+
+      :public
+    end
+  end
+end

data/lib/safe_memoize/custom_key_methods.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module CustomKeyMethods
+    private
+
+    def custom_key_store
+      @__safe_memo_custom_keys__ ||= {}
+    end
+
+    def register_custom_key(method_name, &block)
+      raise ArgumentError, "block required" unless block
+
+      method_name = method_name.to_sym
+      custom_key_store[method_name] = block
+    end
+
+    def compute_cache_key(method_name, args, kwargs)
+      method_name = method_name.to_sym
+
+      # Check if a custom key generator is registered
+      custom_key_block = custom_key_store[method_name]
+
+      if custom_key_block
+        # Call the custom key generator with args and kwargs
+        custom_key = custom_key_block.call(*args, **kwargs)
+        # Wrap in a standard format: [method, custom_key]
+        [method_name, custom_key]
+      else
+        # Use default key generation
+        safe_memo_cache_key(method_name, args, kwargs)
+      end
+    end
+
+    def _clear_custom_keys
+      @__safe_memo_custom_keys__ = {}
+    end
+  end
+end

data/lib/safe_memoize/hooks_methods.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module HooksMethods
+    private
+
+    def memo_hook_store
+      @__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, :on_hit]
+      raise ArgumentError, "invalid hook type: #{hook_type}" unless valid_hooks.include?(hook_type)
+
+      memo_hook_store[hook_type] << block
+    end
+
+    def call_memo_hooks(hook_type, cache_key, record)
+      hooks = memo_hook_store[hook_type] || []
+      hooks.each { |hook| hook.call(cache_key, record) }
+    end
+
+    def _clear_memo_hooks(hook_type = nil)
+      if hook_type
+        memo_hook_store[hook_type] = []
+      else
+        @__safe_memo_hooks__ = {on_expire: [], on_evict: [], on_hit: []}
+      end
+    end
+  end
+end

data/lib/safe_memoize/inspection_methods.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module InspectionMethods
+    private
+
+    def safe_memo_scoped_method(method_name)
+      raise ArgumentError, "expected 0 or 1 arguments" if method_name.length > 1
+
+      method_name.first&.to_sym
+    end
+
+    def memo_matcher_for(method_name, args, kwargs)
+      if args.empty? && kwargs.empty?
+        ->(key) { key[0] == method_name }
+      else
+        cache_key = safe_memo_cache_key(method_name, args, kwargs)
+        ->(key) { key == cache_key }
+      end
+    end
+
+    def memo_entries_for(method_name)
+      cache = memo_cache_or_nil
+      return [] unless cache
+
+      memo_prune_expired_entries!(cache)
+      entries = cache.to_a
+      return entries unless method_name
+
+      entries.select { |(cache_key, _)| cache_key[0] == method_name }
+    end
+
+    def safe_memo_count_for(method_name)
+      memo_entries_for(method_name).length
+    end
+
+    def safe_memo_keys_for(method_name)
+      entries = memo_entries_for(method_name)
+      include_method = method_name.nil?
+
+      entries.map do |(cache_key, value)|
+        memo_projection(cache_key, value, include_method: include_method, include_value: false)
+      end
+    end
+
+    def safe_memo_values_for(method_name)
+      entries = memo_entries_for(method_name)
+      include_method = method_name.nil?
+
+      entries.map do |(cache_key, value)|
+        memo_projection(cache_key, value, include_method: include_method, include_value: true)
+      end
+    end
+
+    def memo_projection(cache_key, value, include_method:, include_value:)
+      method_name, args, kwargs = cache_key
+
+      payload = {args: args, kwargs: kwargs}
+      payload[:method] = method_name if include_method
+      payload[:value] = memo_record_value(value) if include_value
+      payload
+    end
+
+    def safe_memo_cache_key(method_name, args, kwargs)
+      [method_name.to_sym, args, kwargs]
+    end
+  end
+end

data/lib/safe_memoize/instance_methods.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module InstanceMethods
+    include PublicMethods
+    include CacheStoreMethods
+    include CacheRecordMethods
+    include InspectionMethods
+    include HooksMethods
+    include CacheMetricsMethods
+    include PublicMetricsMethods
+    include CustomKeyMethods
+    include PublicCustomKeyMethods
+    include LruMethods
+  end
+end