safe_memoize 0.9.0 → 1.1.0

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module SafeMemoize
-  VERSION = "0.9.0"
+  # The current gem version string.
+  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"
@@ -17,27 +19,81 @@ require_relative "safe_memoize/public_custom_key_methods"
 require_relative "safe_memoize/lru_methods"
 require_relative "safe_memoize/instance_methods"
 
+# Thread-safe memoization for Ruby that correctly handles +nil+ and +false+ values.
+#
+# Prepend this module into any class, then call {ClassMethods#memoize} to wrap
+# instance methods with a per-instance cache backed by a +Mutex+.
+#
+# @example Basic usage
+#   class UserService
+#     prepend SafeMemoize
+#
+#     def current_user
+#       User.find_by(session_id: session_id)
+#     end
+#     memoize :current_user
+#   end
+#
+# @example With TTL and LRU cap
+#   class ApiClient
+#     prepend SafeMemoize
+#
+#     def fetch(id)
+#       http_get("/items/#{id}")
+#     end
+#     memoize :fetch, ttl: 60, max_size: 500
+#   end
+#
+# @see ClassMethods#memoize
+# @see https://github.com/eclectic-coding/safe_memoize README
 module SafeMemoize
+  # Base class for all SafeMemoize-specific exceptions.
+  # Rescue this to catch any error raised by the library itself.
   class Error < StandardError; end
 
   include InstanceMethods
 
+  # @api private
   def self.prepended(base)
     base.extend(ClassMethods)
   end
 
+  # Yields the global {Configuration} object for mutation.
+  #
+  # @example
+  #   SafeMemoize.configure do |c|
+  #     c.default_ttl = 300
+  #   end
+  #
+  # @yield [config] The current {Configuration} instance.
+  # @yieldparam config [Configuration]
+  # @return [void]
   def self.configure
     yield configuration
   end
 
+  # Returns the global {Configuration} instance, creating it on first access.
+  #
+  # @return [Configuration]
   def self.configuration
     @configuration ||= Configuration.new
   end
 
+  # Resets the global configuration to all defaults.
+  #
+  # Useful in test suites to prevent configuration leaking between examples.
+  #
+  # @return [Configuration] the new blank configuration
   def self.reset_configuration!
     @configuration = Configuration.new
   end
 
+  # Emits a structured deprecation warning through the configured handler.
+  #
+  # @param subject [String] short identifier of the deprecated symbol
+  # @param message [String] migration instructions
+  # @param horizon [String] version when the symbol will be removed (e.g. +"v2.0.0"+)
+  # @return [void]
   def self.deprecate(subject, message:, horizon:)
     text = "[SafeMemoize] #{subject} is deprecated and will be removed in #{horizon}. #{message}"
     handler = configuration.on_deprecation

data/rbi/safe_memoize.rbi

