safe_memoize 0.1.2 → 0.3.0

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_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,94 @@
+# 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 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)
+      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__ = {}
+        lru_clear_all
+      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.3.0"
 end

data/lib/safe_memoize.rb

@@ -1,206 +1,25 @@
 # 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/lru_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,146 @@
 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?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?) -> 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 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
+  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 memoized_method_visibility: (Symbol method_name) -> (:private | :protected | :public)
+    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], on_hit: Array[Proc] }?
+
+    private
+
+    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
+  end
+
+  module CacheMetricsMethods
+    @__safe_memo_metrics__: Hash[memo_key, { hits: Integer, misses: Integer, total_time: Float }]?
+
+    private
+
+    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 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
+    include CacheRecordMethods
+    include InspectionMethods
+    include HooksMethods
+    include CacheMetricsMethods
+    include PublicMetricsMethods
+    include CustomKeyMethods
+    include PublicCustomKeyMethods
+    include LruMethods
   end
 end
+