safe_memoize 0.7.0 → 0.9.0

data/benchmarks/README.md

@@ -0,0 +1,68 @@
+# SafeMemoize Benchmarks
+
+Measures throughput for cache hits, cache misses, argument-keyed lookups, and concurrent access. Optional comparison against `memery` and `memo_wise`.
+
+## Running
+
+```bash
+bundle exec ruby benchmarks/benchmark.rb
+```
+
+### With comparison gems
+
+```bash
+gem install memery memo_wise
+bundle exec ruby benchmarks/benchmark.rb
+```
+
+## Sections
+
+| # | Scenario | What it measures |
+|---|---|---|
+| 1 | Zero-arg cache hit | Steady-state throughput on a primed cache |
+| 2 | Zero-arg cache miss | First-call overhead (new instance per iteration) |
+| 3 | With-argument cache hit | Key construction + hash lookup with one positional arg |
+| 4 | Fast path vs locked path | Cost of `max_size:` (adds a Mutex for LRU promotion) |
+| 5 | Shared vs instance cache | Class-level vs per-instance cache throughput |
+| 6 | Concurrent cache hits | 8 threads × 50 000 iterations under contention |
+
+## Interpreting results
+
+**Cache hits are ~50–70× slower than raw `||=`** on a single thread — an expected trade-off. SafeMemoize does significantly more work per call: prepended-module dispatch, deep-frozen key construction, hook dispatch, and metrics tracking. The `||=` pattern is also incorrect for `nil`/`false` return values, which is the whole reason this gem exists.
+
+**The fast path vs locked path gap is ~1.3×.** The locked path (used when `max_size:`, `if:`, or `ttl_refresh:` is set) holds the Mutex for the full read-compute-write cycle; the fast path only acquires it for the write step.
+
+**Shared and instance caches are effectively identical in throughput.** Both paths go through the same Mutex; the class-level cache has one shared Mutex rather than one per instance.
+
+**Concurrent throughput is bounded by the Mutex.** Under 8-thread contention, all threads compete for the per-instance Mutex on every read, serialising access. This is the cost of correctness under concurrent writes; in read-heavy workloads where the cache is pre-warmed the contention is minimal.
+
+## Representative results (Apple M-series, Ruby 3.4, MRI)
+
+```
+1. Zero-arg cache HIT (primed cache)
+   raw safe ivar    ~22 M i/s
+   safe_memoize     ~335 K i/s  (65× slower than raw)
+
+2. Zero-arg cache MISS (new instance each iteration)
+   raw safe ivar    ~8 M i/s
+   safe_memoize     ~227 K i/s  (36× slower than raw)
+
+3. With-argument cache HIT
+   raw safe ivar    ~15 M i/s
+   safe_memoize     ~314 K i/s  (47× slower than raw)
+
+4. Fast path vs locked path
+   fast path        ~310 K i/s
+   max_size: 100    ~234 K i/s  (1.32× slower)
+
+5. Shared vs instance cache
+   instance cache   ~323 K i/s
+   shared cache     ~324 K i/s  (same-ish)
+
+6. Concurrent (8 threads × 50 000 iterations)
+   raw safe ivar         ~12 M i/s
+   safe_memoize (fast)  ~327 K i/s
+   safe_memoize (shared) ~323 K i/s
+```
+
+Results vary by hardware, Ruby version, and GVL scheduling. Run on your own hardware for authoritative numbers.

data/benchmarks/benchmark.rb

