safe_memoize 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64bc56c4cd1fc255353c579f2e740b88516bafc0bfbd9365f605b1ef8af36b6f
-  data.tar.gz: b37f9d850b6d599fda50ef47f4a3e03b21484040a9efabaabba63d9891d0be6f
+  metadata.gz: c378e971e08b2de42905d7cb00f76b4312c7c7fd596857eb051ee311a0690aed
+  data.tar.gz: c0bae56bbdca32caa3b9fa4ff8f0707728e9571298a8dfcb377f9937fe0b8586
 SHA512:
-  metadata.gz: aab068ebb5b277b6b74f79ea2226c81efe3eb620a3b54630339238c3fd536797261af12e84ed446ccd325cf5902180f3c9bd2b00c2ba591a589c829d6223ea30
-  data.tar.gz: c75b60edcc7a189d0e062eb470b64874de56a916ac8369ceb1a7992bc23e7ec1a2303550f620da0be35fc75ad2d28419faba0ddc0c089a5875203004af73272e
+  metadata.gz: 8185afdd3cf81fec90dc3dd02656f394d2d60385d6b6b015b66034c898600c8c68cd20712c5e4ad51ec0957f4bf168d01b5694b1cae036823d01ac17b9d87ffb
+  data.tar.gz: 2e37ee4fcf6b57d5deb2fa252b140cb1d1e20ff67d4ad06444ceae6e075eb7699a662010254a22d5322121febe7cc72a520947432ee16bf6077729f71fe758fb

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-17
+
+- Fix TTL clock starting at `memoize` definition time instead of first method call
+- Fix metrics key silently dropping kwargs, causing methods that differ only in kwargs to share a metrics bucket
+- Fix stale LRU references remaining after expired entries are pruned
+- Add `ttl:` option to `warm_memo` so warmed entries can be given an expiry
+- Add `max_size:` support for `shared: true` memoization (class-level LRU eviction)
+- Add `ttl_refresh: true` option on `memoize` for sliding window TTL — resets expiry on every cache hit
+- Add `include_protected:` and `include_private:` options to `memoize_all`
+- Add `memo_ttl_remaining` for TTL introspection — returns seconds until expiry, `nil` for no TTL, `0` for uncached/expired
+
 ## [0.5.0] - 2026-05-17
 
 - Drop support for Ruby 3.2 (EOL); minimum required version is now Ruby 3.3
@@ -15,7 +26,7 @@
   - All instances share one cache; the method is computed only once regardless of how many objects exist
   - Class-level invalidation: `reset_shared_memo`, `reset_all_shared_memos`
   - Class-level inspection: `shared_memoized?`, `shared_memo_count`
-  - Supports `ttl:`, `if:`, and `unless:` options
+    - Supports `ttl:`, `if:`, and `unless:` options
   - Instance hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`) fire on the calling instance
 - Add `memoize_all` to memoize every public method defined on the class in one call
   - Accepts all options supported by `memoize` (`ttl:`, `max_size:`, `if:`, `unless:`)

data/lib/safe_memoize/cache_metrics_methods.rb

@@ -8,15 +8,15 @@ module SafeMemoize
       @__safe_memo_metrics__ ||= {}
     end
 
-    def record_cache_hit(method_name, args)
-      cache_key = safe_memo_cache_key(method_name, args, {})
+    def record_cache_hit(method_name, args, kwargs)
+      cache_key = safe_memo_cache_key(method_name, args, kwargs)
       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, {})
+    def record_cache_miss(method_name, args, kwargs, computation_time)
+      cache_key = safe_memo_cache_key(method_name, args, kwargs)
       metrics = memo_metrics_store
       metrics[cache_key] ||= {hits: 0, misses: 0, total_time: 0.0}
       metrics[cache_key][:misses] += 1

data/lib/safe_memoize/cache_record_methods.rb

@@ -42,6 +42,7 @@ module SafeMemoize
       cache.delete_if do |cache_key, record|
         if !memo_record_live?(record)
           call_memo_hooks(:on_expire, cache_key, record)
+          lru_remove(cache_key[0], cache_key)
           true
         else
           false

data/lib/safe_memoize/cache_store_methods.rb

@@ -39,7 +39,7 @@ module SafeMemoize
       memo_record_value(record)
     end
 
-    def memo_fetch_or_store(cache_key, expires_at: nil)
+    def memo_fetch_or_store(cache_key, ttl: nil)
       memo_mutex!.synchronize do
         @__safe_memo_cache__ ||= {}
 
@@ -49,7 +49,7 @@ module SafeMemoize
           memo_record_value(record)
         else
           value = yield
-          @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: expires_at)
+          @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: memo_expires_at(ttl))
 
           value
         end

data/lib/safe_memoize/class_methods.rb

@@ -2,7 +2,7 @@
 
 module SafeMemoize
   module ClassMethods
-    def memoize(method_name, ttl: nil, max_size: nil, if: nil, unless: nil, shared: false)
+    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false)
       method_name = method_name.to_sym
       visibility = memoized_method_visibility(method_name)
 
@@ -12,6 +12,7 @@ module SafeMemoize
       ttl = if ttl.nil?
         nil
       else
+
         ttl = Float(ttl)
         raise ArgumentError, "ttl must be non-negative" if ttl < 0
 
@@ -27,7 +28,7 @@ module SafeMemoize
         max_size
       end
 
-      raise ArgumentError, "max_size: is not supported with shared: true" if shared && max_size
+      raise ArgumentError, "ttl_refresh: requires a ttl: to be set" if ttl_refresh && ttl.nil?
 
       if cond_if && cond_unless
         raise ArgumentError, "cannot specify both :if and :unless"
@@ -42,8 +43,6 @@ module SafeMemoize
         ->(result) { !cond_unless.call(result) }
       end
 
-      expires_at = ttl && Process.clock_gettime(Process::CLOCK_MONOTONIC) + ttl
-
       if shared
         klass = self
         shared_mutex = klass.send(:__safe_memo_shared_mutex__)
@@ -61,7 +60,13 @@ module SafeMemoize
               record_live = record && (record[:expires_at].nil? || record[:expires_at] > now)
 
               if record_live
-                record_cache_hit(method_name, args)
+                if max_size
+                  lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {}
+                  lru.delete(cache_key)
+                  lru[cache_key] = true
+                end
+                record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
+                record_cache_hit(method_name, args, kwargs)
                 call_memo_hooks(:on_hit, cache_key, record)
                 record[:value]
               else
@@ -71,10 +76,27 @@ module SafeMemoize
                 value = super(*args, **kwargs)
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-                new_record = {value: value, expires_at: expires_at}
-                shared_cache[cache_key] = new_record unless condition && !condition.call(value)
+                new_record = {value: value, expires_at: memo_expires_at(ttl)}
 
-                record_cache_miss(method_name, args, elapsed_time)
+                if !condition || condition.call(value)
+                  if max_size
+                    lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {}
+                    lru.delete_if { |key, _| !shared_cache.key?(key) }
+                    if lru.size >= max_size
+                      lru_key = lru.keys.first
+                      lru.delete(lru_key)
+                      evicted = shared_cache.delete(lru_key)
+                      call_memo_hooks(:on_evict, lru_key, evicted) if evicted
+                    end
+                  end
+                  shared_cache[cache_key] = new_record
+                  if max_size
+                    lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {}
+                    lru[cache_key] = true
+                  end
+                end
+
+                record_cache_miss(method_name, args, kwargs, elapsed_time)
                 call_memo_hooks(:on_miss, cache_key, new_record)
 
                 value
@@ -97,13 +119,14 @@ module SafeMemoize
 
           cache_key = compute_cache_key(method_name, args, kwargs)
 
-          if max_size || condition
-            # Locked path: used when LRU tracking or conditional storage is needed.
+          if max_size || condition || ttl_refresh
+            # Locked path: used when LRU tracking, conditional storage, or TTL refresh 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)
+                record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
+                record_cache_hit(method_name, args, kwargs)
                 call_memo_hooks(:on_hit, cache_key, record)
                 memo_record_value(record)
               else
@@ -111,14 +134,14 @@ module SafeMemoize
                 value = super(*args, **kwargs)
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-                new_record = memo_record(value, expires_at: expires_at)
+                new_record = memo_record(value, expires_at: memo_expires_at(ttl))
                 if !condition || condition.call(value)
                   lru_evict_if_over_limit(method_name, max_size) if max_size
                   @__safe_memo_cache__ ||= {}
                   @__safe_memo_cache__[cache_key] = new_record
                   lru_touch(method_name, cache_key) if max_size
                 end
-                record_cache_miss(method_name, args, elapsed_time)
+                record_cache_miss(method_name, args, kwargs, elapsed_time)
                 call_memo_hooks(:on_miss, cache_key, new_record)
 
                 value
@@ -127,18 +150,18 @@ module SafeMemoize
           else
             # Fast path: check without lock
             if (record = memo_cache_record(cache_key))
-              record_cache_hit(method_name, args)
+              record_cache_hit(method_name, args, kwargs)
               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) }
+            result = memo_fetch_or_store(cache_key, ttl: ttl) { 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)
+              record_cache_miss(method_name, args, kwargs, elapsed_time)
               new_record = memo_cache_record(cache_key)
               call_memo_hooks(:on_miss, cache_key, new_record)
             end
@@ -155,21 +178,23 @@ module SafeMemoize
 
     def reset_shared_memo(method_name, *args, **kwargs)
       method_name = method_name.to_sym
-      matcher = if args.empty? && kwargs.empty?
-        ->(key) { key[0] == method_name }
-      else
-        cache_key = [method_name, args, kwargs]
-        ->(key) { key == cache_key }
-      end
+      specific_key = (args.empty? && kwargs.empty?) ? nil : [method_name, args, kwargs]
 
       __safe_memo_shared_mutex__.synchronize do
-        __safe_memo_shared_cache__.delete_if { |key, _| matcher.call(key) }
+        if specific_key
+          __safe_memo_shared_cache__.delete(specific_key)
+          __safe_memo_shared_lru_order__[method_name]&.delete(specific_key)
+        else
+          __safe_memo_shared_cache__.delete_if { |key, _| key[0] == method_name }
+          __safe_memo_shared_lru_order__.delete(method_name)
+        end
       end
     end
 
     def reset_all_shared_memos
       __safe_memo_shared_mutex__.synchronize do
         @__safe_memo_shared_cache__ = {}
+        @__safe_memo_shared_lru_order__ = {}
       end
     end
 
@@ -197,9 +222,14 @@ module SafeMemoize
       end
     end
 
-    def memoize_all(except: [], **options)
+    def memoize_all(except: [], include_protected: false, include_private: false, **options)
       excluded = Array(except).map(&:to_sym)
-      public_instance_methods(false).each do |method_name|
+
+      methods = public_instance_methods(false)
+      methods |= protected_instance_methods(false) if include_protected
+      methods |= private_instance_methods(false) if include_private
+
+      methods.each do |method_name|
         next if excluded.include?(method_name)
 
         memoize(method_name, **options)
@@ -216,6 +246,10 @@ module SafeMemoize
       @__safe_memo_shared_mutex__ ||= Mutex.new
     end
 
+    def __safe_memo_shared_lru_order__
+      @__safe_memo_shared_lru_order__ ||= {}
+    end
+
     def memoized_method_visibility(method_name)
       return :private if private_method_defined?(method_name)
       return :protected if protected_method_defined?(method_name)

data/lib/safe_memoize/lru_methods.rb

@@ -38,6 +38,11 @@ module SafeMemoize
       call_memo_hooks(:on_evict, lru_cache_key, record) if record
     end
 
+    # Remove a single cache key from LRU tracking. Called when an entry expires.
+    def lru_remove(method_name, cache_key)
+      lru_order_store[method_name]&.delete(cache_key)
+    end
+
     # Clear all LRU tracking state. Called by reset_all_memos.
     def lru_clear_all
       @__safe_memo_lru_order__ = {}

data/lib/safe_memoize/public_methods.rb

@@ -12,6 +12,21 @@ module SafeMemoize
       end
     end
 
+    def memo_ttl_remaining(method_name, *args, **kwargs)
+      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+
+      with_memo_lock do
+        record = memo_cache_record(cache_key)
+        return 0 unless record
+
+        expires_at = record[:expires_at]
+        return nil unless expires_at
+
+        remaining = expires_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        (remaining > 0) ? remaining.round(6) : 0
+      end
+    end
+
     def memo_count(*method_name)
       scoped_method = safe_memo_scoped_method(method_name)
 
@@ -66,7 +81,7 @@ module SafeMemoize
       end
     end
 
-    def warm_memo(method_name, *args, **kwargs, &block)
+    def warm_memo(method_name, *args, ttl: nil, **kwargs, &block)
       raise ArgumentError, "block required" unless block
 
       method_name = method_name.to_sym
@@ -75,7 +90,7 @@ module SafeMemoize
 
       with_memo_lock do
         @__safe_memo_cache__ ||= {}
-        @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: nil)
+        @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: memo_expires_at(ttl))
       end
 
       value

data/lib/safe_memoize/version.rb

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

data/sig/safe_memoize.rbs

@@ -11,12 +11,13 @@ module SafeMemoize
   @__safe_memo_mutex__: Mutex?
   @__safe_memo_shared_cache__: Hash[memo_key, memo_record]?
   @__safe_memo_shared_mutex__: Mutex?
+  @__safe_memo_shared_lru_order__: Hash[Symbol, Hash[memo_key, true]]?
 
   def self.prepended: (Class base) -> void
 
   module ClassMethods
-    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool) -> void
-    def memoize_all: (?except: Array[Symbol | String], ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?) -> void
+    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool) -> void
+    def memoize_all: (?except: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?) -> void
     def reset_shared_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
     def reset_all_shared_memos: () -> void
     def shared_memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
@@ -26,6 +27,7 @@ module SafeMemoize
 
     def __safe_memo_shared_cache__: () -> Hash[memo_key, memo_record]
     def __safe_memo_shared_mutex__: () -> Mutex
+    def __safe_memo_shared_lru_order__: () -> Hash[Symbol, Hash[memo_key, true]]
     def memoized_method_visibility: (Symbol method_name) -> Symbol
   end
 
@@ -33,6 +35,7 @@ module SafeMemoize
     @__safe_memo_cache__: Hash[memo_key, memo_record]?
 
     def memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> bool
+    def memo_ttl_remaining: (Symbol | String method_name, *untyped args, **untyped kwargs) -> (Float | Integer | nil)
     def memo_count: (*untyped method_name) -> Integer
     def memo_keys: (*untyped method_name) -> Array[untyped]
     def memo_values: (*untyped method_name) -> Array[untyped]
@@ -41,7 +44,7 @@ module SafeMemoize
     def on_memo_hit: { (memo_key cache_key, memo_record record) -> untyped } -> void
     def on_memo_miss: { (memo_key cache_key, memo_record record) -> untyped } -> void
     def clear_memo_hooks: (Symbol? hook_type) -> void
-    def warm_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) { () -> untyped } -> untyped
+    def warm_memo: (Symbol | String method_name, *untyped args, ?ttl: Numeric?, **untyped kwargs) { () -> untyped } -> untyped
     def dump_memo: (?Symbol | String method_name) -> Hash[memo_key, untyped]
     def load_memo: (Hash[memo_key, untyped] snapshot) -> nil
     def reset_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
@@ -59,7 +62,7 @@ module SafeMemoize
     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_fetch_or_store: (memo_key cache_key, ?ttl: Float?) { () -> untyped } -> untyped
     def memo_mutex!: () -> Mutex
     def with_memo_cache: { (Hash[memo_key, memo_record] cache) -> untyped } -> untyped?
   end
@@ -105,8 +108,8 @@ module SafeMemoize
     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 record_cache_hit: (Symbol method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> void
+    def record_cache_miss: (Symbol method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs, Float computation_time) -> void
     def _reset_cache_metrics: () -> void
   end
 
@@ -142,6 +145,7 @@ module SafeMemoize
     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_remove: (Symbol method_name, memo_key cache_key) -> void
     def lru_clear_all: () -> void
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Chuck Smith