safe_memoize 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00d20095844739078f88cd287d4389b749f9953b9b6055939d733f2da139c19d
-  data.tar.gz: 5c4336dbe5e3ee1e1e2b822b92a3abd4f6d5452dedd36d99706c54eb8528ed7a
+  metadata.gz: 945c98062bb51a6f19e3f229da2f8315680f1aea9ac290d1e9d60924ff6a6b6d
+  data.tar.gz: aa74ec52245abaf6fb6835446546cb269b919e07d98088b5f15f589543c1c2f7
 SHA512:
-  metadata.gz: 5d14486d2a280e2e243e2c54184875d175447f8dc921ff9e152374e9f8327061b0b4ce6de0e9213871000c0950a8cab146db7d303a0de8242d081c30e54c53ce
-  data.tar.gz: 67be0eb15e01782f7dc6b0a35cb79c24677f8d56ebf042a9dfdd49d9ec88a44c08711af24063150688c0b1ad9047c70a6c3754fd1cc662ba54a83000c1c5247a
+  metadata.gz: a2fd80a5146bf93a91a36e4449abc4e83d3687d6dbbf91b6323150847b5909b6f69ff25ef75e1804c2217a2652ca148357eaf19dccd7cdc3c2cf60ef255a5121
+  data.tar.gz: d415cc760c97f1e8d3e50f33802279c065c6c56e7f89cc553717538824663b47ff974a9cbe57ccb064638d630892a837eb10cd7602db1a8c50618a52e040fe05

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [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,7 @@ 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
 - Block arguments bypass cache (blocks aren't comparable)
 
 ## Installation
@@ -129,6 +130,21 @@ obj.reset_memo(:search, "ruby", page: 2)       # Clears one positional/keyword c
 obj.reset_all_memos                             # Clears all memoized values
 ```
 
+### 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.
+
 ### Cache inspection
 
 ```ruby

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,60 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module ClassMethods
+    def memoize(method_name, ttl: nil)
+      method_name = method_name.to_sym
+      visibility = memoized_method_visibility(method_name)
+
+      ttl = if ttl.nil?
+        nil
+      else
+        ttl = Float(ttl)
+        raise ArgumentError, "ttl must be non-negative" if ttl < 0
+
+        ttl
+      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)
+
+          # Fast path: check without lock
+          if (record = memo_cache_record(cache_key))
+            record_cache_hit(method_name, args)
+            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
+
+        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: []}
+    end
+
+    def register_memo_hook(hook_type, &block)
+      raise ArgumentError, "block required" unless block
+
+      valid_hooks = [:on_expire, :on_evict]
+      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: []}
+      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,15 @@
+# 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
+  end
+end

data/lib/safe_memoize/public_custom_key_methods.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module PublicCustomKeyMethods
+    def memoize_with_custom_key(method_name, &key_generator)
+      raise ArgumentError, "block required for key generation" unless key_generator
+
+      register_custom_key(method_name, &key_generator)
+    end
+
+    def clear_custom_keys(method_name = nil)
+      if method_name
+        with_memo_lock do
+          custom_key_store.delete(method_name.to_sym)
+        end
+      else
+        with_memo_lock do
+          _clear_custom_keys
+        end
+      end
+    end
+  end
+end

data/lib/safe_memoize/public_methods.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module PublicMethods
+    def memoized?(method_name, *args, **kwargs, &block)
+      return false if block
+
+      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+
+      with_memo_lock do
+        memo_cache_hit?(cache_key)
+      end
+    end
+
+    def memo_count(*method_name)
+      scoped_method = safe_memo_scoped_method(method_name)
+
+      with_memo_lock do
+        safe_memo_count_for(scoped_method)
+      end
+    end
+
+    def memo_keys(*method_name)
+      scoped_method = safe_memo_scoped_method(method_name)
+
+      with_memo_lock do
+        safe_memo_keys_for(scoped_method)
+      end
+    end
+
+    def memo_values(*method_name)
+      scoped_method = safe_memo_scoped_method(method_name)
+
+      with_memo_lock do
+        safe_memo_values_for(scoped_method)
+      end
+    end
+
+    def on_memo_expire(&block)
+      raise ArgumentError, "block required" unless block
+
+      register_memo_hook(:on_expire, &block)
+    end
+
+    def on_memo_evict(&block)
+      raise ArgumentError, "block required" unless block
+
+      register_memo_hook(:on_evict, &block)
+    end
+
+    def clear_memo_hooks(hook_type = nil)
+      with_memo_lock do
+        _clear_memo_hooks(hook_type)
+      end
+    end
+
+    def reset_memo(method_name, *args, **kwargs)
+      method_name = method_name.to_sym
+
+      matcher = memo_matcher_for(method_name, args, kwargs)
+
+      with_memo_lock do
+        with_memo_cache do |cache|
+          cache.delete_if do |key, record|
+            if matcher.call(key)
+              call_memo_hooks(:on_evict, key, record)
+              true
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+
+    def reset_all_memos
+      with_memo_lock do
+        if defined?(@__safe_memo_cache__) && @__safe_memo_cache__
+          @__safe_memo_cache__.each do |key, record|
+            call_memo_hooks(:on_evict, key, record)
+          end
+        end
+        @__safe_memo_cache__ = {}
+      end
+    end
+  end
+end

