safe_memoize 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6beffd3f5a1de6f8582c9a164502f353b8ac6c55caec6326edb4c52b0bf913ec
-  data.tar.gz: 44ebaf0f89254c692b9d33d8962577c9644df6d910818905e46395ba5e28cf89
+  metadata.gz: 12783636e7ebfd6b21453d9262eb81157d9c82de3a9a538fb8825fd173f072f6
+  data.tar.gz: fff5a502ff49712cf365b3fc67d337ad279f1b28e7ed604ee63b8dcf43e0f6bd
 SHA512:
-  metadata.gz: 0f22cd22816499ec3400a7b98cf51c3a3b77a43a0e26451ff97d6f01877d02df8772b7b3be0209e86b5c6c00d435bc96e7db8fd3a28619169e1f0e97b8ab0263
-  data.tar.gz: af315893620e46fe419a2a61ff4092f7d27f71bbfe98185ba0714162148c7d19b2d31ed9db3909d500f3e12f474f51d66ec027d81cd2d7e9948e4bc388d3a5db
+  metadata.gz: 0eedea81071d36fb8891c8767b43b07e5873aaca7d0f14bafdc339acf9c0c040b1e9b050ff72ec840d0edeccf33ef422082423576b5ae58e371dec13f50e4ed0
+  data.tar.gz: 506cadf95e962b1dccf167be9566663ee44d9d4de8ee7eed75bad4189596674b0dc6e485b9063a37f222b1136698b28f031f56d2a035f04e6d3ffa13fcc34b50

data/CHANGELOG.md

@@ -8,6 +8,23 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-05-22
+
+### Added
+
+- `SafeMemoize::Stores::Base` — abstract adapter base class defining the cache store contract: `read(key)`, `write(key, value, expires_in: nil)`, `delete(key)`, `clear`, `keys`, and `exist?(key)`; a frozen `MISS` sentinel on `Base` distinguishes cache misses from cached `nil` or `false` values; `exist?` has a default implementation that delegates to `read`
+- `SafeMemoize::Stores::Memory` — built-in in-process store that wraps a plain `Hash` behind a `Mutex`; supports per-entry TTL via `expires_in:` with lazy expiry on read; serves as both the default store and the reference implementation for custom adapters
+- `Configuration#default_store` — set via `SafeMemoize.configure { |c| c.default_store = MyStore.new }` to route every `memoize` call that has no explicit `store:` through the given adapter; methods using `max_size:` or `shared:` are incompatible and fall back silently to the per-instance hash; an invalid value raises `ArgumentError` at `memoize` time; cleared by `reset_configuration!`
+- `SafeMemoize::Stores::RailsCache` — opt-in adapter (`require "safe_memoize/stores/rails_cache"`) wrapping any `ActiveSupport::Cache::Store` (including `Rails.cache`); values are wrapped in a sentinel envelope so cached `nil`/`false` are distinguished from a cache miss; TTL forwarded as `expires_in:` for native store expiry; `clear` uses `delete_matched` scoped to the namespace; `keys` returns `[]` (AS::Cache has no enumeration API)
+- `SafeMemoize::Stores::Redis` — opt-in adapter (`require "safe_memoize/stores/redis"`) backed by any Redis-compatible client responding to `#get`, `#set`, `#del`, and `#scan_each`; values and keys are serialized with Marshal + `pack("m0")`; TTL is forwarded as `PX` (milliseconds, rounded up) for sub-second precision; `clear` uses `SCAN` to avoid blocking; all entries are namespaced (default: `"safe_memoize"`) so multiple stores or applications can share one Redis instance
+- `store:` option on `memoize` — accepts any `Stores::Base` subclass instance; routes all reads and writes through the adapter's `read`/`write` interface; the store is shared across all instances of the class; `ttl:` is forwarded as `expires_in:` to `write`, `ttl_refresh:` re-writes on every hit, and `if:`/`unless:` conditional storage is enforced at the SafeMemoize layer; raises `ArgumentError` if combined with `max_size:` (LRU belongs in the adapter) or `shared:`
+
+### Changed
+
+- Test suite achieves 100% line coverage — `spec_helper` now requires opt-in store adapters (`Stores::Redis`, `Stores::RailsCache`) after `SimpleCov.start` so Coverage tracks them; `Rakefile` runs `spec/stores/` before other specs to prevent Ruby 3.4 Coverage counter disruption from Ractor/concurrency tests; `version.rb` excluded from coverage reporting
+- `store:` type guard in `ClassMethods#memoize` collapsed to an inline guard clause so Ruby's Coverage module counts the raise correctly
+- Hook-error isolation tests (`concurrency_spec`, `hooks_spec`) now configure `on_hook_error = ->(*) {}` to silence expected stderr warnings rather than leaking them into test output; StatsD error-resilience test asserts on the emitted warning with `expect { }.to output(...).to_stderr`
+
 ## [1.0.0] - 2026-05-22
 
 ### Added