@@ -0,0 +1,225 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: bundle exec ruby benchmarks/benchmark.rb
+#
+# Optional comparison gems (install separately if desired):
+#   gem install memery memo_wise
+#
+# Each section prints iterations/second and a comparison table.
+# Higher i/s is better.
+
+require "benchmark/ips"
+require_relative "../lib/safe_memoize"
+
+# ── Optional comparison gems ──────────────────────────────────────────────────
+
+HAS_MEMERY = begin
+  require "memery"
+  true
+rescue LoadError
+  warn "  [skip] memery not installed (gem install memery to include)"
+  false
+end
+
+HAS_MEMO_WISE = begin
+  require "memo_wise"
+  true
+rescue LoadError
+  warn "  [skip] memo_wise not installed (gem install memo_wise to include)"
+  false
+end
+
+# ── Subject classes ───────────────────────────────────────────────────────────
+
+# Raw patterns — no gem, for baseline reference
+class RawIvarUnsafe
+  # Classic ||= — fast but silently broken for nil/false return values
+  def compute = (@compute ||= 42)
+end
+
+class RawIvarSafe
+  # Safe raw pattern — correct but verbose
+  def compute
+    return @compute if defined?(@compute)
+    @compute = 42
+  end
+
+  def fetch(n)
+    @fetch ||= {}
+    return @fetch[n] if @fetch.key?(n)
+    @fetch[n] = n * 2
+  end
+end
+
+# SafeMemoize
+class SmZeroArg
+  prepend SafeMemoize
+  def compute = 42
+  memoize :compute
+end
+
+class SmWithArg
+  prepend SafeMemoize
+  def fetch(n) = n * 2
+  memoize :fetch
+end
+
+class SmLruPath
+  prepend SafeMemoize
+  def fetch(n) = n * 2
+  memoize :fetch, max_size: 100
+end
+
+class SmShared
+  prepend SafeMemoize
+  def compute = 42
+  memoize :compute, shared: true
+end
+
+# memery
+if HAS_MEMERY
+  class MemeryZeroArg
+    include Memery
+    memoize def compute = 42
+  end
+
+  class MemeryWithArg
+    include Memery
+    memoize def fetch(n) = n * 2
+  end
+end
+
+# memo_wise
+if HAS_MEMO_WISE
+  class MemoWiseZeroArg
+    prepend MemoWise
+    def compute = 42
+    memo_wise :compute
+  end
+
+  class MemoWiseWithArg
+    prepend MemoWise
+    def fetch(n) = n * 2
+    memo_wise :fetch
+  end
+end
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+IPS_CONFIG = {time: 5, warmup: 2}
+
+def section(title)
+  puts
+  puts "=" * 62
+  puts "  #{title}"
+  puts "=" * 62
+end
+
+# ── 1. Zero-arg cache HIT — steady-state throughput ──────────────────────────
+
+section "1. Zero-arg cache HIT  (steady-state, primed cache)"
+
+raw_unsafe = RawIvarUnsafe.new.tap(&:compute)
+raw_safe   = RawIvarSafe.new.tap(&:compute)
+sm_zero    = SmZeroArg.new.tap(&:compute)
+mem_zero   = MemeryZeroArg.new.tap(&:compute) if HAS_MEMERY
+mw_zero    = MemoWiseZeroArg.new.tap(&:compute) if HAS_MEMO_WISE
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("raw ||= (unsafe)")  { raw_unsafe.compute }
+  x.report("raw safe ivar")     { raw_safe.compute }
+  x.report("safe_memoize")      { sm_zero.compute }
+  x.report("memery")            { mem_zero.compute } if HAS_MEMERY
+  x.report("memo_wise")         { mw_zero.compute } if HAS_MEMO_WISE
+  x.compare!
+end
+
+# ── 2. Zero-arg cache MISS — first-call overhead ──────────────────────────────
+
+section "2. Zero-arg cache MISS  (new instance each iteration)"
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("raw safe ivar")  { RawIvarSafe.new.compute }
+  x.report("safe_memoize")   { SmZeroArg.new.compute }
+  x.report("memery")         { MemeryZeroArg.new.compute } if HAS_MEMERY
+  x.report("memo_wise")      { MemoWiseZeroArg.new.compute } if HAS_MEMO_WISE
+  x.compare!
+end
+
+# ── 3. With-argument cache HIT ────────────────────────────────────────────────
+
+section "3. With-argument cache HIT  (single fixed argument)"
+
+raw_arg  = RawIvarSafe.new.tap { |o| o.fetch(1) }
+sm_arg   = SmWithArg.new.tap { |o| o.fetch(1) }
+mem_arg  = MemeryWithArg.new.tap { |o| o.fetch(1) } if HAS_MEMERY
+mw_arg   = MemoWiseWithArg.new.tap { |o| o.fetch(1) } if HAS_MEMO_WISE
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("raw safe ivar")  { raw_arg.fetch(1) }
+  x.report("safe_memoize")   { sm_arg.fetch(1) }
+  x.report("memery")         { mem_arg.fetch(1) } if HAS_MEMERY
+  x.report("memo_wise")      { mw_arg.fetch(1) } if HAS_MEMO_WISE
+  x.compare!
+end
+
+# ── 4. Fast path vs locked path ───────────────────────────────────────────────
+
+section "4. Fast path vs locked path  (max_size: adds mutex for LRU)"
+
+sm_fast = SmWithArg.new.tap { |o| o.fetch(1) }
+sm_lru  = SmLruPath.new.tap { |o| o.fetch(1) }
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("fast path (no max_size)")   { sm_fast.fetch(1) }
+  x.report("locked path (max_size:100)") { sm_lru.fetch(1) }
+  x.compare!
+end
+
+# ── 5. Shared cache vs instance cache ────────────────────────────────────────
+
+section "5. Shared cache vs instance cache  (class-level vs instance-level)"
+
+sm_inst   = SmZeroArg.new.tap(&:compute)
+sm_shared = SmShared.new.tap(&:compute)
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("instance cache")  { sm_inst.compute }
+  x.report("shared cache")    { sm_shared.compute }
+  x.compare!
+end
+
+# ── 6. Concurrent cache hits under thread contention ─────────────────────────
+
+section "6. Concurrent cache hits  (8 threads × 50_000 iterations)"
+
+THREADS   = 8
+ITERS     = 50_000
+TOTAL     = THREADS * ITERS
+
+def bench_threaded(label, obj, method, *args)
+  ts = THREADS.times.map { Thread.new { ITERS.times { obj.public_send(method, *args) } } }
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  ts.each(&:join)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+  ips = TOTAL / elapsed
+  label_str = ips >= 1_000_000 ? format("%.2fM", ips / 1_000_000.0) : format("%.1fK", ips / 1_000.0)
+  printf "  %-34s %6.3fs  (%s i/s)\n", label, elapsed, label_str
+end
+
+puts
+
+bench_threaded("raw safe ivar",         raw_safe,   :compute)
+bench_threaded("safe_memoize (fast)",   sm_inst,    :compute)
+bench_threaded("safe_memoize (shared)", sm_shared,  :compute)
+bench_threaded("memery",                mem_zero,   :compute) if HAS_MEMERY
+bench_threaded("memo_wise",             mw_zero,    :compute) if HAS_MEMO_WISE
+
+puts
+puts "Done."