@@ -0,0 +1,245 @@
+# typed: true
+
+# Sorbet type stubs for the safe_memoize gem.
+#
+# These stubs cover every symbol listed in the public API guarantee
+# (see README "Public API and versioning guarantee"). Opt-in extensions
+# (SafeMemoize::Rails, SafeMemoize::Adapters::*) are included as well,
+# but they are not part of the v1.0.0 semver guarantee.
+#
+# Usage: add `require "safe_memoize"` to your Sorbet ignore list if you
+# use tapioca, or copy this file into sorbet/rbi/shims/ for manual setups.
+
+module SafeMemoize
+  VERSION = T.let(T.unsafe(nil), String)
+
+  class Error < StandardError; end
+
+  sig { params(base: T::Class[T.anything]).void }
+  def self.prepended(base); end
+
+  sig { params(blk: T.proc.params(config: SafeMemoize::Configuration).void).void }
+  def self.configure(&blk); end
+
+  sig { returns(SafeMemoize::Configuration) }
+  def self.configuration; end
+
+  sig { returns(SafeMemoize::Configuration) }
+  def self.reset_configuration!; end
+
+  sig { params(subject: String, message: String, horizon: String).void }
+  def self.deprecate(subject, message:, horizon:); end
+
+  class Configuration
+    sig { returns(T.nilable(Numeric)) }
+    attr_accessor :default_ttl
+
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :default_max_size
+
+    sig { returns(T.nilable(T.proc.params(message: String).void)) }
+    attr_accessor :on_deprecation
+
+    sig { returns(T.nilable(T.proc.params(error: Exception, hook_type: Symbol, cache_key: T.untyped).void)) }
+    attr_accessor :on_hook_error
+
+    sig { returns(T::Boolean) }
+    attr_accessor :active_support_notifications
+
+    sig { returns(T.untyped) }
+    attr_accessor :statsd_client
+
+    sig { returns(T.untyped) }
+    attr_accessor :opentelemetry_tracer
+
+    sig { void }
+    def initialize; end
+  end
+
+  module ClassMethods
+    sig do
+      params(
+        method_name: T.any(Symbol, String),
+        ttl: T.nilable(Numeric),
+        max_size: T.nilable(Integer),
+        ttl_refresh: T::Boolean,
+        if: T.nilable(T.proc.params(result: T.untyped).returns(T.untyped)),
+        unless: T.nilable(T.proc.params(result: T.untyped).returns(T.untyped)),
+        shared: T::Boolean,
+        key: T.nilable(T.proc.params(args: T.untyped).returns(T.untyped))
+      ).void
+    end
+    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil); end
+
+    sig do
+      params(
+        except: T::Array[T.any(Symbol, String)],
+        only: T::Array[T.any(Symbol, String)],
+        include_protected: T::Boolean,
+        include_private: T::Boolean,
+        ttl: T.nilable(Numeric),
+        max_size: T.nilable(Integer),
+        ttl_refresh: T::Boolean,
+        if: T.nilable(T.proc.params(result: T.untyped).returns(T.untyped)),
+        unless: T.nilable(T.proc.params(result: T.untyped).returns(T.untyped)),
+        shared: T::Boolean,
+        key: T.nilable(T.proc.params(args: T.untyped).returns(T.untyped))
+      ).void
+    end
+    def memoize_all(except: [], only: [], include_protected: false, include_private: false, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil); end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped).void }
+    def reset_shared_memo(method_name, *args, **kwargs); end
+
+    sig { void }
+    def reset_all_shared_memos; end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped).returns(T::Boolean) }
+    def shared_memoized?(method_name, *args, **kwargs); end
+
+    sig { params(method_name: T.nilable(T.any(Symbol, String))).returns(Integer) }
+    def shared_memo_count(method_name = nil); end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped).returns(T.nilable(Float)) }
+    def shared_memo_age(method_name, *args, **kwargs); end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped).returns(T::Boolean) }
+    def shared_memo_stale?(method_name, *args, **kwargs); end
+  end
+
+  module PublicMethods
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped, blk: T.nilable(T.proc.returns(T.untyped))).returns(T::Boolean) }
+    def memoized?(method_name, *args, **kwargs, &blk); end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped).returns(T.nilable(T.any(Float, Integer))) }
+    def memo_ttl_remaining(method_name, *args, **kwargs); end
+
+    sig { params(method_name: T.nilable(T.any(Symbol, String))).returns(Integer) }
+    def memo_count(method_name = nil); end
+
+    sig { params(method_name: T.nilable(T.any(Symbol, String))).returns(T::Array[T.untyped]) }
+    def memo_keys(method_name = nil); end
+
+    sig { params(method_name: T.nilable(T.any(Symbol, String))).returns(T::Array[T.untyped]) }
+    def memo_values(method_name = nil); end
+
+    sig { params(blk: T.proc.params(cache_key: T.untyped, record: T::Hash[Symbol, T.untyped]).returns(T.untyped)).void }
+    def on_memo_expire(&blk); end
+
+    sig { params(blk: T.proc.params(cache_key: T.untyped, record: T::Hash[Symbol, T.untyped]).returns(T.untyped)).void }
+    def on_memo_evict(&blk); end
+
+    sig { params(blk: T.proc.params(cache_key: T.untyped, record: T::Hash[Symbol, T.untyped]).returns(T.untyped)).void }
+    def on_memo_hit(&blk); end
+
+    sig { params(blk: T.proc.params(cache_key: T.untyped, record: T::Hash[Symbol, T.untyped]).returns(T.untyped)).void }
+    def on_memo_miss(&blk); end
+
+    sig { params(blk: T.proc.params(cache_key: T.untyped, record: T::Hash[Symbol, T.untyped]).returns(T.untyped)).void }
+    def on_memo_store(&blk); end
+
+    sig { params(hook_type: T.nilable(Symbol)).void }
+    def clear_memo_hooks(hook_type = nil); end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, ttl: T.nilable(Numeric), kwargs: T.untyped, blk: T.proc.returns(T.untyped)).returns(T.untyped) }
+    def warm_memo(method_name, *args, ttl: nil, **kwargs, &blk); end
+
+    sig { params(method_name: T.any(Symbol, String), arg_sets: T::Array[T.untyped]).returns(T::Array[T.untyped]) }
+    def memo_preload(method_name, *arg_sets); end
+
+    sig { params(method_name: T.nilable(T.any(Symbol, String))).returns(T::Hash[T.untyped, T.untyped]) }
+    def dump_memo(method_name = nil); end
+
+    sig { params(snapshot: T::Hash[T.untyped, T.untyped]).void }
+    def load_memo(snapshot); end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, ttl: T.nilable(Numeric), kwargs: T.untyped).returns(T::Boolean) }
+    def memo_touch(method_name, *args, ttl: nil, **kwargs); end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped).returns(T.untyped) }
+    def memo_refresh(method_name, *args, **kwargs); end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped).returns(T.nilable(Float)) }
+    def memo_age(method_name, *args, **kwargs); end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped).returns(T::Boolean) }
+    def memo_stale?(method_name, *args, **kwargs); end
+
+    sig { params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped).void }
+    def reset_memo(method_name, *args, **kwargs); end
+
+    sig { void }
+    def reset_all_memos; end
+
+    sig do
+      params(method_name: T.any(Symbol, String), args: T.untyped, kwargs: T.untyped)
+        .returns(T.nilable(T::Hash[Symbol, T.untyped]))
+    end
+    def memo_inspect(method_name, *args, **kwargs); end
+  end
+
+  module PublicMetricsMethods
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def cache_stats; end
+
+    sig { params(method_name: T.any(Symbol, String)).returns(T::Hash[Symbol, T.untyped]) }
+    def cache_stats_for(method_name); end
+
+    sig { returns(Float) }
+    def cache_hit_rate; end
+
+    sig { returns(Float) }
+    def cache_miss_rate; end
+
+    sig { params(method_name: T.nilable(T.any(Symbol, String))).void }
+    def cache_metrics_reset(method_name = nil); end
+  end
+
+  module PublicCustomKeyMethods
+    sig { params(method_name: T.any(Symbol, String), blk: T.proc.params(args: T.untyped).returns(T.untyped)).void }
+    def memoize_with_custom_key(method_name, &blk); end
+
+    sig { params(method_name: T.nilable(T.any(Symbol, String))).void }
+    def clear_custom_keys(method_name = nil); end
+  end
+
+  module Adapters
+    module StatsD
+      METRIC_NAMES = T.let(T.unsafe(nil), T::Hash[Symbol, String])
+
+      sig { params(client: T.untyped, hook_type: Symbol, cache_key: T.untyped, class_name: T.nilable(String)).void }
+      def self.dispatch(client, hook_type, cache_key, class_name); end
+    end
+
+    module OpenTelemetry
+      SPAN_NAME = T.let(T.unsafe(nil), String)
+
+      sig { params(tracer: T.untyped, method_name: T.any(Symbol, String), class_name: T.nilable(String), blk: T.proc.returns(T.untyped)).returns(T.untyped) }
+      def self.trace(tracer, method_name, class_name, &blk); end
+    end
+  end
+
+  module Rails
+    sig { params(instance: T.untyped).void }
+    def self.track(instance); end
+
+    sig { void }
+    def self.reset_tracked!; end
+
+    module RequestScoped
+      sig { params(base: Module).void }
+      def self.included(base); end
+
+      sig { void }
+      def reset_request_memos; end
+    end
+
+    class Middleware
+      sig { params(app: T.untyped).void }
+      def initialize(app); end
+
+      sig { params(env: T.untyped).returns(T.untyped) }
+      def call(env); end
+    end
+  end
+end

