redis-objects-preloadable 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e46629bdca1958195bdb6eebd11446ae6842a574b8789855fdede06cac509fe
-  data.tar.gz: 5730090a0ffd1a8697c061d6a714d6f48a75cc140b809d2377364925d2ace50b
+  metadata.gz: 2135bc0cffef091721bc51971f69adbfbe636ef10a372758db3e4de164bf7ec9
+  data.tar.gz: cae263e6dafa776af239cf3ce8d7a38d1f2eccbf2452b90e5a2a8afe82bf8680
 SHA512:
-  metadata.gz: 79589dae4c2e987e95d3d9195f00752da234a5f5b0ec37bd0351c9f5d20be83136836784e2627fdde55fead3e30b384a5e0ff8705a6ccc63128c75f4f5f8a820
-  data.tar.gz: 6601dcdf77506ebdc93e574ce9e9b3e469c9538a8376d70d134fa75b7b8fe968a97fd38158026ec66c172344b1f0f00ec03b1dbcd9db09595aaebe01d13e7a29
+  metadata.gz: 82c717b269c84a0c977b195ec5be729a177e83d00268506eb9d2efc641cf1d32938fd4f9eb9c6346746b55e11ba0b41d954051719140c7e1f99ecd54e345f085
+  data.tar.gz: 4b96bf14d1cce588cf96500819898aa0da85468f75fce4e9b9042d6ea22bd50c25ab392def2120323e39d0b47e7a295204a674ea3af48a811e26a6e4c50706e9

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [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/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,38 @@
 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 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.1"
     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.1
 platform: ruby
 authors:
 - kyohah