data/codecov.yml

@@ -0,0 +1,17 @@
+# Configure Pull Request Bot Comments
+comment:
+  layout: "reach, diff, flags, files"
+  behavior: default
+  # Only post or update the comment if the coverage drops
+  require_changes: "coverage_drop"
+
+# Configure Commit Status Checks (the green checkmark/red X list)
+coverage:
+  status:
+    project:
+      default:
+        # Prevent "Informational" mode so a drop causes an actual red failure check
+        informational: false
+    patch:
+      default:
+        informational: false

data/lib/safe_memoize/adapters/opentelemetry.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Adapters
+    module OpenTelemetry
+      SPAN_NAME = "safe_memoize.compute"
+
+      def self.trace(tracer, method_name, class_name)
+        return yield unless tracer&.respond_to?(:in_span)
+
+        tracer.in_span(SPAN_NAME, attributes: {
+          "safe_memoize.method" => method_name.to_s,
+          "safe_memoize.class" => class_name.to_s,
+          "safe_memoize.cache_hit" => false
+        }) { yield }
+      end
+    end
+  end
+end

data/lib/safe_memoize/adapters/statsd.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Adapters
+    module StatsD
+      METRIC_NAMES = {
+        on_hit: "safe_memoize.hit",
+        on_miss: "safe_memoize.miss",
+        on_evict: "safe_memoize.evict",
+        on_expire: "safe_memoize.expire",
+        on_store: "safe_memoize.store"
+      }.freeze
+
+      def self.dispatch(client, hook_type, cache_key, class_name)
+        metric = METRIC_NAMES[hook_type]
+        return unless metric
+
+        tags = ["method:#{cache_key[0]}", "class:#{class_name}"]
+        client.increment(metric, tags: tags)
+      rescue => error
+        warn "[SafeMemoize] StatsD dispatch error: #{error.message}"
+      end
+    end
+  end
+end