data/sig/safe_memoize.rbs

@@ -1,5 +1,9 @@
 module SafeMemoize
   VERSION: String
+
+  class Error < StandardError
+  end
+
   include InstanceMethods
 
   type default_memo_key = [Symbol, Array[untyped], Hash[Symbol, untyped]]
@@ -28,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
@@ -56,15 +61,15 @@ module SafeMemoize
 
     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]
+    def memo_count: (?(Symbol | String) method_name) -> Integer
+    def memo_keys: (?(Symbol | String) method_name) -> Array[untyped]
+    def memo_values: (?(Symbol | String) 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 on_memo_miss: { (memo_key cache_key, memo_record record) -> untyped } -> void
     def on_memo_store: { (memo_key cache_key, memo_record record) -> untyped } -> void
-    def clear_memo_hooks: (Symbol? hook_type) -> void
+    def clear_memo_hooks: (?Symbol hook_type) -> void
     def warm_memo: (Symbol | String method_name, *untyped args, ?ttl: Numeric?, **untyped kwargs) { () -> untyped } -> untyped
     def memo_preload: (Symbol | String method_name, *Array[untyped] arg_sets) -> Array[untyped]
     def dump_memo: (?Symbol | String method_name) -> Hash[memo_key, untyped]
@@ -167,7 +172,7 @@ module SafeMemoize
 
   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
+    def clear_custom_keys: (?(Symbol | String) method_name) -> void
   end
 
   module LruMethods
@@ -195,7 +200,39 @@ 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]
+
+      def self.dispatch: (untyped client, Symbol hook_type, memo_key cache_key, String? class_name) -> void
+    end
+
     module OpenTelemetry
       SPAN_NAME: String
       def self.trace: (untyped tracer, Symbol | String method_name, String? class_name) { () -> untyped } -> untyped

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -41,11 +41,13 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
 - ".github/workflows/release.yml"
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - ROADMAP.md
 - Rakefile
+- UPGRADING.md
 - benchmarks/README.md
 - benchmarks/benchmark.rb
 - codecov.yml
@@ -69,7 +71,12 @@ 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
 homepage: https://github.com/eclectic-coding/safe_memoize
 licenses: