redis-objects-preloadable 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e46629bdca1958195bdb6eebd11446ae6842a574b8789855fdede06cac509fe
-  data.tar.gz: 5730090a0ffd1a8697c061d6a714d6f48a75cc140b809d2377364925d2ace50b
+  metadata.gz: a44062b18cd9ef7c2fed29f9bf72f7438f319bb9383727f7c69dcf013d6c98fd
+  data.tar.gz: 6d9bbfafa458a31596ac7cf721852e5ea05e50ea2fe9ecb2d30c640e0e46b6e6
 SHA512:
-  metadata.gz: 79589dae4c2e987e95d3d9195f00752da234a5f5b0ec37bd0351c9f5d20be83136836784e2627fdde55fead3e30b384a5e0ff8705a6ccc63128c75f4f5f8a820
-  data.tar.gz: 6601dcdf77506ebdc93e574ce9e9b3e469c9538a8376d70d134fa75b7b8fe968a97fd38158026ec66c172344b1f0f00ec03b1dbcd9db09595aaebe01d13e7a29
+  metadata.gz: 8197221aca5a63029b05b0a1a7fa4a54bf8a9ac3338f1467a979016647e534fa61c80ec26b3ac2b903ef88afd1866d51619e369e70da54dded7a573b50bd9996
+  data.tar.gz: 9dae232377119b913f983a42e0fa999f1ccf5ee48261d231b86b4599837de0c2485937ed867f7d13c1d6e6bdcb3bb8beb3440a5df49e89aa938ae3caed991031

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.1.2] - 2026-02-22
+
+- Fix `RelationExtension#reset` to clear `@redis_preload_context_attached`, so `redis_preload` context is correctly re-attached on every `load` after `reset` (matches AR `.includes` behavior)
+- Document that `record.reload` does not clear preloaded Redis values (by design)
+
+## [0.1.1] - 2026-02-22
+
+- Fix Rails 8.1 / Ruby 3.4 compatibility: forward all arguments in `ModelExtension.all` override to avoid `ArgumentError` when `ActiveRecord::Persistence#_find_record` calls `all(all_queries: ...)` ([#fix](https://github.com/kyohah/redis-objects-preloadable/issues))
+
 ## [0.1.0] - 2026-02-20
 
 - Initial release

data/README.md

@@ -105,6 +105,28 @@ Preloading is lazy. The `redis_preload` scope attaches metadata to the relation,
 
 The type patches are applied via `prepend` on `Redis::Counter`, `Redis::Value`, `Redis::List`, `Redis::Set`, `Redis::SortedSet`, and `Redis::HashKey`.
 
+## Limitations
+
+### `record.reload` does not clear preloaded values
+
+`reload` refreshes DB columns only. Preloaded Redis values remain cached on the redis-objects instances and are **not** updated.
+
+```ruby
+widget = Widget.redis_preload(:view_count).first
+widget.view_count.value  # => 5 (preloaded)
+
+# Another process increments the counter in Redis...
+
+widget.reload
+widget.view_count.value  # => 5 (still the preloaded value — NOT refreshed)
+```
+
+If you need a fresh Redis value after `reload`, fetch the record again without preloading:
+
+```ruby
+Widget.find(widget.id).view_count.value  # => hits Redis directly
+```
+
 ## Backward Compatibility: `read_redis_counter`
 
 If your models use the `read_redis_counter` helper (from the original Concern-based approach), it continues to work. With transparent preloading, you can remove explicit `read_redis_counter` calls and access `counter.value` directly.

data/lib/redis/objects/preloadable/model_extension.rb

@@ -3,17 +3,37 @@
 class Redis
   module Objects
     module Preloadable
+      # ActiveSupport::Concern that integrates Preloadable into ActiveRecord models.
+      #
+      # Included automatically when a model does +include Redis::Objects::Preloadable+.
+      # Overrides +.all+ to extend relations with {RelationExtension} and provides
+      # the backward-compatible +read_redis_counter+ helper.
+      #
       module ModelExtension
         extend ActiveSupport::Concern
 
         class_methods do
-          def all
-            super.extending(Redis::Objects::Preloadable::RelationExtension)
+          # @api private
+          def all(...)
+            super(...).extending(Redis::Objects::Preloadable::RelationExtension)
           end
         end
 
         private
 
+        # Backward-compatible helper for reading a counter with SQL fallback.
+        #
+        # If the counter has a preloaded value, it is returned directly.
+        # Otherwise, checks Redis and falls back to the block (SQL query).
+        #
+        # With transparent preloading, this method is no longer necessary.
+        # You can access +counter.value+ directly instead.
+        #
+        # @param _name [Symbol] the counter attribute name (unused in transparent mode)
+        # @param counter [Redis::Counter] the counter instance
+        # @yield SQL fallback block that returns the count
+        # @return [Integer] the counter value
+        #
         def read_redis_counter(_name, counter)
           if counter.instance_variable_defined?(:@preloaded_value)
             raw = counter.instance_variable_get(:@preloaded_value)

data/lib/redis/objects/preloadable/preload_context.rb

@@ -3,15 +3,36 @@
 class Redis
   module Objects
     module Preloadable
+      # Redis::Objects types that support MGET (single-value keys).
       MGET_TYPES = %i[counter value].freeze
 
+      # Holds a batch of records and attribute names, and resolves them
+      # in a single Redis round-trip on first access.
+      #
+      # PreloadContext is created by {RelationExtension#load} or
+      # {Preloadable.preload} and attached to each redis-objects instance.
+      # Resolution is lazy and idempotent.
+      #
+      # @example
+      #   context = PreloadContext.new(records, [:view_count, :tag_ids])
+      #   context.resolve!  # fetches all values in one batch
+      #   context.resolve!  # no-op on subsequent calls
+      #
       class PreloadContext
+        # @param records [Array<ActiveRecord::Base>] records to preload
+        # @param names [Array<Symbol>] redis-objects attribute names
         def initialize(records, names)
           @records = records
           @names = names
           @resolved = false
         end
 
+        # Resolve all preloaded attributes in a single batch.
+        #
+        # Uses MGET for counter/value types and pipelined commands for
+        # list/set/sorted_set/hash_key types. This method is idempotent.
+        #
+        # @return [void]
         def resolve!
           return if @resolved
 

data/lib/redis/objects/preloadable/relation_extension.rb

@@ -3,15 +3,44 @@
 class Redis
   module Objects
     module Preloadable
+      # Extends ActiveRecord::Relation with +redis_preload+ scope.
+      #
+      # This module is automatically mixed into relations via
+      # {ModelExtension::ClassMethods#all}.
+      #
+      # @example
+      #   Widget.where(active: true).redis_preload(:view_count, :tag_ids).each do |w|
+      #     w.view_count.value  # preloaded
+      #   end
+      #
       module RelationExtension
+        # Declare redis-objects attributes to batch-preload when the relation loads.
+        #
+        # Can be chained with other ActiveRecord scopes. Preloading is lazy:
+        # no Redis calls until the first attribute access.
+        #
+        # @param names [Array<Symbol>] redis-objects attribute names
+        # @return [ActiveRecord::Relation] a new relation with preload metadata
+        #
+        # @example
+        #   Widget.order(:id).redis_preload(:view_count).limit(100)
+        #
         def redis_preload(*names)
           spawn.tap { |r| r.instance_variable_set(:@redis_preload_names, names) }
         end
 
+        # @return [Array<Symbol>] the redis-objects attribute names to preload
         def redis_preload_names
           @redis_preload_names || []
         end
 
+        # @api private
+        def reset
+          @redis_preload_context_attached = false
+          super
+        end
+
+        # @api private
         def load
           result = super
 

data/lib/redis/objects/preloadable/type_patches/counter.rb

@@ -4,7 +4,10 @@ class Redis
   module Objects
     module Preloadable
       module TypePatches
+        # Prepended onto Redis::Counter to support preloaded values.
+        # Fetched via MGET. Returns +.to_i+ (0 for nil/missing keys).
         module Counter
+          # @api private
           def preload!(raw_value)
             @preloaded_value = raw_value
           end

data/lib/redis/objects/preloadable/type_patches/hash_key.rb

@@ -4,7 +4,10 @@ class Redis
   module Objects
     module Preloadable
       module TypePatches
+        # Prepended onto Redis::HashKey to support preloaded values.
+        # Fetched via HGETALL in a pipeline.
         module HashKey
+          # @api private
           def preload!(raw_value)
             @preloaded_value = raw_value || {}
           end

data/lib/redis/objects/preloadable/type_patches/list.rb

@@ -4,7 +4,10 @@ class Redis
   module Objects
     module Preloadable
       module TypePatches
+        # Prepended onto Redis::List to support preloaded values.
+        # Fetched via LRANGE 0 -1 in a pipeline.
         module List
+          # @api private
           def preload!(raw_value)
             @preloaded_value = raw_value || []
           end

data/lib/redis/objects/preloadable/type_patches/set.rb

@@ -4,7 +4,10 @@ class Redis
   module Objects
     module Preloadable
       module TypePatches
+        # Prepended onto Redis::Set to support preloaded values.
+        # Fetched via SMEMBERS in a pipeline.
         module Set
+          # @api private
           def preload!(raw_value)
             @preloaded_value = raw_value || []
           end

data/lib/redis/objects/preloadable/type_patches/sorted_set.rb

@@ -4,7 +4,10 @@ class Redis
   module Objects
     module Preloadable
       module TypePatches
+        # Prepended onto Redis::SortedSet to support preloaded values.
+        # Fetched via ZRANGE 0 -1 WITHSCORES in a pipeline.
         module SortedSet
+          # @api private
           def preload!(raw_value)
             @preloaded_value = raw_value || []
           end

data/lib/redis/objects/preloadable/type_patches/value.rb

@@ -4,7 +4,10 @@ class Redis
   module Objects
     module Preloadable
       module TypePatches
+        # Prepended onto Redis::Value to support preloaded values.
+        # Fetched via MGET. Returns raw string or nil.
         module Value
+          # @api private
           def preload!(raw_value)
             @preloaded_value = raw_value
           end

data/lib/redis/objects/preloadable/version.rb

@@ -3,7 +3,7 @@
 class Redis
   module Objects
     module Preloadable
-      VERSION = "0.1.0"
+      VERSION = "0.1.2"
     end
   end
 end

data/lib/redis/objects/preloadable.rb

@@ -21,6 +21,36 @@ Redis::Set.prepend(Redis::Objects::Preloadable::TypePatches::Set)
 Redis::SortedSet.prepend(Redis::Objects::Preloadable::TypePatches::SortedSet)
 Redis::HashKey.prepend(Redis::Objects::Preloadable::TypePatches::HashKey)
 
+# Redis::Objects::Preloadable eliminates N+1 Redis calls for redis-objects
+# attributes on ActiveRecord models.
+#
+# It provides two APIs:
+#
+# 1. +redis_preload+ scope on ActiveRecord relations
+# 2. +Redis::Objects::Preloadable.preload+ for arbitrary record arrays
+#
+# == Basic usage
+#
+#   class Pack < ApplicationRecord
+#     include Redis::Objects
+#     include Redis::Objects::Preloadable
+#
+#     counter :cache_total_count
+#     list    :recent_item_ids
+#   end
+#
+#   # Scope-based (top-level queries)
+#   Pack.redis_preload(:cache_total_count, :recent_item_ids).limit(100).each do |pack|
+#     pack.cache_total_count.value  # preloaded via MGET
+#     pack.recent_item_ids.values   # preloaded via pipeline
+#   end
+#
+# == Association-loaded records
+#
+#   users = User.includes(:articles).load
+#   articles = users.flat_map(&:articles)
+#   Redis::Objects::Preloadable.preload(articles, :view_count)
+#
 class Redis
   module Objects
     module Preloadable
@@ -28,6 +58,23 @@ class Redis
         base.include(ModelExtension)
       end
 
+      # Batch-preload Redis::Objects attributes on an array of records.
+      #
+      # Use this for records loaded outside of +redis_preload+ scope,
+      # such as association-loaded records via +includes+.
+      #
+      # Preloading is lazy: no Redis calls are made until the first
+      # attribute access on any of the records.
+      #
+      # @param records [Array<ActiveRecord::Base>, ActiveRecord::Relation] records to preload
+      # @param names [Array<Symbol>] redis-objects attribute names to preload
+      # @return [Array<ActiveRecord::Base>] the same records array
+      #
+      # @example Preload on association-loaded records
+      #   users = User.includes(:articles).load
+      #   articles = users.flat_map(&:articles)
+      #   Redis::Objects::Preloadable.preload(articles, :view_count, :cached_summary)
+      #
       def self.preload(records, *names)
         records = records.to_a
         return records if records.empty? || names.empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis-objects-preloadable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - kyohah