data/lib/safe_memoize/class_methods.rb

@@ -4,6 +4,11 @@ module SafeMemoize
   module ClassMethods
     def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil)
       method_name = method_name.to_sym
+
+      unless method_defined?(method_name) || private_method_defined?(method_name) || protected_method_defined?(method_name)
+        raise ArgumentError, "cannot memoize :#{method_name} — no instance method with that name is defined on #{self}"
+      end
+
       visibility = memoized_method_visibility(method_name)
 
       config = SafeMemoize.configuration
@@ -83,7 +88,7 @@ module SafeMemoize
                 call_memo_hooks(:on_expire, cache_key, record) if record && !record_live
 
                 start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-                value = super(*args, **kwargs)
+                value = Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, klass.name) { super(*args, **kwargs) }
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
                 new_record = memo_record(value, expires_at: memo_expires_at(ttl))
@@ -142,7 +147,7 @@ module SafeMemoize
                 memo_record_value(record)
               else
                 start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-                value = super(*args, **kwargs)
+                value = Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name) { super(*args, **kwargs) }
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
                 new_record = memo_record(value, expires_at: memo_expires_at(ttl))
@@ -169,7 +174,9 @@ module SafeMemoize
 
             # Cache miss - compute and store
             start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            result = memo_fetch_or_store(cache_key, ttl: ttl) { super(*args, **kwargs) }
+            result = memo_fetch_or_store(cache_key, ttl: ttl) do
+              Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name) { super(*args, **kwargs) }
+            end
             elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
             with_memo_lock do
@@ -274,8 +281,11 @@ module SafeMemoize
       end
     end
 
-    def memoize_all(except: [], include_protected: false, include_private: false, **options)
+    def memoize_all(except: [], only: [], include_protected: false, include_private: false, **options)
+      raise ArgumentError, "cannot specify both :only and :except" if only.any? && except.any?
+
       excluded = Array(except).map(&:to_sym)
+      included = Array(only).map(&:to_sym)
 
       methods = public_instance_methods(false)
       methods |= protected_instance_methods(false) if include_protected
@@ -283,6 +293,7 @@ module SafeMemoize
 
       methods.each do |method_name|
         next if excluded.include?(method_name)
+        next if included.any? && !included.include?(method_name)
 
         memoize(method_name, **options)
       end

data/lib/safe_memoize/configuration.rb

@@ -2,11 +2,17 @@
 
 module SafeMemoize
   class Configuration
-    attr_accessor :default_ttl, :default_max_size
+    attr_accessor :default_ttl, :default_max_size, :on_deprecation, :on_hook_error,
+      :active_support_notifications, :statsd_client, :opentelemetry_tracer
 
     def initialize
       @default_ttl = nil
       @default_max_size = nil
