redis-objects-preloadable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2e46629bdca1958195bdb6eebd11446ae6842a574b8789855fdede06cac509fe
+  data.tar.gz: 5730090a0ffd1a8697c061d6a714d6f48a75cc140b809d2377364925d2ace50b
+SHA512:
+  metadata.gz: 79589dae4c2e987e95d3d9195f00752da234a5f5b0ec37bd0351c9f5d20be83136836784e2627fdde55fead3e30b384a5e0ff8705a6ccc63128c75f4f5f8a820
+  data.tar.gz: 6601dcdf77506ebdc93e574ce9e9b3e469c9538a8376d70d134fa75b7b8fe968a97fd38158026ec66c172344b1f0f00ec03b1dbcd9db09595aaebe01d13e7a29

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-02-20
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 kyohah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,128 @@
+# redis-objects-preloadable
+
+[English](README.md) | [日本語](docs/ja/index.md) | [中文](docs/zh/index.md) | [Français](docs/fr/index.md) | [Deutsch](docs/de/index.md)
+
+Eliminate N+1 Redis calls for [redis-objects](https://github.com/nateware/redis-objects) in ActiveRecord models.
+
+Provides `redis_preload` scope that batch-loads Redis::Objects attributes using `MGET` (for counter/value) and `pipelined` commands (for list/set/sorted_set/hash_key), following the same design as ActiveRecord's `preload`.
+
+## Installation
+
+```ruby
+gem "redis-objects-preloadable"
+```
+
+## Setup
+
+Include `Redis::Objects::Preloadable` in your model after `Redis::Objects`:
+
+```ruby
+class Pack < ApplicationRecord
+  include Redis::Objects
+  include Redis::Objects::Preloadable
+
+  counter :cache_total_count, expiration: 15.minutes
+  list    :recent_item_ids
+  set     :tag_ids
+end
+```
+
+## Usage
+
+Chain `redis_preload` onto any ActiveRecord relation:
+
+```ruby
+records = Pack.order(:id)
+              .redis_preload(:cache_total_count, :recent_item_ids, :tag_ids)
+              .limit(100)
+
+records.each do |pack|
+  pack.cache_total_count.value   # preloaded, no Redis call
+  pack.recent_item_ids.values    # preloaded
+  pack.tag_ids.members           # preloaded
+end
+```
+
+Without `redis_preload`, accessing Redis attributes falls back to individual Redis calls (original behavior).
+
+### Preloading on Association-Loaded Records
+
+`redis_preload` works on top-level relations. For records loaded via `includes` / `preload` / `eager_load`, use `Redis::Objects::Preloadable.preload`:
+
+```ruby
+class User < ApplicationRecord
+  has_many :articles
+end
+
+class Article < ApplicationRecord
+  include Redis::Objects
+  include Redis::Objects::Preloadable
+
+  counter :view_count
+  value   :cached_summary
+end
+
+users = User.includes(:articles).load
+
+# Batch-preload Redis attributes on the associated records
+articles = users.flat_map(&:articles)
+Redis::Objects::Preloadable.preload(articles, :view_count, :cached_summary)
+
+users.each do |user|
+  user.articles.each do |article|
+    article.view_count.value     # preloaded, no Redis call
+    article.cached_summary.value # preloaded
+  end
+end
+```
+
+`Redis::Objects::Preloadable.preload` accepts any array of records, so it works in any context — not just associations.
+
+### Lazy Resolution
+
+Preloading is lazy. The `redis_preload` scope attaches metadata to the relation, but no Redis calls are made until you first access a preloaded attribute. At that point, all declared attributes for all loaded records are fetched in a single batch.
+
+## Supported Types
+
+| redis-objects type | Redis command     | Preloaded methods                          |
+|--------------------|-------------------|--------------------------------------------|
+| `counter`          | MGET              | `value`, `nil?`                            |
+| `value`            | MGET              | `value`, `nil?`                            |
+| `list`             | LRANGE 0 -1       | `value`, `values`, `[]`, `length`, `empty?`|
+| `set`              | SMEMBERS          | `members`, `include?`, `length`, `empty?`  |
+| `sorted_set`       | ZRANGE WITHSCORES | `members`, `score`, `rank`, `length`       |
+| `hash_key`         | HGETALL           | `all`, `[]`, `keys`, `values`              |
+
+## How It Works
+
+1. `redis_preload(:attr1, :attr2)` extends the AR relation with `RelationExtension`
+2. When the relation is loaded, a `PreloadContext` is attached to each redis-objects instance
+3. On first attribute access, `PreloadContext#resolve!` fires:
+   - **counter/value** types: batched via `MGET`
+   - **list/set/sorted_set/hash_key** types: batched via `pipelined`
+4. Each redis-objects instance receives its preloaded value via `preload!`
+5. Subsequent reads return the preloaded value without hitting Redis
+
+The type patches are applied via `prepend` on `Redis::Counter`, `Redis::Value`, `Redis::List`, `Redis::Set`, `Redis::SortedSet`, and `Redis::HashKey`.
+
+## 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.
+
+## Requirements
+
+- Ruby >= 3.1
+- ActiveRecord >= 7.0
+- redis-objects >= 1.7
+
+## Development
+
+```bash
+bin/setup           # install dependencies
+bundle exec rspec   # run tests (requires local Redis)
+bundle exec rubocop # lint
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class Redis
+  module Objects
+    module Preloadable
+      module ModelExtension
+        extend ActiveSupport::Concern
+
+        class_methods do
+          def all
+            super.extending(Redis::Objects::Preloadable::RelationExtension)
+          end
+        end
+
+        private
+
+        def read_redis_counter(_name, counter)
+          if counter.instance_variable_defined?(:@preloaded_value)
+            raw = counter.instance_variable_get(:@preloaded_value)
+            return raw.to_i if raw
+
+            count = yield
+            counter.value = count
+            return count
+          end
+
+          if counter.exists?
+            counter.value.to_i
+          else
+            count = yield
+            counter.value = count
+            count
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+class Redis
+  module Objects
+    module Preloadable
+      MGET_TYPES = %i[counter value].freeze
+
+      class PreloadContext
+        def initialize(records, names)
+          @records = records
+          @names = names
+          @resolved = false
+        end
+
+        def resolve!
+          return if @resolved
+
+          @resolved = true
+          return if @records.empty?
+
+          execute_preload
+        end
+
+        private
+
+        def execute_preload
+          klass = @records.first.class
+          prefix = klass.redis_prefix
+          ids = @records.map(&:id)
+          redis_objects = klass.redis_objects
+
+          mget_names = @names.select { |n| MGET_TYPES.include?(redis_objects.dig(n, :type)) }
+          pipeline_names = @names - mget_names
+
+          with_redis do |redis|
+            fetch_mget(redis, prefix, ids, mget_names)
+            fetch_pipeline(redis, prefix, ids, pipeline_names, redis_objects)
+          end
+        end
+
+        def with_redis(&)
+          redis_conn = ::Redis::Objects.redis
+          if redis_conn.respond_to?(:with)
+            redis_conn.with(&)
+          else
+            yield redis_conn
+          end
+        end
+
+        def fetch_mget(redis, prefix, ids, names)
+          return if names.empty?
+
+          n = ids.size
+          keys = names.flat_map { |name| ids.map { |id| "#{prefix}:#{id}:#{name}" } }
+          values = redis.mget(*keys)
+
+          names.each_with_index do |name, i|
+            @records.zip(values[i * n, n]).each do |record, raw_value|
+              record.public_send(name).preload!(raw_value)
+            end
+          end
+        end
+
+        def fetch_pipeline(redis, prefix, ids, names, redis_objects)
+          return if names.empty?
+
+          order, results = run_pipeline(redis, prefix, ids, names, redis_objects)
+          apply_pipeline_results(order, results)
+        end
+
+        def run_pipeline(redis, prefix, ids, names, redis_objects)
+          order = []
+          results = redis.pipelined do |pipe|
+            names.each do |name|
+              type = redis_objects.dig(name, :type)
+              ids.each do |id|
+                order << [name, id]
+                pipeline_command(pipe, "#{prefix}:#{id}:#{name}", type)
+              end
+            end
+          end
+          [order, results]
+        end
+
+        def pipeline_command(pipe, key, type)
+          case type
+          when :list       then pipe.lrange(key, 0, -1)
+          when :set        then pipe.smembers(key)
+          when :sorted_set then pipe.zrange(key, 0, -1, with_scores: true)
+          when :dict       then pipe.hgetall(key)
+          else                  pipe.get(key)
+          end
+        end
+
+        def apply_pipeline_results(order, results)
+          record_by_id = @records.index_by(&:id)
+          order.each_with_index do |(name, id), idx|
+            record_by_id[id]&.public_send(name)&.preload!(results[idx])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class Redis
+  module Objects
+    module Preloadable
+      module RelationExtension
+        def redis_preload(*names)
+          spawn.tap { |r| r.instance_variable_set(:@redis_preload_names, names) }
+        end
+
+        def redis_preload_names
+          @redis_preload_names || []
+        end
+
+        def load
+          result = super
+
+          if !@redis_preload_context_attached && @redis_preload_names&.any? && loaded?
+            @redis_preload_context_attached = true
+            context = PreloadContext.new(records, @redis_preload_names)
+            records.each do |record|
+              @redis_preload_names.each do |name|
+                record.public_send(name).instance_variable_set(:@preload_context, context)
+              end
+            end
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Redis
+  module Objects
+    module Preloadable
+      module TypePatches
+        module Counter
+          def preload!(raw_value)
+            @preloaded_value = raw_value
+          end
+
+          def value
+            @preload_context&.resolve!
+            return @preloaded_value.to_i if defined?(@preloaded_value)
+
+            super
+          end
+
+          def nil?
+            @preload_context&.resolve!
+            return @preloaded_value.nil? if defined?(@preloaded_value)
+
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class Redis
+  module Objects
+    module Preloadable
+      module TypePatches
+        module HashKey
+          def preload!(raw_value)
+            @preloaded_value = raw_value || {}
+          end
+
+          def all
+            @preload_context&.resolve!
+            return @preloaded_value if defined?(@preloaded_value)
+
+            super
+          end
+
+          def [](key)
+            @preload_context&.resolve!
+            return @preloaded_value[key.to_s] if defined?(@preloaded_value)
+
+            super
+          end
+
+          def keys
+            @preload_context&.resolve!
+            return @preloaded_value.keys if defined?(@preloaded_value)
+
+            super
+          end
+
+          def values
+            @preload_context&.resolve!
+            return @preloaded_value.values if defined?(@preloaded_value)
+
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+class Redis
+  module Objects
+    module Preloadable
+      module TypePatches
+        module List
+          def preload!(raw_value)
+            @preloaded_value = raw_value || []
+          end
+
+          def value
+            @preload_context&.resolve!
+            return @preloaded_value if defined?(@preloaded_value)
+
+            super
+          end
+
+          def values
+            value
+          end
+
+          def [](index, length = nil)
+            @preload_context&.resolve!
+            if defined?(@preloaded_value)
+              return length ? @preloaded_value[index, length] : @preloaded_value[index]
+            end
+
+            super
+          end
+
+          def length
+            @preload_context&.resolve!
+            return @preloaded_value.length if defined?(@preloaded_value)
+
+            super
+          end
+
+          def empty?
+            @preload_context&.resolve!
+            return @preloaded_value.empty? if defined?(@preloaded_value)
+
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class Redis
+  module Objects
+    module Preloadable
+      module TypePatches
+        module Set
+          def preload!(raw_value)
+            @preloaded_value = raw_value || []
+          end
+
+          def members
+            @preload_context&.resolve!
+            return @preloaded_value if defined?(@preloaded_value)
+
+            super
+          end
+
+          def include?(member)
+            @preload_context&.resolve!
+            return @preloaded_value.include?(member.to_s) if defined?(@preloaded_value)
+
+            super
+          end
+
+          def length
+            @preload_context&.resolve!
+            return @preloaded_value.length if defined?(@preloaded_value)
+
+            super
+          end
+
+          def empty?
+            @preload_context&.resolve!
+            return @preloaded_value.empty? if defined?(@preloaded_value)
+
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Redis
+  module Objects
+    module Preloadable
+      module TypePatches
+        module SortedSet
+          def preload!(raw_value)
+            @preloaded_value = raw_value || []
+          end
+
+          def members(options = {})
+            @preload_context&.resolve!
+            if defined?(@preloaded_value)
+              return @preloaded_value if options[:with_scores]
+
+              return @preloaded_value.map(&:first)
+            end
+
+            super
+          end
+
+          def score(member)
+            @preload_context&.resolve!
+            if defined?(@preloaded_value)
+              pair = @preloaded_value.find { |m, _| m == member.to_s }
+              return pair&.last
+            end
+
+            super
+          end
+
+          def rank(member)
+            @preload_context&.resolve!
+            return @preloaded_value.index { |m, _| m == member.to_s } if defined?(@preloaded_value)
+
+            super
+          end
+
+          def length
+            @preload_context&.resolve!
+            return @preloaded_value.length if defined?(@preloaded_value)
+
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Redis
+  module Objects
+    module Preloadable
+      module TypePatches
+        module Value
+          def preload!(raw_value)
+            @preloaded_value = raw_value
+          end
+
+          def value
+            @preload_context&.resolve!
+            return @preloaded_value if defined?(@preloaded_value)
+
+            super
+          end
+
+          def nil?
+            @preload_context&.resolve!
+            return @preloaded_value.nil? if defined?(@preloaded_value)
+
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Redis
+  module Objects
+    module Preloadable
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/redis/objects/preloadable.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "redis-objects"
+
+require_relative "preloadable/version"
+require_relative "preloadable/type_patches/counter"
+require_relative "preloadable/type_patches/value"
+require_relative "preloadable/type_patches/list"
+require_relative "preloadable/type_patches/set"
+require_relative "preloadable/type_patches/sorted_set"
+require_relative "preloadable/type_patches/hash_key"
+require_relative "preloadable/preload_context"
+require_relative "preloadable/relation_extension"
+require_relative "preloadable/model_extension"
+
+Redis::Counter.prepend(Redis::Objects::Preloadable::TypePatches::Counter)
+Redis::Value.prepend(Redis::Objects::Preloadable::TypePatches::Value)
+Redis::List.prepend(Redis::Objects::Preloadable::TypePatches::List)
+Redis::Set.prepend(Redis::Objects::Preloadable::TypePatches::Set)
+Redis::SortedSet.prepend(Redis::Objects::Preloadable::TypePatches::SortedSet)
+Redis::HashKey.prepend(Redis::Objects::Preloadable::TypePatches::HashKey)
+
+class Redis
+  module Objects
+    module Preloadable
+      def self.included(base)
+        base.include(ModelExtension)
+      end
+
+      def self.preload(records, *names)
+        records = records.to_a
+        return records if records.empty? || names.empty?
+
+        context = PreloadContext.new(records, names)
+        records.each do |record|
+          names.each do |name|
+            record.public_send(name).instance_variable_set(:@preload_context, context)
+          end
+        end
+        records
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: redis-objects-preloadable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kyohah
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: redis-objects
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: |
+  Provides batch loading (MGET / pipeline) for Redis::Objects attributes on
+  ActiveRecord models, following the same design as ActiveRecord's `preload`.
+  Supports counter, value, list, set, sorted_set, and hash_key types.
+email:
+- 3257272+kyohah@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/redis/objects/preloadable.rb
+- lib/redis/objects/preloadable/model_extension.rb
+- lib/redis/objects/preloadable/preload_context.rb
+- lib/redis/objects/preloadable/relation_extension.rb
+- lib/redis/objects/preloadable/type_patches/counter.rb
+- lib/redis/objects/preloadable/type_patches/hash_key.rb
+- lib/redis/objects/preloadable/type_patches/list.rb
+- lib/redis/objects/preloadable/type_patches/set.rb
+- lib/redis/objects/preloadable/type_patches/sorted_set.rb
+- lib/redis/objects/preloadable/type_patches/value.rb
+- lib/redis/objects/preloadable/version.rb
+homepage: https://github.com/kyohah/redis-objects-preloadable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kyohah/redis-objects-preloadable
+  source_code_uri: https://github.com/kyohah/redis-objects-preloadable
+  changelog_uri: https://github.com/kyohah/redis-objects-preloadable/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.5
+specification_version: 4
+summary: Eliminate N+1 Redis calls for redis-objects in ActiveRecord models
+test_files: []