data/ROADMAP.md

@@ -4,33 +4,17 @@ This document tracks the planned evolution of SafeMemoize through v1.0.0 and bey
 
 ---
 
-## v1.0.0 — Stable API
-
-*Goal: declare a stable, semver-governed public API that downstream code can depend on with confidence.*
-
-| Feature | Description | Status |
-|---|---|---|
-| Semantic versioning guarantee | Document which constants, methods, and option keys are public API; breaking changes require a major bump henceforth | Shipped |
-| Complete RBS + Sorbet signatures | Cover all public methods including overloads for optional keyword arguments; publish `.rbi` stubs as a companion package if demand warrants | Shipped |
-| Full API reference | Generated documentation hosted on RubyDoc or a dedicated docs site; all public methods documented with parameter types, return values, and usage examples | Shipped |
-| Ractor compatibility audit | Investigate and either support Ractor-compatible operation (Mutex replacement, shared-cache storage) or document the limitation clearly | Shipped |
-| Ruby version policy | Formalise the supported Ruby version window and cadence for dropping EOL versions | Shipped |
-| Deprecation sweep | Resolve or formally deprecate any unstable internal APIs before the stable release | Shipped |
-| Upgrade guide | Document all breaking changes from 0.x and provide a migration path for users of deprecated behaviour | Shipped |
-
----
-
 ## v1.1.0 — Pluggable Cache Stores
 
 *Goal: allow the in-process hash cache to be swapped for an external store, enabling cross-process and distributed memoization.*
 
 | Feature | Description | Status |
 |---|---|---|
-| Cache store adapter interface | Define a minimal read/write/delete/clear/keys contract that external backends must implement | Planned |
-| `store:` option on `memoize` | Accept any store adapter object; defaults to the existing in-process hash store | Planned |
-| Redis adapter | Reference implementation (`SafeMemoize::Stores::Redis`) with TTL, LRU-like expiry, and serialization handled transparently | Planned |
-| Rails.cache adapter | Thin wrapper around `ActiveSupport::Cache::Store` for projects already using a configured Rails cache | Planned |
-| Global default store | Set via `SafeMemoize.configure` — applies a default store to every memoized method without per-call configuration | Planned |
+| Cache store adapter interface | Define a minimal read/write/delete/clear/keys contract that external backends must implement | Shipped |
+| `store:` option on `memoize` | Accept any store adapter object; defaults to the existing in-process hash store | Shipped |
+| Redis adapter | Reference implementation (`SafeMemoize::Stores::Redis`) with TTL, LRU-like expiry, and serialization handled transparently | Shipped |
+| Rails.cache adapter | Thin wrapper around `ActiveSupport::Cache::Store` for projects already using a configured Rails cache | Shipped |
+| Global default store | Set via `SafeMemoize.configure` — applies a default store to every memoized method without per-call configuration | Shipped |
 
 ---
 

data/Rakefile

@@ -3,7 +3,15 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec) do |t|
+  # Run store specs first: Ruby Coverage counters for opt-in adapters
+  # (redis, rails_cache) must be exercised before Ractor/concurrency tests
+  # run, which can disrupt coverage tracking in certain Ruby 3.4 builds.
+  store_specs = Dir["spec/stores/**/*_spec.rb"].sort
+  other_specs = Dir["spec/**/*_spec.rb"].sort - store_specs
+  t.rspec_opts = (store_specs + other_specs).join(" ")
+  t.pattern = "non_existent_placeholder" # overridden by rspec_opts file args
+end
 
 require "standard/rake"
 

