Add memoize: true option for per-instance caching

[agrberg]

Summary

• Adds a memoize: true option to cacheable that stores deserialized values directly on the instance, skipping the cache adapter on repeated calls
• Memoized values are keyed by cache key (matching adapter identity semantics) and cleared automatically by clear_*_cache
• Zero overhead when memoize is not used — the feature is fully opt-in

Closes #15

Context

When using a serializing cache backend (Redis, Memcached), every call to a cached method pays the deserialization cost via Marshal.load. For expensive objects like ActiveRecord models, this becomes a bottleneck when the same method is called repeatedly within a single request. With memoize: true, the first call fetches from the adapter as usual, but subsequent calls on the same instance return the already-deserialized object directly.

Test plan

• All 73 existing + new tests pass (bundle exec rspec)
• RuboCop clean (bundle exec rubocop)
• Example script runs and demonstrates adapter hit difference (bundle exec ruby examples/memoize_example.rb)
• Verify behavior with a real serializing adapter (e.g., Rails.cache backed by Redis)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an opt-in memoize: true mode to cacheable to avoid repeated cache-adapter fetch/deserialization by storing the deserialized result on the receiver (instance or class object) for the lifetime of that receiver.

Changes:

• Add per-receiver memoization to generated cacheable methods, keyed by computed cache key.
• Add a Cacheable::MEMOIZE_NOT_SET sentinel to correctly memoize nil/false.
• Add RSpec coverage, README documentation, and an example script demonstrating reduced adapter hits.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lib/cacheable/method_generator.rb	Implements memoization fast-path and memo store writes; hooks memo clearing into clear_*_cache.
lib/cacheable.rb	Introduces sentinel constant used by memoization to distinguish “unset” from nil/false.
spec/cacheable/cacheable_spec.rb	Adds tests covering memoization behavior (adapter hit reduction, nil/false, unless, clearing, class methods).
README.md	Documents memoize: true, usage, and caveats around object lifetime / staleness.
examples/memoize_example.rb	Demonstrates adapter-hit difference with and without memoization.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[agrberg]

This branch should address and close our last open issue. To be merged after #21