+      @on_deprecation = nil
+      @on_hook_error = nil
+      @active_support_notifications = false
+      @statsd_client = nil
+      @opentelemetry_tracer = nil
     end
   end
 end

data/lib/safe_memoize/hooks_methods.rb

@@ -2,6 +2,14 @@
 
 module SafeMemoize
   module HooksMethods
+    NOTIFICATION_EVENT_NAMES = {
+      on_hit: "cache_hit.safe_memoize",
+      on_miss: "cache_miss.safe_memoize",
+      on_evict: "cache_evict.safe_memoize",
+      on_expire: "cache_expire.safe_memoize",
+      on_store: "cache_store.safe_memoize"
+    }.freeze
+
     private
 
     def memo_hook_store
@@ -19,7 +27,38 @@ module SafeMemoize
 
     def call_memo_hooks(hook_type, cache_key, record)
       hooks = memo_hook_store[hook_type] || []
-      hooks.each { |hook| hook.call(cache_key, record) }
+      hooks.each do |hook|
+        hook.call(cache_key, record)
+      rescue => error
+        handler = SafeMemoize.configuration.on_hook_error
+        if handler
+          handler.call(error, hook_type, cache_key)
+        else
+          warn "[SafeMemoize] Hook error in #{hook_type}: #{error.message}"
+        end
+      end
+
+      safe_memo_notify(hook_type, cache_key) if SafeMemoize.configuration.active_support_notifications
+
+      if (client = SafeMemoize.configuration.statsd_client)
+        Adapters::StatsD.dispatch(client, hook_type, cache_key, self.class.name)
+      end
+    end
+
+    def safe_memo_notify(hook_type, cache_key)
+      return unless defined?(ActiveSupport::Notifications)
+
+      asn = ActiveSupport::Notifications
+      return unless asn.respond_to?(:instrument)
+
+      event = NOTIFICATION_EVENT_NAMES[hook_type]
+      return unless event
+
+      asn.instrument(event, {
+        method: cache_key[0],
+        key: cache_key,
+        class: self.class.name
+      })
     end
 
     def _clear_memo_hooks(hook_type = nil)

data/lib/safe_memoize/inspection_methods.rb

@@ -69,7 +69,20 @@ module SafeMemoize
     end
 
     def safe_memo_cache_key(method_name, args, kwargs)
-      [method_name.to_sym, args, kwargs]
+      [method_name.to_sym, deep_freeze_copy(args), deep_freeze_copy(kwargs)]
+    end
+
+    def deep_freeze_copy(obj)
+      case obj
+      when Array
+        obj.map { |e| deep_freeze_copy(e) }.freeze
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[deep_freeze_copy(k)] = deep_freeze_copy(v) }.freeze
+      when String
+        -obj
+      else
+        obj
+      end
     end
   end
 end

data/lib/safe_memoize/public_methods.rb

@@ -226,5 +226,48 @@ module SafeMemoize
         lru_clear_all
       end
     end
+
+    def memo_inspect(method_name, *args, **kwargs)
+      method_name = method_name.to_sym
+      cache_key = compute_cache_key(method_name, args, kwargs)
+
+      with_memo_lock do
+        record = memo_cache_record(cache_key)
+        return nil unless record
+
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        ttl_remaining = if record[:expires_at]
+          remaining = record[:expires_at] - now
+          (remaining > 0) ? remaining.round(6) : 0
+        end
+
+        age = (now - record[:cached_at]).round(6) if record[:cached_at]
+
+        metrics_key = safe_memo_cache_key(method_name, args, kwargs)
+        entry_metrics = memo_metrics_store[metrics_key] || {hits: 0, misses: 0}
+
+        custom_key = (cache_key.length == 2) ? cache_key[1] : nil
+
+        lru_position = begin
+          method_lru = lru_order_store[method_name]
+          if method_lru&.key?(cache_key)
+            keys = method_lru.keys
+            keys.length - keys.index(cache_key)
+          end
+        end
+
+        {
+          cached: true,
+          value: memo_record_value(record),
+          hits: entry_metrics[:hits],
+          misses: entry_metrics[:misses],
+          ttl_remaining: ttl_remaining,
+          age: age,
+          custom_key: custom_key,
+          lru_position: lru_position
+        }
+      end
+    end
   end
 end

