cacheable 1.0.4 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba379f0770988ff42a99397f056206bbbb9b60a59b51a5fee51d687263adb96e
-  data.tar.gz: ef68f492cf221457515452df0324ff87d634914ac67e286a4e698c096e5a2a3e
+  metadata.gz: 9f7c4005f6683ae5c61de0d34d3795ac4607e6bb001e7f73065b947559720662
+  data.tar.gz: '0439c9b90265170df3706406c52c896fb8953c7e5737c9027ce9d140dcef6aed'
 SHA512:
-  metadata.gz: 79e94e9ec720e03d2be5370ac8554c2c1635589b5cfffec5a56f27fe228944e659da1e5aa52b94836559fc06301a6f1e41d0df418c7305db925a175754ce73d8
-  data.tar.gz: e56db78b1855a5cb4bcba7b1f408d4c4cff9cbef03f05641596e721c0b332bfc7878769632ef2eda6e6d2476505bdaf38b477fa32abc6513170b88806d21209b
+  metadata.gz: c08c9cdc5d6b3a9811b072df3feae84cf87dc7cadccee8fafc654b15de24d240f0ddb2c4a1bbee879765e11fef04e69cd6b81d126ffe96e9410eea8436fb239a
+  data.tar.gz: 384da8f24a3cdd069c9f634d31a2ef77bb1b83083aa9ca4f5d0adce364c172cf04efd0ad235373b66cb648e196cb04804d0ada2ac78400b7b5cdf75b214c1db6

data/README.md

@@ -1,7 +1,11 @@
 # Cacheable
 
+[![CI](https://github.com/splitwise/cacheable/actions/workflows/ci.yml/badge.svg)](https://github.com/splitwise/cacheable/actions/workflows/ci.yml)
+
 By [Splitwise](https://www.splitwise.com)
 
+Requires Ruby >= 3.3
+
 Cacheable is a gem which adds method caching in Ruby following an [aspect-oriented programming (AOP)](https://en.wikipedia.org/wiki/Aspect-oriented_programming) paradigm. Its core goals are:
 
 * ease of use (method annotation)
@@ -78,9 +82,9 @@ end
 > a = GitHubApiAdapter.new
 > a.star_count
 Fetching data from GitHub
- => 19
+ => 58
 > a.star_count
- => 19
+ => 58
 
 # Notice that "Fetching data from GitHub" was not output the 2nd time the method was invoked.
 # The network call and result parsing would also not be performed again.
@@ -98,12 +102,12 @@ The cache can intentionally be skipped by appending `_without_cache` to the meth
 > a = GitHubApiAdapter.new
 > a.star_count
 Fetching data from GitHub
- => 19
+ => 58
 > a.star_count_without_cache
 Fetching data from GitHub
- => 19
+ => 58
 > a.star_count
- => 19
+ => 58
 ```
 
 #### Remove the Value via `clear_#{method}_cache`
@@ -114,15 +118,15 @@ The cached value can be cleared at any time by calling `clear_#{your_method_name
 > a = GitHubApiAdapter.new
 > a.star_count
 Fetching data from GitHub
- => 19
+ => 58
 > a.star_count
- => 19
+ => 58
 
 > a.clear_star_count_cache
  => true
 > a.star_count
 Fetching data from GitHub
- => 19
+ => 58
 ```
 
 ## Additional Configuration
@@ -131,7 +135,7 @@ Fetching data from GitHub
 
 #### Default
 
-By default, Cacheable will construct key a key in the format `[cache_key || class_name, method_name]` without using method arguments.
+By default, Cacheable will construct a key in the format `[cache_key || class_name, method_name]` without using method arguments. If a cached method is called with arguments while using the default key format, Cacheable will emit a warning to stderr since different arguments will return the same cached value. To silence the warning, provide a `:key_format` proc that includes the arguments in the cache key.
 
 If the object responds to `cache_key` its return value will be the first element in the array. `ActiveRecord` provides [`cache_key`](https://api.rubyonrails.org/classes/ActiveRecord/Integration.html#method-i-cache_key) but it can be added to any Ruby object or overwritten. If the object does not respond to it, the name of the class will be used instead. The second element will be the name of the method as a symbol.
 
@@ -151,12 +155,13 @@ require 'net/http'
 class GitHubApiAdapter
   include Cacheable
 
-  cacheable :star_count, key_format: ->(target, method_name, method_args) do
-    [target.class, method_name, method_args.first, Time.now.strftime('%Y-%m-%d')].join('/')
+  cacheable :star_count, key_format: ->(target, method_name, method_args, **kwargs) do
+    date = kwargs.fetch(:date, Time.now.strftime('%Y-%m-%d'))
+    [target.class, method_name, method_args.first, date].join('/')
   end
 
-  def star_count(repo)
-    puts "Fetching data from GitHub for #{repo}"
+  def star_count(repo, date: Time.now.strftime('%Y-%m-%d'))
+    puts "Fetching data from GitHub for #{repo} (as of #{date})"
     url = "https://api.github.com/repos/splitwise/#{repo}"
 
     JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
@@ -166,33 +171,34 @@ end
 
 * `target` is the object the method is being called on (`#<GitHubApiAdapter:0x0…0>`)
 * `method_name` is the name of the method being cached (`:star_count`)
-* `method_args` is an array of arguments being passed to the method (`[params]`)
+* `method_args` is an array of positional arguments being passed to the method (`[params]`)
+* `**kwargs` are the keyword arguments being passed to the method
 
 Including the method argument(s) allows you to cache different calls to the same method. Without the arguments in the cache key, a call to `star_count('cacheable')` would populate the cache and `star_count('tokenautocomplete')` would return the number of stars for Cacheable instead of what you want.
 
-In addition, we're including the current date in the cache key so calling this method tomorrow will return an updated value.
+**Note:** The `key_format` proc only receives keyword arguments that the caller explicitly passes — method defaults are not included. That's why the proc uses `kwargs.fetch(:date, Time.now.strftime('%Y-%m-%d'))` to compute its own default when `date:` is omitted. This ensures the cache key always varies by date.
 
 ```irb
 > a = GitHubApiAdapter.new
 > a.star_count('cacheable')
-Fetching data from GitHub for cacheable
- => 19
+Fetching data from GitHub for cacheable (as of 2026-02-26)
+ => 58
 > a.star_count('cacheable')
- => 19
+ => 58
 > a.star_count('tokenautocomplete')
-Fetching data from GitHub for tokenautocomplete
- => 1164
+Fetching data from GitHub for tokenautocomplete (as of 2026-02-26)
+ => 1309
 > a.star_count('tokenautocomplete')
- => 1164
+ => 1309
 
  # In this example the follow cache keys are generated:
- # GitHubApiAdapter/star_count/cacheable/2018-09-21
- # GitHubApiAdapter/star_count/tokenautocomplete/2018-09-21
+ # GitHubApiAdapter/star_count/cacheable/2026-02-26
+ # GitHubApiAdapter/star_count/tokenautocomplete/2026-02-26
 ```
 
 ### Conditional Caching
 
-You can control if a method should be cached by supplying a proc to the `unless:` option which will get the same arguments as `key_format:`. This logic can be defined in a method on the class and the name of the method as a symbol can be passed as well. **Note**: When using a symbol, the first argument, `target`, will not be passed but will be available as `self`.
+You can control if a method should be cached by supplying a proc to the `unless:` option which will get the same arguments as `key_format:` (`target, method_name, method_args, **kwargs`). This logic can be defined in a method on the class and the name of the method as a symbol can be passed as well. **Note**: When using a symbol, the first argument, `target`, will not be passed but will be available as `self`.
 
 ```ruby
 # From examples/conditional_example.rb
@@ -204,18 +210,19 @@ require 'net/http'
 class GitHubApiAdapter
   include Cacheable
 
-  cacheable :star_count, unless: :growing_fast?, key_format: ->(target, method_name, method_args) do
-    [target.class, method_name, method_args.first].join('/')
+  cacheable :star_count, unless: :growing_fast?, key_format: ->(target, method_name, method_args, **kwargs) do
+    date = kwargs.fetch(:date, Time.now.strftime('%Y-%m-%d'))
+    [target.class, method_name, method_args.first, date].join('/')
   end
 
-  def star_count(repo)
-    puts "Fetching data from GitHub for #{repo}"
+  def star_count(repo, date: Time.now.strftime('%Y-%m-%d'))
+    puts "Fetching data from GitHub for #{repo} (as of #{date})"
     url = "https://api.github.com/repos/splitwise/#{repo}"
 
     JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
   end
 
-  def growing_fast?(_method_name, method_args)
+  def growing_fast?(_method_name, method_args, **)
     method_args.first == 'cacheable'
   end
 end
@@ -226,17 +233,17 @@ Cacheable is new so we don't want to cache the number of stars it has as we expe
 ```irb
 > a = GitHubApiAdapter.new
 > a.star_count('tokenautocomplete')
-Fetching data from GitHub for tokenautocomplete
- => 1164
+Fetching data from GitHub for tokenautocomplete (as of 2026-02-26)
+ => 1309
 a.star_count('tokenautocomplete')
- => 1164
+ => 1309
 
 > a.star_count('cacheable')
-Fetching data from GitHub for cacheable
- => 19
+Fetching data from GitHub for cacheable (as of 2026-02-26)
+ => 58
 > a.star_count('cacheable')
-Fetching data from GitHub for cacheable
- => 19
+Fetching data from GitHub for cacheable (as of 2026-02-26)
+ => 58
 ```
 
 ### Cache Options
@@ -247,6 +254,72 @@ If your cache backend supports options, you can pass them as the `cache_options:
 cacheable :with_options, cache_options: {expires_in: 3_600}
 ```
 
+### Memoization
+
+By default, every call to a cached method hits the cache adapter, which includes deserialization. For methods where the deserialized object is expensive to reconstruct (e.g., large ActiveRecord collections), you can enable per-instance memoization so that repeated calls on the **same object** skip the adapter entirely:
+
+```ruby
+# From examples/memoize_example.rb
+
+class ExpensiveService
+  include Cacheable
+
+  cacheable :without_memoize
+
+  cacheable :with_memoize, memoize: true
+
+  def without_memoize
+    puts '  [method] computing value'
+    42
+  end
+
+  def with_memoize
+    puts '  [method] computing value'
+    42
+  end
+end
+```
+
+Using a logging adapter wrapper (see `examples/memoize_example.rb` for the full setup), the difference becomes clear:
+
+```
+--- without memoize ---
+  [cache] fetch ["ExpensiveService", :without_memoize]
+  [method] computing value
+  [cache] fetch ["ExpensiveService", :without_memoize]    <-- adapter hit again (deserialization cost)
+
+--- with memoize: true ---
+  [cache] fetch ["ExpensiveService", :with_memoize]
+  [method] computing value
+                                                           <-- no adapter hit on second call
+
+--- after clearing ---
+  [cache] fetch ["ExpensiveService", :with_memoize]       <-- adapter hit again after clear
+  [method] computing value
+```
+
+**Important**: Memoized values persist for the lifetime of the object instance, and after the first call they bypass the cache adapter entirely. This means adapter-driven expiration (`expires_in`) and other backend invalidation mechanisms will **not** be re-checked while the instance stays alive. If your cache key changes (e.g., `cache_key` based on `updated_at`), the memoized value will also **not** automatically update. This is especially important for class-method memoization (where the "instance" is the class itself), because the memo can effectively outlive the cache TTL. Use `memoize: true` only when you know the value will not change for the lifetime of the instance (or class), or call `clear_#{method}_cache` explicitly when needed.
+
+### Per-Class Cache Adapter
+
+By default, all classes use the global adapter set via `Cacheable.cache_adapter`. If you need a specific class to use a different cache backend, you can set one directly on the class:
+
+```ruby
+class FrequentlyAccessedModel
+  include Cacheable
+
+  self.cache_adapter = MyFasterCache.new
+
+  cacheable :expensive_lookup
+
+  def expensive_lookup
+    # ...
+  end
+end
+```
+
+The class-level adapter takes precedence over the global adapter. Classes without their own adapter fall back to `Cacheable.cache_adapter` as usual.
+
 ### Flexible Options
 
 You can use the same options with multiple cache methods or limit them only to specific methods:
@@ -298,15 +371,15 @@ end
 ```irb
 > GitHubApiAdapter.star_count_for_cacheable
 Fetching data from GitHub for cacheable
- => 19
+ => 58
 > GitHubApiAdapter.star_count_for_cacheable
- => 19
+ => 58
 
 > GitHubApiAdapter.star_count_for_tokenautocomplete
 Fetching data from GitHub for tokenautocomplete
- => 1164
+ => 1309
 > GitHubApiAdapter.star_count_for_tokenautocomplete
- => 1164
+ => 1309
 ```
 
 ### Other Notes / Frequently Asked Questions

data/lib/cacheable/cache_adapter.rb

@@ -7,11 +7,11 @@ module Cacheable
 
     def self.extended(base)
       base.instance_variable_set(:@_cache_adapter, nil)
-      base.cache_adapter = DEFAULT_ADAPTER
+      base.cache_adapter = DEFAULT_ADAPTER if base == Cacheable
     end
 
     def cache_adapter
-      @_cache_adapter
+      @_cache_adapter || (self == Cacheable ? nil : Cacheable.cache_adapter)
     end
 
     def cache_adapter=(name_or_adapter)

data/lib/cacheable/cache_adapters/memory_adapter.rb

@@ -1,42 +1,50 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
 module Cacheable
   module CacheAdapters
     class MemoryAdapter
       def initialize
+        @monitor = Monitor.new
         clear
       end
 
       def read(key)
-        cache[key]
+        @monitor.synchronize { @cache[key] }
       end
 
       def write(key, value)
-        cache[key] = value
+        @monitor.synchronize { @cache[key] = value }
       end
 
       def exist?(key)
-        cache.key?(key)
+        @monitor.synchronize { @cache.key?(key) }
       end
 
+      # NOTE: yield is intentionally called inside the lock to prevent thundering herd — only one thread
+      # computes a missing value while others wait. This is acceptable for a simple in-memory adapter;
+      # production use cases needing high concurrency should use a real cache backend via CacheAdapter.
       def fetch(key, _options = {})
-        return read(key) if exist?(key)
+        @monitor.synchronize do
+          return @cache[key] if @cache.key?(key)
 
-        write(key, Proc.new.call)
+          @cache[key] = yield
+        end
       end
 
       def delete(key)
-        return false unless exist?(key)
+        @monitor.synchronize do
+          return false unless @cache.key?(key)
 
-        cache.delete key
-        true
+          @cache.delete(key)
+          true
+        end
       end
 
       def clear
-        @cache = {}
+        @monitor.synchronize { @cache = {} }
       end
-
-      private
-
-      attr_reader :cache
     end
   end
 end

data/lib/cacheable/cache_adapters.rb

@@ -14,7 +14,7 @@ module Cacheable
       private
 
       def class_name_for(string)
-        string.split('_').map { |name_part| "#{name_part[0].upcase}#{name_part[1..-1].downcase}" }.join
+        string.split('_').map { |name_part| "#{name_part[0].upcase}#{name_part[1..].downcase}" }.join
       end
     end
   end

data/lib/cacheable/method_generator.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'English'
-
 module Cacheable
   module MethodGenerator
     def cacheable(*original_method_names, **opts)
@@ -13,51 +11,72 @@ module Cacheable
     private
 
     def method_interceptor_module_name
-      class_name = name&.gsub(/:/, '') || to_s.gsub(/[^a-zA-Z_0-9]/, '')
+      class_name = name&.gsub(':', '') || to_s.gsub(/[^a-zA-Z_0-9]/, '')
       "#{class_name}Cacher"
     end
 
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    # rubocop:disable Metrics/AbcSize, Metrics/BlockLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def create_cacheable_methods(original_method_name, opts = {})
       method_names = create_method_names(original_method_name)
       key_format_proc = opts[:key_format] || default_key_format
 
-      const_get(method_interceptor_module_name).class_eval do
-        define_method(method_names[:key_format_method_name]) do |*args|
-          key_format_proc.call(self, original_method_name, args)
+      unless_proc = opts[:unless].is_a?(Symbol) ? opts[:unless].to_proc : opts[:unless]
+
+      @_cacheable_interceptor.class_eval do
+        define_method(method_names[:key_format_method_name]) do |*args, **kwargs|
+          key_format_proc.call(self, original_method_name, args, **kwargs)
         end
 
-        define_method(method_names[:clear_cache_method_name]) do |*args|
-          Cacheable.cache_adapter.delete(__send__(method_names[:key_format_method_name], *args))
+        define_method(method_names[:clear_cache_method_name]) do |*args, **kwargs|
+          cache_key = __send__(method_names[:key_format_method_name], *args, **kwargs)
+          @_cacheable_memoized&.dig(original_method_name)&.delete(cache_key) if opts[:memoize]
+          adapter = (is_a?(Module) ? singleton_class : self.class).cache_adapter
+          adapter.delete(cache_key)
         end
 
-        define_method(method_names[:without_cache_method_name]) do |*args|
-          original_method = method(original_method_name).super_method
-          original_method.call(*args)
+        define_method(method_names[:without_cache_method_name]) do |*args, **kwargs, &block|
+          method(original_method_name).super_method.call(*args, **kwargs, &block)
         end
 
-        define_method(method_names[:with_cache_method_name]) do |*args|
-          Cacheable.cache_adapter.fetch(__send__(method_names[:key_format_method_name], *args), opts[:cache_options]) do
-            __send__(method_names[:without_cache_method_name], *args)
+        define_method(method_names[:with_cache_method_name]) do |*args, **kwargs, &block|
+          cache_key = __send__(method_names[:key_format_method_name], *args, **kwargs)
+
+          if opts[:memoize]
+            method_memo = ((@_cacheable_memoized ||= {})[original_method_name] ||= {})
+            cached = method_memo.fetch(cache_key, Cacheable::MEMOIZE_NOT_SET)
+            return cached unless cached.equal?(Cacheable::MEMOIZE_NOT_SET)
           end
-        end
 
-        define_method(original_method_name) do |*args|
-          unless_proc = opts[:unless].is_a?(Symbol) ? opts[:unless].to_proc : opts[:unless]
+          adapter = (is_a?(Module) ? singleton_class : self.class).cache_adapter
+          result = adapter.fetch(cache_key, opts[:cache_options]) do # rubocop:disable Lint/UselessDefaultValueArgument -- not Hash#fetch; second arg is cache options (e.g. expires_in) passed to the adapter
+            __send__(method_names[:without_cache_method_name], *args, **kwargs, &block)
+          end
+          method_memo[cache_key] = result if opts[:memoize]
+          result
+        end
 
-          if unless_proc&.call(self, original_method_name, args)
-            __send__(method_names[:without_cache_method_name], *args)
+        define_method(original_method_name) do |*args, **kwargs, &block|
+          if unless_proc&.call(self, original_method_name, args, **kwargs)
+            __send__(method_names[:without_cache_method_name], *args, **kwargs, &block)
           else
-            __send__(method_names[:with_cache_method_name], *args)
+            __send__(method_names[:with_cache_method_name], *args, **kwargs, &block)
           end
         end
       end
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    # rubocop:enable Metrics/AbcSize, Metrics/BlockLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
     def default_key_format
-      proc do |target, method_name, _method_args|
-        # By default, we omit the _method_args from the cache key because there is no acceptable default behavior
+      warned = false
+
+      proc do |target, method_name, method_args, **kwargs|
+        if !warned && (!method_args.empty? || !kwargs.empty?)
+          warn "Cacheable WARNING: '#{method_name}' is using the default key format but was called with " \
+               'arguments. Arguments are NOT included in the cache key, so different arguments will return ' \
+               'the same cached value. Provide a :key_format proc to include arguments in the cache key.'
+          warned = true
+        end
+
         class_name = (target.is_a?(Module) ? target.name : target.class.name)
         cache_key = target.respond_to?(:cache_key) ? target.cache_key : class_name
         [cache_key, method_name].compact
@@ -66,7 +85,7 @@ module Cacheable
 
     def create_method_names(original_method_name)
       method_name_without_punctuation = original_method_name.to_s.sub(/([?!=])$/, '')
-      punctuation = $LAST_PAREN_MATCH
+      punctuation = Regexp.last_match(-1)
 
       {
         with_cache_method_name: "#{method_name_without_punctuation}_with_cache#{punctuation}",

data/lib/cacheable/version.rb

@@ -2,15 +2,13 @@
 
 module Cacheable
   module VERSION
-    MAJOR = 1
-    MINOR = 0
-    TINY = 4
+    MAJOR = 2
+    MINOR = 1
+    TINY = 0
     PRE = nil
 
-    STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.').freeze
-
     def self.to_s
-      STRING
+      [MAJOR, MINOR, TINY, PRE].compact.join('.').freeze
     end
   end
 end

data/lib/cacheable.rb

@@ -31,12 +31,18 @@ require 'cacheable/version'
 module Cacheable
   extend CacheAdapter
 
+  # Sentinel value to distinguish "not yet memoized" from a memoized nil/false.
+  MEMOIZE_NOT_SET = Object.new.freeze
+
   def self.included(base)
+    base.extend(Cacheable::CacheAdapter)
     base.extend(Cacheable::MethodGenerator)
 
     interceptor_name = base.send(:method_interceptor_module_name)
-    remove_const(interceptor_name) if const_defined?(interceptor_name)
-
-    base.prepend const_set(interceptor_name, Module.new)
+    interceptor = Module.new
+    interceptor.define_singleton_method(:to_s) { interceptor_name }
+    interceptor.define_singleton_method(:inspect) { interceptor_name }
+    base.instance_variable_set(:@_cacheable_interceptor, interceptor)
+    base.prepend interceptor
   end
 end

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: cacheable
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 2.1.0
 platform: ruby
 authors:
 - Jess Hottenstein
 - Ryan Laughlin
 - Aaron Rosenberg
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2018-07-31 00:00:00.000000000 Z
+date: 2026-03-02 00:00:00.000000000 Z
 dependencies: []
 description: Add caching simply without modifying your existing code. Includes configurable
   options for simple cache invalidation. See README on github for more information.
@@ -30,8 +30,9 @@ files:
 homepage: https://github.com/splitwise/cacheable
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -39,16 +40,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.8
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Add caching to any Ruby method in a aspect orientated programming approach.
 test_files: []