data/lib/safe_memoize/class_methods.rb

@@ -25,6 +25,10 @@ module SafeMemoize
     # @param key [Proc, nil] class-level custom cache key generator. Receives the same
     #   arguments as the method and should return a single comparable value. Instance-level
     #   keys set via {PublicCustomKeyMethods#memoize_with_custom_key} take priority.
+    # @param store [Stores::Base, nil] custom cache store adapter. Must be a
+    #   {Stores::Base} subclass instance. The store is shared across all instances of the
+    #   class. When +nil+, the default per-instance in-process hash is used.
+    #   Cannot be combined with +max_size:+ or +shared:+.
     # @return [void]
     # @raise [ArgumentError] if the method does not exist, or option values are invalid
     #
@@ -38,7 +42,11 @@ module SafeMemoize
     #
     # @example Conditional — only cache successful responses
     #   memoize :fetch, if: ->(v) { v[:status] == 200 }
-    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil)
+    #
+    # @example With a custom store
+    #   STORE = SafeMemoize::Stores::Memory.new
+    #   memoize :fetch, store: STORE, ttl: 300
+    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil, store: nil)
       method_name = method_name.to_sym
 
       unless method_defined?(method_name) || private_method_defined?(method_name) || protected_method_defined?(method_name)
@@ -85,6 +93,26 @@ module SafeMemoize
       raise ArgumentError, ":unless must be callable" if cond_unless && !cond_unless.respond_to?(:call)
       raise ArgumentError, ":key must be callable" if key && !key.respond_to?(:call)
 
+      if store
+        raise ArgumentError, "store: must be a SafeMemoize::Stores::Base instance (got #{store.class})" unless store.is_a?(SafeMemoize::Stores::Base)
+        raise ArgumentError, "max_size: is not supported with store: — use the store adapter's own eviction" if max_size
+        raise ArgumentError, "shared: and store: cannot be combined" if shared
+      end
+
+      # Resolve effective store: explicit store: wins; global default applies when
+      # compatible (max_size: and shared: are incompatible — fall back silently).
+      effective_store = store
+      if effective_store.nil? && !max_size && !shared
+        global_default = SafeMemoize.configuration.default_store
+        if global_default
+          unless global_default.is_a?(SafeMemoize::Stores::Base)
+            raise ArgumentError,
+              "SafeMemoize.configuration.default_store must be a Stores::Base instance (got #{global_default.class})"
+          end
+          effective_store = global_default
+        end
+      end
+
       __safe_memo_class_key_generators__[method_name] = key if key
 
       # Normalize to a single "should cache?" predicate
@@ -94,6 +122,49 @@ module SafeMemoize
         ->(result) { !cond_unless.call(result) }
       end
 
+      if effective_store
+        miss = SafeMemoize::Stores::Base::MISS
+
+        mod = Module.new do
+          define_method(method_name) do |*args, **kwargs, &block|
+            return super(*args, **kwargs, &block) if block
+
+            cache_key = compute_cache_key(method_name, args, kwargs)
+            cached = effective_store.read(cache_key)
+
+            unless cached.equal?(miss)
+              effective_store.write(cache_key, cached, expires_in: ttl) if ttl_refresh
+              record_cache_hit(method_name, args, kwargs)
+              call_memo_hooks(:on_hit, cache_key, {value: cached, expires_at: nil, cached_at: nil})
+              return cached
+            end
+
+            start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            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
+
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            if !condition || condition.call(value)
+              effective_store.write(cache_key, value, expires_in: ttl)
+              call_memo_hooks(:on_store, cache_key, {value: value, expires_at: nil, cached_at: now})
+            end
+
+            record_cache_miss(method_name, args, kwargs, elapsed_time)
+            call_memo_hooks(:on_miss, cache_key, {value: value, expires_at: nil, cached_at: now})
+
+            value
+          end
+
+          send(visibility, method_name)
+        end
+
+        prepend mod
+
+        return
+      end
+
       if shared
         klass = self
         shared_mutex = klass.send(:__safe_memo_shared_mutex__)

data/lib/safe_memoize/configuration.rb

@@ -42,6 +42,12 @@ module SafeMemoize
     #   When set, {Adapters::OpenTelemetry} wraps each cache-miss computation in a span.
     attr_accessor :opentelemetry_tracer
 
+    # @return [Stores::Base, nil] Default cache store applied to every {ClassMethods#memoize}
+    #   call that does not specify its own +store:+. +nil+ uses the built-in per-instance
+    #   hash cache. Methods using +max_size:+ or +shared:+ are incompatible with an external
+    #   store and will silently continue using the per-instance hash even when this is set.
+    attr_accessor :default_store
+
     # @api private
     def initialize
       @default_ttl = nil
@@ -51,6 +57,7 @@ module SafeMemoize
       @active_support_notifications = false
       @statsd_client = nil
       @opentelemetry_tracer = nil
+      @default_store = nil
     end
   end
 end

data/lib/safe_memoize/stores/base.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Stores
+    # Abstract base class for SafeMemoize cache store adapters.
+    #
+    # Subclass this and implement all abstract methods to plug in a custom backend
+    # (Redis, Memcached, Rails.cache, etc.). The {Stores::Memory} class is the
+    # built-in reference implementation.
+    #
+    # @abstract
+    #
+    # @example Minimal inline implementation
+    #   class MyStore < SafeMemoize::Stores::Base
+    #     def initialize = (@h = {})
+    #     def read(key) = @h.fetch(key, MISS)
+    #     def write(key, value, expires_in: nil) = (@h[key] = value)
+    #     def delete(key) = @h.delete(key)
+    #     def clear = @h.clear
+    #     def keys = @h.keys
+    #   end
+    class Base
+      # Sentinel returned by {#read} to signal a cache miss.
+      #
+      # Distinct from +nil+ and +false+, which are valid cached values.
+      MISS = Object.new.freeze
+
+      # Read a value from the store.
+      #
+      # @param key [Object] cache key
+      # @return [Object] the stored value, or {MISS} if absent or expired
+      # @abstract
+      def read(key)
+        raise NotImplementedError, "#{self.class}#read must be implemented"
+      end
+
+      # Write a value to the store.
+      #
+      # @param key [Object] cache key
+      # @param value [Object] value to cache (may be +nil+ or +false+)
+      # @param expires_in [Numeric, nil] seconds until expiry; +nil+ means no expiry
+      # @return [void]
+      # @abstract
+      def write(key, value, expires_in: nil)
+        raise NotImplementedError, "#{self.class}#write must be implemented"
+      end
+
+      # Delete a single entry.
+      #
+      # @param key [Object] cache key
+      # @return [void]
+      # @abstract
+      def delete(key)
+        raise NotImplementedError, "#{self.class}#delete must be implemented"
+      end
+
+      # Remove all entries from the store.
+      #
+      # @return [void]
+      # @abstract
+      def clear
+        raise NotImplementedError, "#{self.class}#clear must be implemented"
+      end
+
+      # Return all live (non-expired) keys.
+      #
+      # @return [Array<Object>]
+      # @abstract
+      def keys
+        raise NotImplementedError, "#{self.class}#keys must be implemented"
+      end
+
+      # Check whether a live entry exists for the given key.
+      #
+      # The default delegates to {#read}; subclasses may override for stores
+      # with a native existence check.
+      #
+      # @param key [Object]
+      # @return [Boolean]
+      def exist?(key)
+        read(key) != MISS
+      end
+    end
+  end
+end

data/lib/safe_memoize/stores/memory.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Stores
+    # Default in-process cache store backed by a plain +Hash+.
+    #
+    # Thread-safe via an internal +Mutex+. Supports per-entry TTL with lazy
+    # expiry: stale entries are not proactively removed but are treated as
+    # misses on read and excluded from {#keys}.
+    class Memory < Base
+      def initialize
+        @data = {}
+        @mutex = Mutex.new
+      end
+
+      # @param key [Object]
+      # @return [Object] stored value, or {MISS} if absent or expired
+      def read(key)
+        @mutex.synchronize do
+          entry = @data[key]
+          return MISS unless entry
+          return MISS if expired?(entry)
+
+          entry[:value]
+        end
+      end
+
+      # @param key [Object]
+      # @param value [Object]
+      # @param expires_in [Numeric, nil] seconds until expiry
+      # @return [void]
+      def write(key, value, expires_in: nil)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        expires_at = expires_in ? now + expires_in.to_f : nil
+
+        @mutex.synchronize do
+          @data[key] = {value: value, expires_at: expires_at, cached_at: now}
+        end
+      end
+
+      # @param key [Object]
+      # @return [void]
+      def delete(key)
+        @mutex.synchronize { @data.delete(key) }
+      end
+
+      # Removes all entries.
+      # @return [void]
+      def clear
+        @mutex.synchronize { @data.clear }
+      end
+
+      # Returns all live (non-expired) keys.
+      # @return [Array<Object>]
+      def keys
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @mutex.synchronize do
+          @data.filter_map { |k, entry| k unless entry[:expires_at] && entry[:expires_at] <= now }
+        end
+      end
+
+      private
+
+      def expired?(entry)
+        expires_at = entry[:expires_at]
+        expires_at && expires_at <= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/safe_memoize/stores/rails_cache.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "safe_memoize"
+
+module SafeMemoize
+  module Stores
+    # Cache store adapter backed by any +ActiveSupport::Cache::Store+.
+    #
+    # Not auto-required. Add to your Rails initializer:
+    #   require "safe_memoize/stores/rails_cache"
+    #
+    # Compatible with any +ActiveSupport::Cache::Store+ implementation
+    # (+MemoryStore+, +FileStore+, +MemCacheStore+, +RedisCacheStore+, etc.)
+    # and with +Rails.cache+ directly.
+    #
+    # Because +ActiveSupport::Cache+ returns +nil+ for both a cache miss and
+    # a cached +nil+ value, this adapter wraps every value in a two-element
+    # sentinel envelope before writing. The envelope is transparent to callers.
+    #
+    # TTL is forwarded as +expires_in:+ to the cache, so the underlying store
+    # manages expiry natively — there is no lazy-expiry overhead on read.
+    #
+    # {#clear} uses +delete_matched+ scoped to the adapter's namespace, so it
+    # never clears entries belonging to other parts of the application. The
+    # backend must respond to +delete_matched+ (all standard Rails cache stores
+    # do); a +NotImplementedError+ is raised if it does not.
+    #
+    # {#keys} returns an empty array — +ActiveSupport::Cache::Store+ does not
+    # expose a standard key enumeration API. Override the method if your
+    # backend supports it.
+    #
+    # @example Basic setup
+    #   # config/initializers/safe_memoize.rb
+    #   require "safe_memoize/stores/rails_cache"
+    #
+    #   MEMO_STORE = SafeMemoize::Stores::RailsCache.new(Rails.cache)
+    #
+    #   class MyService
+    #     prepend SafeMemoize
+    #     def fetch(id) = http_get(id)
+    #     memoize :fetch, store: MEMO_STORE, ttl: 300
+    #   end
+    #
+    # @example Dedicated cache store (recommended for production)
+    #   MEMO_STORE = SafeMemoize::Stores::RailsCache.new(
+    #     ActiveSupport::Cache::RedisCacheStore.new(url: ENV["REDIS_URL"]),
+    #     namespace: "myapp:memo"
+    #   )
+    class RailsCache < Base
+      # Tag prepended to every stored value so cached +nil+/+false+ are
+      # distinguishable from a cache miss.
+      VALUE_TAG = "safe_memoize:v1"
+
+      # @param cache [ActiveSupport::Cache::Store] the cache store to use;
+      #   typically +Rails.cache+ or a dedicated store instance
+      # @param namespace [String] key prefix used to scope all entries;
+      #   defaults to +"safe_memoize"+
+      def initialize(cache, namespace: "safe_memoize")
+        @cache = cache
+        @namespace = namespace
+      end
+
+      # @param key [Object] cache key (serialized with Marshal + Base64)
+      # @return [Object] the stored value, or {MISS} if absent or unrecognised
+      def read(key)
+        raw = @cache.read(cache_key(key))
+        return MISS unless raw.is_a?(Array) && raw.length == 2 && raw[0] == VALUE_TAG
+
+        raw[1]
+      end
+
+      # @param key [Object] cache key
+      # @param value [Object] value to store (may be +nil+ or +false+)
+      # @param expires_in [Numeric, nil] TTL in seconds forwarded to the cache
+      #   as +expires_in:+; +nil+ means no expiry
+      # @return [void]
+      def write(key, value, expires_in: nil)
+        opts = expires_in ? {expires_in: expires_in} : {}
+        @cache.write(cache_key(key), [VALUE_TAG, value], **opts)
+      end
+
+      # @param key [Object]
+      # @return [void]
+      def delete(key)
+        @cache.delete(cache_key(key))
+      end
+
+      # Removes all entries written by this adapter (scoped to the namespace).
+      #
+      # Delegates to +delete_matched+ on the underlying store; raises
+      # +NotImplementedError+ if the store does not support it.
+      #
+      # @return [void]
+      # @raise [NotImplementedError] if the backing store does not respond to
+      #   +delete_matched+
+      def clear
+        unless @cache.respond_to?(:delete_matched)
+          raise NotImplementedError,
+            "#{@cache.class} does not support delete_matched — " \
+            "implement clear manually or use a store that supports it (e.g. MemoryStore, RedisCacheStore)"
+        end
+        @cache.delete_matched(/\A#{Regexp.escape(@namespace)}:/)
+      end
+
+      # Returns an empty array.
+      #
+      # +ActiveSupport::Cache::Store+ does not expose a key enumeration API.
+      # Override this method if your backend supports key listing.
+      #
+      # @return [Array]
+      def keys
+        []
+      end
+
+      # @param key [Object]
+      # @return [Boolean]
+      def exist?(key)
+        @cache.exist?(cache_key(key))
+      end
+
+      private
+
+      def cache_key(key)
+        "#{@namespace}:#{[Marshal.dump(key)].pack("m0")}"
+      end
+    end
+  end
+end

data/lib/safe_memoize/stores/redis.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "safe_memoize"
+
+module SafeMemoize
+  module Stores
+    # Cache store adapter backed by Redis.
+    #
+    # Not auto-required. Add to your application:
+    #   require "safe_memoize/stores/redis"
+    #
+    # Requires a Redis-compatible client that responds to +#get+, +#set+,
+    # +#del+, and +#scan_each+. Compatible with the +redis+ gem (v4+) and
+    # any drop-in replacement.
+    #
+    # Values and keys are serialized with +Marshal+ (Base64-encoded via
+    # +Array#pack("m0")+) so that any Ruby object, including +nil+ and
+    # +false+, can be stored and retrieved faithfully. TTL is forwarded to
+    # Redis as the +PX+ option (milliseconds, rounded up to the nearest
+    # millisecond; minimum 1 ms) to preserve sub-second precision.
+    #
+    # @example Basic setup
+    #   require "redis"
+    #   require "safe_memoize/stores/redis"
+    #
+    #   REDIS_STORE = SafeMemoize::Stores::Redis.new(::Redis.new)
+    #
+    #   class MyService
+    #     prepend SafeMemoize
+    #     def fetch(id) = http_get(id)
+    #     memoize :fetch, store: REDIS_STORE, ttl: 300
+    #   end
+    #
+    # @example With a custom namespace
+    #   STORE = SafeMemoize::Stores::Redis.new(::Redis.new, namespace: "myapp:memo")
+    class Redis < Base
+      # @param client [Object] a Redis-compatible client responding to
+      #   +#get+, +#set+, +#del+, and +#scan_each+
+      # @param namespace [String] key prefix used to scope all entries in Redis;
+      #   defaults to +"safe_memoize"+
+      def initialize(client, namespace: "safe_memoize")
+        @client = client
+        @namespace = namespace
+      end
+
+      # @param key [Object] cache key (serialized with Marshal + Base64)
+      # @return [Object] the stored value, or {MISS} if absent
+      def read(key)
+        raw = @client.get(redis_key(key))
+        return MISS if raw.nil?
+
+        Marshal.load(raw) # rubocop:disable Security/MarshalLoad
+      rescue TypeError, ArgumentError
+        MISS
+      end
+
+      # @param key [Object] cache key
+      # @param value [Object] value to store (may be +nil+ or +false+)
+      # @param expires_in [Numeric, nil] TTL in seconds forwarded to Redis as +PX+
+      #   (milliseconds, rounded up; minimum 1 ms); +nil+ means no expiry
+      # @return [void]
+      def write(key, value, expires_in: nil)
+        raw = Marshal.dump(value)
+        if expires_in
+          @client.set(redis_key(key), raw, px: [(expires_in * 1000).ceil, 1].max)
+        else
+          @client.set(redis_key(key), raw)
+        end
+      end
+
+      # @param key [Object]
+      # @return [void]
+      def delete(key)
+        @client.del(redis_key(key))
+      end
+
+      # Removes all entries written by this adapter (scoped to the namespace).
+      # Uses +SCAN+ internally to avoid blocking Redis.
+      # @return [void]
+      def clear
+        to_delete = []
+        @client.scan_each(match: "#{@namespace}:*") { |k| to_delete << k }
+        @client.del(*to_delete) unless to_delete.empty?
+      end
+
+      # Returns all live keys in the namespace, deserialized back to their
+      # original Ruby form. Entries that cannot be deserialized are silently
+      # skipped. Because Redis handles TTL natively, every key returned by
+      # +SCAN+ is live.
+      #
+      # @return [Array<Object>]
+      def keys
+        prefix = "#{@namespace}:"
+        result = []
+        @client.scan_each(match: "#{@namespace}:*") do |rk|
+          encoded = rk.delete_prefix(prefix)
+          result << Marshal.load(encoded.unpack1("m0")) # rubocop:disable Security/MarshalLoad
+        rescue ArgumentError, TypeError
+          # skip keys that cannot be deserialized (e.g. written by another serializer)
+        end
+        result
+      end
+
+      private
+
+      def redis_key(key)
+        "#{@namespace}:#{[Marshal.dump(key)].pack("m0")}"
+      end
+    end
+  end
+end

data/lib/safe_memoize/version.rb

@@ -2,5 +2,5 @@
 
 module SafeMemoize
   # The current gem version string.
-  VERSION = "1.0.0"
+  VERSION = "1.1.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/stores/base"
+require_relative "safe_memoize/stores/memory"
 require_relative "safe_memoize/adapters/statsd"
 require_relative "safe_memoize/adapters/opentelemetry"
 require_relative "safe_memoize/class_methods"

data/sig/safe_memoize.rbs

@@ -32,12 +32,13 @@ module SafeMemoize
     attr_accessor active_support_notifications: bool
     attr_accessor statsd_client: untyped
     attr_accessor opentelemetry_tracer: untyped
+    attr_accessor default_store: Stores::Base?
 
     def initialize: () -> void
   end
 
   module ClassMethods
-    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?) -> 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, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?store: Stores::Base?) -> void
     def memoize_all: (?except: Array[Symbol | String], ?only: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?) -> void
     def reset_shared_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
     def reset_all_shared_memos: () -> void
@@ -199,6 +200,32 @@ module SafeMemoize
     include LruMethods
   end
 
+  module Stores
+    class Base
+      MISS: Object
+
+      def read: (untyped key) -> untyped
+      def write: (untyped key, untyped value, ?expires_in: Numeric?) -> void
+      def delete: (untyped key) -> void
+      def clear: () -> void
+      def keys: () -> Array[untyped]
+      def exist?: (untyped key) -> bool
+    end
+
+    class Memory < Base
+      def initialize: () -> void
+      def read: (untyped key) -> untyped
+      def write: (untyped key, untyped value, ?expires_in: Numeric?) -> void
+      def delete: (untyped key) -> void
+      def clear: () -> void
+      def keys: () -> Array[untyped]
+
+      private
+
+      def expired?: ({ expires_at: Float?, value: untyped, cached_at: Float }) -> bool
+    end
+  end
+
   module Adapters
     module StatsD
       METRIC_NAMES: Hash[Symbol, String]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -71,6 +71,10 @@ files:
 - lib/safe_memoize/rails/middleware.rb
 - lib/safe_memoize/rails/request_scoped.rb
 - lib/safe_memoize/release_tooling.rb
+- lib/safe_memoize/stores/base.rb
+- lib/safe_memoize/stores/memory.rb
+- lib/safe_memoize/stores/rails_cache.rb
+- lib/safe_memoize/stores/redis.rb
 - lib/safe_memoize/version.rb
 - rbi/safe_memoize.rbi
 - sig/safe_memoize.rbs