data/lib/safe_memoize/rails/middleware.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Rails
+    # Rack middleware that resets all thread-tracked memoized instances at the
+    # end of each request. Useful for service objects that are instantiated
+    # per-request and register themselves via `SafeMemoize::Rails.track(self)`.
+    #
+    # Add to your Rack stack in config/application.rb:
+    #   config.middleware.use SafeMemoize::Rails::Middleware
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env)
+      ensure
+        SafeMemoize::Rails.reset_tracked!
+      end
+    end
+  end
+end

data/lib/safe_memoize/rails/request_scoped.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Rails
+    # Include in a Rails controller to automatically reset instance memos after
+    # each request. In non-controller classes (service objects, models), include
+    # it to gain `reset_request_memos` and call it manually at the end of a
+    # request or job.
+    #
+    # The class must also `prepend SafeMemoize` for `reset_all_memos` to exist.
+    #
+    # Example — controller:
+    #   class ApplicationController < ActionController::Base
+    #     prepend SafeMemoize
+    #     include SafeMemoize::Rails::RequestScoped
+    #   end
+    #
+    # Example — service object with middleware tracking:
+    #   class ReportService
+    #     prepend SafeMemoize
+    #     include SafeMemoize::Rails::RequestScoped
+    #
+    #     def initialize
+    #       SafeMemoize::Rails.track(self)
+    #     end
+    #   end
+    module RequestScoped
+      def self.included(base)
+        base.after_action :reset_all_memos if base.respond_to?(:after_action)
+      end
+
+      def reset_request_memos
+        reset_all_memos
+      end
+    end
+  end
+end

data/lib/safe_memoize/rails.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "safe_memoize"
+require_relative "rails/request_scoped"
+require_relative "rails/middleware"
+
+module SafeMemoize
+  # Optional Rails integration. Not auto-required — add to your initializer:
+  #   require "safe_memoize/rails"
+  module Rails
+    # Register an instance to have its memos reset at the end of the current
+    # request (via Middleware). Thread-local; each thread maintains its own list.
+    def self.track(instance)
+      (Thread.current[:safe_memoize_tracked] ||= []) << instance
+    end
+
+    # Reset all tracked instances and clear the list. Called automatically by
+    # Middleware after each request. Safe to call with an empty list.
+    def self.reset_tracked!
+      instances = Thread.current[:safe_memoize_tracked] || []
+      instances.each do |instance|
+        instance.reset_all_memos if instance.respond_to?(:reset_all_memos)
+      end
+    ensure
+      Thread.current[:safe_memoize_tracked] = []
+    end
+  end
+end

data/lib/safe_memoize/version.rb

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

data/lib/safe_memoize.rb

@@ -2,6 +2,8 @@
 
 require_relative "safe_memoize/version"
 require_relative "safe_memoize/configuration"
+require_relative "safe_memoize/adapters/statsd"
+require_relative "safe_memoize/adapters/opentelemetry"
 require_relative "safe_memoize/class_methods"
 require_relative "safe_memoize/public_methods"
 require_relative "safe_memoize/cache_store_methods"
@@ -35,4 +37,10 @@ module SafeMemoize
   def self.reset_configuration!
     @configuration = Configuration.new
   end
+
+  def self.deprecate(subject, message:, horizon:)
+    text = "[SafeMemoize] #{subject} is deprecated and will be removed in #{horizon}. #{message}"
+    handler = configuration.on_deprecation
+    handler ? handler.call(text) : warn(text)
+  end
 end