data/lib/safe_memoize/public_metrics_methods.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module PublicMetricsMethods
+    def cache_stats
+      with_memo_lock do
+        metrics = memo_metrics_store
+
+        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
+        }
+      end
+    end
+
+    def cache_stats_for(method_name)
+      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
+
+        {
+          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
+        }
+      end
+    end
+
+    def cache_hit_rate
+      stats = cache_stats
+      stats[:hit_rate]
+    end
+
+    def cache_miss_rate
+      stats = cache_stats
+      stats[:miss_rate]
+    end
+
+    def cache_metrics_reset
+      with_memo_lock do
+        _reset_cache_metrics
+      end
+    end
+  end
+end

data/lib/safe_memoize/version.rb

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

data/lib/safe_memoize.rb

@@ -1,206 +1,24 @@
 # frozen_string_literal: true
 
 require_relative "safe_memoize/version"
+require_relative "safe_memoize/class_methods"
+require_relative "safe_memoize/public_methods"
+require_relative "safe_memoize/cache_store_methods"
+require_relative "safe_memoize/cache_record_methods"
+require_relative "safe_memoize/inspection_methods"
+require_relative "safe_memoize/hooks_methods"
+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/instance_methods"
 
 module SafeMemoize
   class Error < StandardError; end
 
+  include InstanceMethods
+
   def self.prepended(base)
     base.extend(ClassMethods)
   end
-
-  module ClassMethods
-    def memoize(method_name)
-      method_name = method_name.to_sym
-      visibility = memoized_method_visibility(method_name)
-
-      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 = safe_memo_cache_key(method_name, args, kwargs)
-
-          # Fast path: check without lock
-          return memo_cache_read(cache_key) if memo_cache_hit?(cache_key)
-
-          memo_fetch_or_store(cache_key) { super(*args, **kwargs) }
-        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
-
-  def memoized?(method_name, *args, **kwargs, &block)
-    return false if block
-
-    cache_key = safe_memo_cache_key(method_name, args, kwargs)
-
-    with_memo_lock do
-      with_memo_cache { |cache| cache.key?(cache_key) } || false
-    end
-  end
-
-  def memo_count(*method_name)
-    scoped_method = safe_memo_scoped_method(method_name)
-
-    with_memo_lock do
-      safe_memo_count_for(scoped_method)
-    end
-  end
-
-  def memo_keys(*method_name)
-    scoped_method = safe_memo_scoped_method(method_name)
-
-    with_memo_lock do
-      safe_memo_keys_for(scoped_method)
-    end
-  end
-
-  def memo_values(*method_name)
-    scoped_method = safe_memo_scoped_method(method_name)
-
-    with_memo_lock do
-      safe_memo_values_for(scoped_method)
-    end
-  end
-
-  def reset_memo(method_name, *args, **kwargs)
-    method_name = method_name.to_sym
-
-    matcher = memo_matcher_for(method_name, args, kwargs)
-
-    with_memo_lock do
-      with_memo_cache do |cache|
-        cache.delete_if { |key, _| matcher.call(key) }
-      end
-    end
-  end
-
-  def reset_all_memos
-    with_memo_lock do
-      @__safe_memo_cache__ = {}
-    end
-  end
-
-  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 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)
-    cache = memo_cache_or_nil
-    cache&.key?(cache_key)
-  end
-
-  def memo_cache_read(cache_key)
-    cache = memo_cache_or_nil
-    cache && cache[cache_key]
-  end
-
-  def memo_fetch_or_store(cache_key)
-    memo_mutex!.synchronize do
-      @__safe_memo_cache__ ||= {}
-
-      if @__safe_memo_cache__.key?(cache_key)
-        @__safe_memo_cache__[cache_key]
-      else
-        @__safe_memo_cache__[cache_key] = yield
-      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
-
-  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
-
-    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] = value if include_value
-    payload
-  end
-
-  def safe_memo_cache_key(method_name, args, kwargs)
-    [method_name.to_sym, args, kwargs]
-  end
 end

data/sig/safe_memoize.rbs

@@ -1,47 +1,133 @@
 module SafeMemoize
   VERSION: String
+  include InstanceMethods
 
-  type memo_key = [Symbol, Array[untyped], Hash[Symbol, untyped]]
-  type memo_entry = [memo_key, untyped]
+  type default_memo_key = [Symbol, Array[untyped], Hash[Symbol, untyped]]
+  type custom_memo_key = [Symbol, untyped]
+  type memo_key = default_memo_key | custom_memo_key
+  type memo_record = { value: untyped, expires_at: Float? }
 
-  @__safe_memo_cache__: Hash[memo_key, untyped]?
+  @__safe_memo_cache__: Hash[memo_key, memo_record]?
   @__safe_memo_mutex__: Mutex?
 
   def self.prepended: (Class base) -> void
 
-  def memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
-  def memo_count: () -> Integer
-  def memo_count: (Symbol | String method_name) -> Integer
-  def memo_keys: () -> Array[untyped]
-  def memo_keys: (Symbol | String method_name) -> Array[untyped]
-  def memo_values: () -> Array[untyped]
-  def memo_values: (Symbol | String method_name) -> Array[untyped]
-  def reset_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
-  def reset_all_memos: () -> void
-
-  private
-
-  def safe_memo_scoped_method: (Array[untyped] method_name) -> Symbol?
-  def with_memo_lock: { () -> untyped } -> untyped
-  def memo_cache_or_nil: () -> Hash[memo_key, untyped]?
-  def memo_cache_hit?: (memo_key cache_key) -> bool
-  def memo_cache_read: (memo_key cache_key) -> untyped?
-  def memo_fetch_or_store: (memo_key cache_key) { () -> untyped } -> untyped
-  def memo_mutex!: () -> Mutex
-  def with_memo_cache: { (Hash[memo_key, untyped] cache) -> untyped } -> untyped?
-  def memo_matcher_for: (Symbol method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> ((memo_key) -> bool)
-  def memo_entries_for: (Symbol? method_name) -> Array[memo_entry]
-  def safe_memo_count_for: (Symbol? method_name) -> Integer
-  def safe_memo_keys_for: (Symbol? method_name) -> Array[untyped]
-  def safe_memo_values_for: (Symbol? method_name) -> Array[untyped]
-  def memo_projection: (memo_key cache_key, untyped value, include_method: bool, include_value: bool) -> Hash[Symbol, untyped]
-  def safe_memo_cache_key: (Symbol | String method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> memo_key
-
   module ClassMethods
-    def memoize: (Symbol | String method_name) -> void
+    def memoize: (Symbol | String method_name, ?ttl: Numeric?) -> void
+
+    private
+
+    def memoized_method_visibility: (Symbol method_name) -> Symbol
+  end
+
+  module PublicMethods
+    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 clear_memo_hooks: (Symbol? hook_type) -> void
+    def reset_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
+    def reset_all_memos: () -> void
+  end
+
+  module CacheStoreMethods
+    @__safe_memo_cache__: Hash[memo_key, memo_record]?
+    @__safe_memo_mutex__: Mutex?
+
+    private
+
+    def with_memo_lock: { () -> untyped } -> untyped
+    def memo_cache_or_nil: () -> Hash[memo_key, memo_record]?
+    def memo_cache_hit?: (memo_key cache_key) -> bool
+    def memo_cache_record: (memo_key cache_key) -> memo_record?
+    def memo_cache_read: (memo_key cache_key) -> untyped?
+    def memo_fetch_or_store: (memo_key cache_key) { () -> untyped } -> untyped
+    def memo_mutex!: () -> Mutex
+    def with_memo_cache: { (Hash[memo_key, memo_record] cache) -> untyped } -> untyped?
+  end
+
+  module CacheRecordMethods
+    private
+
+    def memo_ttl: (Numeric? ttl) -> Float?
+    def memo_expires_at: (Float? ttl) -> Float?
+    def memo_record: (untyped value, expires_at: Float?) -> memo_record
+    def memo_record_value: (memo_record record) -> untyped
+    def memo_record_live?: (memo_record? record) -> bool
+    def memo_prune_expired_entries!: (Hash[memo_key, memo_record] cache) -> void
+  end
+
+  module InspectionMethods
+    private
+
+    def safe_memo_scoped_method: (Array[untyped] method_name) -> Symbol?
+    def memo_matcher_for: (Symbol method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> untyped
+    def memo_entries_for: (Symbol? method_name) -> Array[untyped]
+    def safe_memo_count_for: (Symbol? method_name) -> Integer
+    def safe_memo_keys_for: (Symbol? method_name) -> Array[untyped]
+    def safe_memo_values_for: (Symbol? method_name) -> Array[untyped]
+    def memo_projection: (memo_key cache_key, memo_record value, include_method: bool, include_value: bool) -> Hash[Symbol, untyped]
+    def safe_memo_cache_key: (Symbol | String method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> default_memo_key
+  end
+
+  module HooksMethods
+    @__safe_memo_hooks__: { on_expire: Array[Proc], on_evict: Array[Proc] }?
+
+    private
+
+    def memo_hook_store: () -> { on_expire: Array[Proc], on_evict: 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
+  end
+
+  module CacheMetricsMethods
+    @__safe_memo_metrics__: Hash[memo_key, { hits: Integer, misses: Integer, total_time: Float }]?
 
     private
 
-    def memoized_method_visibility: (Symbol method_name) -> (:private | :protected | :public)
+    def memo_metrics_store: () -> Hash[memo_key, { hits: Integer, misses: Integer, total_time: Float }]
+    def record_cache_hit: (Symbol method_name, Array[untyped] args) -> void
+    def record_cache_miss: (Symbol method_name, Array[untyped] args, Float computation_time) -> void
+    def _reset_cache_metrics: () -> void
+  end
+
+  module PublicMetricsMethods
+    def cache_stats: () -> Hash[Symbol, untyped]
+    def cache_stats_for: (Symbol | String method_name) -> Hash[Symbol, untyped]
+    def cache_hit_rate: () -> Float
+    def cache_miss_rate: () -> Float
+    def cache_metrics_reset: () -> void
+  end
+
+  module CustomKeyMethods
+    @__safe_memo_custom_keys__: Hash[Symbol, Proc]?
+
+    private
+
+    def custom_key_store: () -> Hash[Symbol, Proc]
+    def register_custom_key: (Symbol | String method_name) { (*untyped args, **untyped kwargs) -> untyped } -> void
+    def compute_cache_key: (Symbol | String method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> memo_key
+    def _clear_custom_keys: () -> void
+  end
+
+  module PublicCustomKeyMethods
+    def memoize_with_custom_key: (Symbol | String method_name) { (*untyped args, **untyped kwargs) -> untyped } -> void
+    def clear_custom_keys: (Symbol | String? method_name) -> void
+  end
+
+  module InstanceMethods
+    include PublicMethods
+    include CacheStoreMethods
+    include CacheRecordMethods
+    include InspectionMethods
+    include HooksMethods
+    include CacheMetricsMethods
+    include PublicMetricsMethods
+    include CustomKeyMethods
+    include PublicCustomKeyMethods
   end
 end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -25,6 +25,17 @@ files:
 - README.md
 - Rakefile
 - lib/safe_memoize.rb
+- lib/safe_memoize/cache_metrics_methods.rb
+- lib/safe_memoize/cache_record_methods.rb
+- lib/safe_memoize/cache_store_methods.rb
+- lib/safe_memoize/class_methods.rb
+- lib/safe_memoize/custom_key_methods.rb
+- lib/safe_memoize/hooks_methods.rb
+- lib/safe_memoize/inspection_methods.rb
+- lib/safe_memoize/instance_methods.rb
+- lib/safe_memoize/public_custom_key_methods.rb
+- lib/safe_memoize/public_methods.rb
+- lib/safe_memoize/public_metrics_methods.rb
 - lib/safe_memoize/release_tooling.rb
 - lib/safe_memoize/version.rb
 - sig/safe_memoize.rbs