grape-entity-preloader 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1706cb12b11070d46f62c3b3a4e9aacb797e1aff8659ca4c41d2ee68306b5f1
-  data.tar.gz: 6a060769e40134c573d14b235def6800b931c1fa8b87e84e5d370ce735384e2b
+  metadata.gz: 671275e5b668d11b22c54c7475aa8eb9ec91836a4f35549ed954af02d1e21eda
+  data.tar.gz: edaeb202a4ca0b7d56fec26d6d3fe07ad01b39391096bdfc0f25b4d7fb6f6fd7
 SHA512:
-  metadata.gz: f17b3f692873737c4e9a55e9a971324b77d8263ff08e62cb3d71bee414487e949fe8e76a6d9b088bf2442c4ce266f11041ae7bd3d0394fb236a635f6a8bbb951
-  data.tar.gz: 0e7ba460164dcfad7736f3beb8947c4636d54f954227de6968db5836111171eb8b6b4126fa8348d303f29e15b840e9309c096da04c204a692a434bb419c88cec
+  metadata.gz: 13377f5e77e915f68c9d046fefd0ad109f26e65f0e2af35db5e265e0c3d09f703197b1dfb76bb3f0c64dc0243c7232839a3538d428a9860c0d5139257d69a663
+  data.tar.gz: f6413435b1765b7ac3efbe5fe1960d0cd65c2c7e255eb2e764baccde3d1d242b96b1173435a7f36d694208df8678a973443a990bf462e35d848114277704754c

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [1.0.0] - 2026-08-14 UTC
+
+### Added
+
+- Deduplicate identical preload callbacks.
+- Warn when skipping preloading for exposures with dynamic key or dynamic attr_path.
+
+### Changed
+
+- **Breaking**: Merge `:preload_association`, `:preload_callback`, and `:preload_condition` into a single `:preload` option on exposures. The option now accepts:
+  - a Symbol for an ActiveRecord association (`preload: :books`);
+  - a Proc for a callback (`preload: ->(objects, options) { ... }`);
+  - an Array combining the above with an optional condition Proc (`preload: [:books, ->(options) { ... }]` or `preload: [->(objects, options) { ... }, ->(options) { ... }]`).
+- **Breaking**: Require `preload_callback` Proc to return a Hash mapping each object to its preloaded value, instead of an Array of values. Preloaded values are cached in `options` and reused across exposures at the same nesting level.
+- Defer ActiveRecord version check to runtime.
+
+### Fixed
+
+- Keep consistent `attr_path` for nested exposures when preloader is enabled.
+- Disable preloader during nested entity serialization instead of at root `represent`, preventing duplicate preloads for deferred serialization.
+- Fix cyclic entity references during preload option extraction to avoid infinite recursion.
+
+## [0.3.0] - 2026-03-17 UTC
+
+- Ensure `with_enable` and `with_disable` methods return block result
+
 ## [0.2.0] - 2025-10-14 UTC
 
 - ⚠️ [Broken] Remove `:grape_entity_preloader` option functionality, please use `Grape::Entity::Preloader.with_enable` or `Grape::Entity::Preloader.with_disable` instead.

data/README.md

@@ -47,16 +47,20 @@ Grape::Entity::Preloader.with_disable do
 end
 ```
 
-### `preload_association`
+### `preload`
 
-Use `preload_association` to preload ActiveRecord associations. This helps to avoid N+1 queries when an exposure represents an association.
+Use `preload` to configure preloading for an exposure. It can be a `Symbol` to preload an ActiveRecord association, a `Proc` to run a custom preload callback, or an `Array` with an optional condition.
+
+#### Association preloading
+
+A `Symbol` value preloads the named association:
 
 ```ruby
 class UserEntity < Grape::Entity
   expose :id
   expose :name
   # This will preload the `books` association for all users being represented.
-  expose :books, using: BookEntity, preload_association: :books
+  expose :books, using: BookEntity, preload: :books
 end
 
 # In your API
@@ -74,28 +78,29 @@ class BookEntity < Grape::Entity
   expose :id
   expose :title
   # This will preload tags for each book
-  expose :tags, using: TagEntity, preload_association: :tags
+  expose :tags, using: TagEntity, preload: :tags
 end
 
 class UserEntity < Grape::Entity
   expose :id
   expose :name
-  expose :books, using: BookEntity, preload_association: :books
+  expose :books, using: BookEntity, preload: :books
 end
 
 # It will generate 3 queries instead of 1 + 10 (for books) + N (for tags)
 UserEntity.represent(User.limit(10))
 ```
 
-### `preload_callback`
+#### Custom preloading callback
 
-For more complex scenarios that `preload_association` doesn't cover (e.g., loading data from other services, custom caching logic), you can use `preload_callback`.
+For more complex scenarios that association preloading doesn't cover (e.g., loading data from other services, custom caching logic), you can use a `Proc` that accepts two arguments:
 
-It must be a `Proc` that accepts two arguments:
 1. `objects`: An array of the parent objects being represented.
 2. `options`: The `Grape::Entity::Options` object for the current representation context.
 
-**The `Proc` should return an array of objects that will be used for the nested entity representation. These returned objects will then be passed to the preloader for that nested entity, allowing for further nested preloading.**
+This is the same `objects` / `options` signature used by conditional preloading (see below).
+
+**The `Proc` must return a `Hash` mapping each parent object to its preloaded value.** The preloader stores this Hash in `options` and reads from it when rendering the exposure. If the cache is not available, the exposure fallback to its normal value method (delegation or block).
 
 ```ruby
 class UserStatsEntity < Grape::Entity
@@ -107,36 +112,46 @@ class UserEntity < Grape::Entity
   expose :id
   expose :name
 
-  expose :stats, using: UserStatsEntity, preload_callback: ->(users, _options) do
+  expose :stats, using: UserStatsEntity, preload: ->(users, _options) do
     # `users` is an array of User objects.
     # Here you can fetch stats for all users in one batch.
-    user_ids = users.map(&:id)
-    stats_data = StatsService.batch_get_by_user_ids(user_ids) # returns a hash { user_id => stats_object }
+    stats_by_user_id = StatsService.batch_get_by_user_ids(users.map(&:id))
 
-    # The preloader needs to associate the loaded data back to the original objects.
-    # A common pattern is to attach the data to a new attribute on the object.
-    users.each { |user| user.instance_variable_set(:@stats, stats_data[user.id]) }
-
-    # The block must return the objects that will be presented by the nested entity.
-    # In this case, it's the stats objects we just loaded.
-    users.map { |user| user.instance_variable_get(:@stats) }
+    # Return a Hash mapping each user to its stats object.
+    users.to_h { |user| [user, stats_by_user_id[user.id]] }
+  end do |user, _options|
+    # Fallback when the preloader is disabled.
+    StatsService.get(user.id)
   end
 end
+```
 
-# In the entity, you need to define how to access the preloaded data.
+**Callback deduplication**
+
+When several `expose` declarations need the same preloaded data, reference the same `preload` callback `Proc` for each of them. The preloader will run that callback once, store the resulting Hash in `options`, and reuse it for all of the associated exposures, avoiding duplicate work.
+
+```ruby
 class UserEntity < Grape::Entity
-  # ...
-  expose :stats, using: UserStatsEntity, preload_callback: ... do |user, _options|
-    user.instance_variable_get(:@stats)
+  stats_callback = ->(users, _options) do
+    stats_by_user_id = StatsService.batch_get(users.map(&:id))
+    users.to_h { |user| [user, stats_by_user_id[user.id]] }
+  end
+
+  expose :public_stats, using: StatsEntity, preload: stats_callback do |user, _options|
+    StatsService.get(user.id)
+  end
+
+  expose :private_stats, using: StatsEntity, preload: stats_callback do |user, _options|
+    StatsService.get(user.id)
   end
 end
 ```
 
-### `preload_condition`
+#### Conditional preloading
 
-Use `preload_condition` to conditionally enable or disable preloading for an exposure. It must be a `Proc` that accepts one argument: `options`, which is the `Grape::Entity::Options` object.
+When you need a condition, pass an `Array` where the first element is the preload value and the second element is a `Proc` that accepts one argument: `options`.
 
-If the `Proc` returns a falsy value, preloading for that exposure will be skipped.
+If the condition `Proc` returns a falsy value, preloading for that exposure will be skipped.
 
 ```ruby
 class UserEntity < Grape::Entity
@@ -146,8 +161,7 @@ class UserEntity < Grape::Entity
   # The :audit_log association will only be preloaded if `include_audit_log` is true in the options.
   expose :audit_log,
          using: AuditLogEntity,
-         preload_association: :audit_log,
-         preload_condition: ->(options) { options[:include_audit_log] }
+         preload: [:audit_log, ->(options) { options[:include_audit_log] }]
 end
 
 # Preloading for :audit_log is skipped
@@ -157,6 +171,19 @@ UserEntity.represent(user)
 UserEntity.represent(user, include_audit_log: true)
 ```
 
+For a callback with a condition:
+
+```ruby
+class UserEntity < Grape::Entity
+  expose :stats,
+         using: UserStatsEntity,
+         preload: [
+           ->(users, _options) { StatsService.batch_get(users) },
+           ->(options) { options[:include_stats] }
+         ]
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/grape/entity/preloader/entity.rb

@@ -9,9 +9,8 @@ module Grape
         module ClassMethods # rubocop:disable Style/Documentation
           def represent(objects, options = {})
             options = Grape::Entity::Options.new(options) unless options.is_a?(Grape::Entity::Options)
-
-            Preloader.new(root_exposures, objects, options).call if Preloader.enabled?
-            Preloader.with_disable { super(objects, options) }
+            Preloader.new(self, objects, options).call if Preloader.enabled?
+            super(objects, options)
           end
         end
       end
@@ -21,5 +20,5 @@ end
 
 Grape::Entity.prepend(Grape::Entity::Preloader::Entity)
 silence_warnings do
-  Grape::Entity::OPTIONS = (Grape::Entity::OPTIONS + %i[preload_association preload_callback preload_condition]).freeze
+  Grape::Entity::OPTIONS = (Grape::Entity::OPTIONS + %i[preload]).freeze
 end

data/lib/grape/entity/preloader/exposure.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Grape
+  class Entity
+    class Preloader
+      module Exposure # rubocop:disable Style/Documentation
+        module Base # rubocop:disable Style/Documentation
+          extend ActiveSupport::Concern
+
+          attr_reader :preload
+
+          def initialize(_attribute, options, _conditions)
+            @preload = options[:preload]
+            validate_preload_option!
+
+            super
+          end
+
+          def preload_association
+            case preload
+            when Symbol
+              preload
+            when Array
+              value = preload[0]
+              value.is_a?(Symbol) ? value : nil
+            end
+          end
+
+          def preload_callback
+            case preload
+            when Proc
+              preload
+            when Array
+              value = preload[0]
+              value.is_a?(Proc) ? value : nil
+            end
+          end
+
+          def preload_condition
+            preload.last if preload.is_a?(Array)
+          end
+
+          private
+
+          def validate_preload_option! # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/AbcSize,Metrics/PerceivedComplexity
+            normalized_preload = Array.wrap(preload)
+            return if normalized_preload.empty?
+            raise ArgumentError if normalized_preload.size > 2
+
+            first_value, second_value = normalized_preload
+            raise ArgumentError if !first_value.is_a?(Symbol) && !first_value.is_a?(Proc)
+            raise ArgumentError if first_value.is_a?(Proc) && first_value.arity != 2
+            raise ArgumentError if second_value.is_a?(Proc) && second_value.arity != 1
+          rescue ArgumentError
+            raise ArgumentError, <<~MSG.strip_heredoc
+              The :preload option must be a Symbol, Proc, or Array.
+              - Symbol: :activerecord_association_name
+              - Proc(callback): ->(objects, options) { { object1 => value1, object2 => value2 } }
+                objects: An array of the parent objects being represented.
+                options: The Grape::Entity::Options object for the current representation context.
+                return: A Hash mapping each object to its preloaded value.
+              - Array: [activerecord_association_name, condition_proc] | [callback_proc, condition_proc]
+                condition_proc: ->(options) { ... }
+                  options: The Grape::Entity::Options object for the root representation context.
+                  return: A truthy or falsy value indicating whether preloading should be performed.
+
+              eg:
+                preload: :books
+                preload: ->(objects, options) { ... }
+                preload: [:books, ->(options) { ... }]
+                preload: [->(objects, options) { ... }, ->(options) { ... }]
+            MSG
+          end
+        end
+        ::Grape::Entity::Exposure::Base.prepend(Base)
+
+        module RepresentExposure # rubocop:disable Style/Documentation
+          def value(...)
+            Preloader.with_disable { super }
+          end
+        end
+        ::Grape::Entity::Exposure::RepresentExposure.prepend(RepresentExposure)
+
+        module Value # rubocop:disable Style/Documentation
+          def value(entity, options)
+            cache = options.dig(PRELOAD_CACHE_KEY, preload_callback)
+            cache.is_a?(Hash) ? cache[entity.object] : super
+          end
+
+          # Always return true for preloaded exposures since they are always valid
+          # The actual validation happens in the #value method
+          def valid?(entity)
+            preload_callback ? true : super
+          end
+        end
+        ::Grape::Entity::Exposure::DelegatorExposure.prepend(Value)
+        ::Grape::Entity::Exposure::BlockExposure.prepend(Value)
+        ::Grape::Entity::Exposure::FormatterExposure.prepend(Value)
+        ::Grape::Entity::Exposure::FormatterBlockExposure.prepend(Value)
+      end
+    end
+  end
+end

data/lib/grape/entity/preloader/options.rb

@@ -6,12 +6,32 @@ module Grape
       module Options # rubocop:disable Style/Documentation
         extend ActiveSupport::Concern
 
-        included do
+        prepended do
           def_delegators :opts_hash, :delete, :[]=
         end
+
+        # Grape-Entity builds new Options objects via merge/reverse_merge (e.g.
+        # reverse_merge(collection: true) when representing an array). The
+        # default implementation copies opts_hash but drops @for_nesting_cache,
+        # so nested Options created during preloading (and their populated
+        # PRELOAD_CACHE_KEY caches) are lost before later serialization. Copy the
+        # cache so the same nested Options are reused.
+        def merge(...)
+          super.tap { |options| options.instance_variable_set(:@for_nesting_cache, @for_nesting_cache.dup) }
+        end
+        def reverse_merge(...) # rubocop:disable Layout/EmptyLineBetweenDefs
+          super.tap { |options| options.instance_variable_set(:@for_nesting_cache, @for_nesting_cache.dup) }
+        end
+
+        private
+
+        def build_for_nesting(...)
+          # Clear preload cache for nested entities to avoid sharing cache across nesting levels
+          super.tap { |options| options.opts_hash[PRELOAD_CACHE_KEY] = {} }
+        end
       end
     end
   end
 end
 
-Grape::Entity::Options.include(Grape::Entity::Preloader::Options)
+Grape::Entity::Options.prepend(Grape::Entity::Preloader::Options)

data/lib/grape/entity/preloader/version.rb

@@ -3,7 +3,7 @@
 module Grape
   class Entity
     class Preloader
-      VERSION = '0.2.0'
+      VERSION = '1.0.0'
     end
   end
 end

data/lib/grape/entity/preloader.rb

@@ -4,12 +4,15 @@ require 'grape-entity'
 require_relative 'preloader/version'
 require_relative 'preloader/entity'
 require_relative 'preloader/options'
-require_relative 'preloader/exposure/base'
+require_relative 'preloader/exposure'
 
 module Grape
   class Entity
     class Preloader # rubocop:disable Style/Documentation,Metrics/ClassLength
-      attr_reader :exposures, :objects, :options, :associations, :callbacks, :nested_association_chain
+      STATE_KEY = :grape_entity_preloader
+      PRELOAD_CACHE_KEY = :grape_entity_preload_cache
+
+      attr_reader :entity_class, :objects, :options, :associations, :callbacks, :nested_association_chain
 
       singleton_class.attr_accessor :enabled
       self.enabled = false
@@ -18,63 +21,45 @@ module Grape
         self.enabled = true
       end
 
+      def self.disabled!
+        self.enabled = false
+      end
+
       def self.enabled?
-        if ActiveSupport::IsolatedExecutionState.key?(:grape_entity_preloader)
-          ActiveSupport::IsolatedExecutionState[:grape_entity_preloader]
+        if ActiveSupport::IsolatedExecutionState.key?(STATE_KEY)
+          ActiveSupport::IsolatedExecutionState[STATE_KEY]
         else
           enabled
         end
       end
 
-      def self.with_enable
-        return yield if enabled?
-
-        old_value = ActiveSupport::IsolatedExecutionState[:grape_entity_preloader]
-        ActiveSupport::IsolatedExecutionState[:grape_entity_preloader] = true
-
-        yield
-
-        if old_value.nil?
-          ActiveSupport::IsolatedExecutionState.delete(:grape_entity_preloader)
-        else
-          ActiveSupport::IsolatedExecutionState[:grape_entity_preloader] = old_value
-        end
+      def self.disabled?
+        !enabled?
       end
 
-      def self.disabled!
-        self.enabled = false
+      def self.with_enable(&block)
+        enabled? ? yield : with_state(true, &block)
       end
 
-      def self.disabled?
-        !enabled?
+      def self.with_disable(&block)
+        disabled? ? yield : with_state(false, &block)
       end
 
-      def self.with_disable
-        return yield if disabled?
-
-        old_value = ActiveSupport::IsolatedExecutionState[:grape_entity_preloader]
-        ActiveSupport::IsolatedExecutionState[:grape_entity_preloader] = false
+      def self.with_state(value)
+        old_value = ActiveSupport::IsolatedExecutionState[STATE_KEY]
+        ActiveSupport::IsolatedExecutionState[STATE_KEY] = value
 
         yield
-
+      ensure
         if old_value.nil?
-          ActiveSupport::IsolatedExecutionState.delete(:grape_entity_preloader)
+          ActiveSupport::IsolatedExecutionState.delete(STATE_KEY)
         else
-          ActiveSupport::IsolatedExecutionState[:grape_entity_preloader] = old_value
-        end
-      end
-
-      def self.activerecord_gte_7_0?
-        unless defined?(ActiveRecord) && ActiveRecord.respond_to?(:version) && ActiveRecord.version >= Gem::Version.new('7.0')
-          warn 'ActiveRecord 7.0 or later is required for preload association'
-          return false
+          ActiveSupport::IsolatedExecutionState[STATE_KEY] = old_value
         end
-
-        true
       end
 
-      def initialize(exposures, objects, options)
-        @exposures = exposures
+      def initialize(entity_class, objects, options)
+        @entity_class = entity_class
         @objects = Array.wrap(objects)
         @options = options
 
@@ -86,7 +71,7 @@ module Grape
       def call
         return if objects.empty?
 
-        extract_preload_options(exposures, options, associations)
+        extract_preload_option(entity_class.root_exposures, options, associations, [entity_class])
         execute_preload_associations
         execute_preload_callbacks
       end
@@ -94,72 +79,105 @@ module Grape
       private
 
       def execute_preload_associations
-        return unless Preloader.activerecord_gte_7_0?
         return if associations.empty?
 
         # TODO: Change ActiveRecord async query
         ActiveRecord::Associations::Preloader.new(records: objects, associations: associations).call
+      rescue => e # rubocop:disable Style/RescueStandardError
+        if defined?(ActiveRecord) && ActiveRecord.respond_to?(:version) && ActiveRecord.version >= Gem::Version.new('7.0')
+          raise e
+        end
+
+        raise 'Preloading associations requires ActiveRecord >= 7.0'
       end
 
-      def execute_preload_callbacks # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/CyclomaticComplexity
+      def execute_preload_callbacks # rubocop:disable Metrics/AbcSize,Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
         callbacks.each do |association_chain, exposures_with_options|
           association_objects = association_chain.inject(objects) do |items, association|
             items.filter_map(&association).flatten(1)
           end
           next if association_objects.empty?
 
-          exposures_with_options.each do |exposure, options|
-            callback_objects = exposure.preload_callback.call(association_objects, options)
-            # Dynamic keys are difficult to handle and less used, skipped directly
-            next if !exposure.is_a?(Grape::Entity::Exposure::RepresentExposure) || exposure_with_dynamic_key?(exposure)
-
-            Preloader.new(
-              exposure.using_class.root_exposures,
-              callback_objects,
-              nesting_options(exposure, options)
-            ).call
+          exposures_with_options.group_by { |exposure, _options| exposure.preload_callback }.each do |callback, group|
+            first_options = group.first[1]
+            callback_result = callback.call(association_objects, first_options)
+            unless callback_result.is_a?(Hash)
+              raise ArgumentError, 'The :preload callback must return a Hash mapping objects to their preloaded values.'
+            end
+
+            (first_options[PRELOAD_CACHE_KEY] ||= {})[callback] = callback_result
+
+            group.each do |exposure, nested_options|
+              next unless exposure.is_a?(Grape::Entity::Exposure::RepresentExposure)
+
+              # Dynamic key are difficult to handle and little used, so skip preloading directly.
+              key = exposure.instance_variable_get(:@key)
+              if key.respond_to?(:call)
+                warn "#{entity_class}.#{exposure.attribute} has dynamic key, preloading is not supported"
+                next
+              end
+
+              Preloader.new(
+                exposure.using_class,
+                callback_result.values.flatten(1),
+                nesting_options_for(nested_options, key)
+              ).call
+            end
           end
         end
       end
 
-      def extract_preload_options(exposures, options, associations) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/MethodLength
-        exposures.each do |exposure|
+      def extract_preload_option(exposures, options, associations, visited_entity_classes = []) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/MethodLength
+        exposures.each do |exposure| # rubocop:disable Metrics/BlockLength
+          key = exposure.instance_variable_get(:@key)
+          # Dynamic key or attr_path are difficult to handle and little used, so skip preloading directly.
+          if key.respond_to?(:call)
+            warn "#{entity_class}.#{exposure.attribute} has dynamic key, preloading is not supported"
+            next
+          end
+          if exposure.instance_variable_get(:@attr_path_proc).respond_to?(:call)
+            warn "#{entity_class}.#{exposure.attribute} has dynamic attr_path, preloading is not supported"
+            next
+          end
+
           next unless exposure.should_return_key?(options)
           next if exposure.preload_condition && !exposure.preload_condition.call(options)
 
           if exposure.preload_callback
             callbacks[nested_association_chain.dup] << [exposure, options]
-          elsif exposure.preload_association && Preloader.activerecord_gte_7_0?
+          elsif exposure.preload_association
             associations[exposure.preload_association] ||= {}
           end
 
-          # Dynamic keys are difficult to handle and less used, skipped directly
-          next if exposure_with_dynamic_key?(exposure)
-
           if exposure.is_a?(Grape::Entity::Exposure::NestingExposure)
-            extract_preload_options(
-              exposure.nested_exposures,
-              nesting_options(exposure, options),
-              associations
-            )
+            options.with_attr_path(key) do
+              extract_preload_option(
+                exposure.nested_exposures,
+                nesting_options_for(options, key),
+                associations,
+                visited_entity_classes
+              )
+            end
           elsif exposure.is_a?(Grape::Entity::Exposure::RepresentExposure) && associations[exposure.preload_association]
-            nested_association_chain.push(exposure.preload_association)
-            extract_preload_options(
-              exposure.using_class.root_exposures,
-              nesting_options(exposure, options),
-              associations[exposure.preload_association]
-            )
-            nested_association_chain.pop
+            # Skip cyclic entity references to avoid infinite recursion during preload option extraction.
+            next if visited_entity_classes.include?(exposure.using_class)
+
+            options.with_attr_path(key) do
+              nested_association_chain.push(exposure.preload_association)
+              extract_preload_option(
+                exposure.using_class.root_exposures,
+                nesting_options_for(options, key),
+                associations[exposure.preload_association],
+                visited_entity_classes + [exposure.using_class]
+              )
+              nested_association_chain.pop
+            end
           end
         end
       end
 
-      def nesting_options(exposure, options)
-        options.for_nesting(exposure.instance_variable_get(:@key))
-      end
-
-      def exposure_with_dynamic_key?(exposure)
-        exposure.instance_variable_get(:@key).respond_to?(:call)
+      def nesting_options_for(options, key)
+        key ? options.for_nesting(key) : options
       end
     end
   end

data/spec/grape/entity/preloader_spec.rb

@@ -4,4 +4,231 @@ RSpec.describe Grape::Entity::Preloader do
   it 'has a version number' do
     expect(Grape::Entity::Preloader::VERSION).not_to be_nil
   end
+
+  describe '.with_enable' do
+    it 'returns the value of the block' do
+      result = described_class.with_enable { 42 }
+      expect(result).to eq(42)
+    end
+
+    it 'returns the value of the block when already enabled' do
+      described_class.enabled!
+      result = described_class.with_enable { 'hello' }
+      expect(result).to eq('hello')
+    ensure
+      described_class.disabled!
+    end
+  end
+
+  describe '.with_disable' do
+    it 'returns the value of the block' do
+      result = described_class.with_disable { 42 }
+      expect(result).to eq(42)
+    end
+
+    it 'returns the value of the block when already disabled' do
+      described_class.disabled!
+      result = described_class.with_disable { 'hello' }
+      expect(result).to eq('hello')
+    end
+  end
+
+  describe 'nested exposure options' do
+    def entity_class(paths)
+      Class.new(Grape::Entity) do
+        expose :a
+        expose :embed do
+          expose :b do |obj, options|
+            paths << options[:attr_path].dup
+            obj[:b]
+          end
+        end
+      end
+    end
+
+    it 'keeps correct attr_path when preloader is disabled' do
+      paths = []
+      described_class.with_disable { entity_class(paths).represent({ a: 1, b: 2 }, serializable: true) }
+      expect(paths).to eq([%i[embed b]])
+    end
+
+    it 'keeps correct attr_path when preloader is enabled' do
+      paths = []
+      described_class.with_enable { entity_class(paths).represent({ a: 1, b: 2 }, serializable: true) }
+      expect(paths).to eq([%i[embed b]])
+    end
+
+    it 'provides the same attr_path regardless of preloader state' do
+      paths = { disabled: [], enabled: [] }
+      described_class.with_disable { entity_class(paths[:disabled]).represent({ a: 1, b: 2 }, serializable: true) }
+      described_class.with_enable { entity_class(paths[:enabled]).represent({ a: 1, b: 2 }, serializable: true) }
+      expect(paths[:disabled]).to eq(paths[:enabled])
+      expect(paths[:enabled]).to eq([%i[embed b]])
+    end
+
+    it 'keeps correct attr_path when as_json is called after serializable: false with arrays' do
+      paths = []
+      described_class.with_enable { entity_class(paths).represent([{ a: 1, b: 2 }], serializable: false).as_json }
+      expect(paths).to eq([%i[embed b]])
+    end
+  end
+
+  describe 'preload callback deduplication' do
+    it 'only calls the same callback once for multiple exposures' do
+      calls = []
+      item_class = Struct.new(:id)
+
+      callback = lambda do |objects, _options|
+        calls << objects
+        objects.to_h { |obj| [obj, { value: obj.id }] }
+      end
+
+      child_entity = Class.new(Grape::Entity) do
+        expose :value
+      end
+
+      parent_entity = Class.new(Grape::Entity) do
+        expose :foo, using: child_entity, preload: callback do |obj, _options|
+          { value: obj.id }
+        end
+
+        expose :bar, using: child_entity, preload: callback do |obj, _options|
+          { value: obj.id }
+        end
+      end
+
+      objects = [item_class.new(1), item_class.new(2)]
+      described_class.with_enable { parent_entity.represent(objects) }
+
+      expect(calls.size).to eq(1)
+      expect(calls.first).to eq(objects)
+    end
+  end
+
+  describe 'preload cache isolation across nesting levels' do
+    it 'does not share parent cache with nested cache for the same object and callback' do
+      item_class = Struct.new(:id, :child)
+      calls = []
+      callback = lambda do |objects, _options|
+        call_index = calls.size
+        calls.concat(objects)
+        objects.to_h { |obj| [obj, { call_index: call_index }] }
+      end
+
+      child_entity = Class.new(Grape::Entity) do
+        expose :id
+        expose :meta, preload: callback
+      end
+
+      parent_entity = Class.new(Grape::Entity) do
+        expose :id
+        expose :meta, preload: callback
+        expose :child, using: child_entity, preload: ->(objects, _options) { objects.to_h { |obj| [obj, obj.child] } }
+      end
+
+      parent = item_class.new(1, nil)
+      parent.child = parent
+
+      result = described_class.with_enable { parent_entity.represent(parent, serializable: true) }
+
+      expect(calls.size).to eq(2)
+      expect(result[:meta]).to eq({ call_index: 0 })
+      expect(result[:child][:meta]).to eq({ call_index: 1 })
+    end
+  end
+
+  describe 'circular entity references' do
+    it 'does not recurse infinitely when extracting preload options for mutually referencing entities' do
+      item_class = Struct.new(:id, :child, :parent)
+
+      child_entity = Class.new(Grape::Entity)
+      parent_entity = Class.new(Grape::Entity) do
+        expose :id
+        expose :child, using: child_entity, preload: :child
+      end
+      child_entity.class_eval do
+        expose :id
+        expose :parent, using: parent_entity, preload: :parent
+      end
+
+      parent = item_class.new(1, nil, nil)
+      child = item_class.new(2, nil, parent)
+      parent.child = child
+
+      options = Grape::Entity::Options.new({})
+      preloader = described_class.new(parent_entity, [parent], options)
+
+      expect do
+        preloader.send(
+          :extract_preload_option,
+          parent_entity.root_exposures,
+          options,
+          {},
+          [parent_entity]
+        )
+      end.not_to raise_error
+    end
+  end
+
+  describe 'deferred serialization with serializable: false' do
+    it 'does not preload nested exposures twice when as_json is called later' do
+      item_class = Struct.new(:id, :child)
+      calls = []
+      callback = lambda do |objects, _options|
+        call_index = calls.size
+        calls.concat(objects)
+        objects.to_h { |obj| [obj, { call_index: call_index }] }
+      end
+
+      child_entity = Class.new(Grape::Entity) do
+        expose :id
+        expose :meta, preload: callback
+      end
+
+      parent_entity = Class.new(Grape::Entity) do
+        expose :id
+        expose :meta, preload: callback
+        expose :child, using: child_entity, preload: ->(objects, _options) { objects.to_h { |obj| [obj, obj.child] } }
+      end
+
+      parent = item_class.new(1, nil)
+      parent.child = parent
+
+      result = described_class.with_enable { parent_entity.represent(parent, serializable: false).as_json }
+
+      expect(calls.size).to eq(2)
+      expect(result[:meta]).to eq({ call_index: 0 })
+      expect(result[:child][:meta]).to eq({ call_index: 1 })
+    end
+
+    it 'keeps nested preload cache when as_json is called after serializable: false with arrays' do
+      item_class = Struct.new(:id, :child)
+      calls = []
+      callback = lambda do |objects, _options|
+        call_index = calls.size
+        calls.concat(objects)
+        objects.to_h { |obj| [obj, { call_index: call_index }] }
+      end
+
+      child_entity = Class.new(Grape::Entity) do
+        expose :id
+        expose :meta, preload: callback
+      end
+
+      parent_entity = Class.new(Grape::Entity) do
+        expose :id
+        expose :meta, preload: callback
+        expose :child, using: child_entity, preload: ->(objects, _options) { objects.to_h { |obj| [obj, obj.child] } }
+      end
+
+      parent = item_class.new(1, nil)
+      parent.child = parent
+
+      result = described_class.with_enable { parent_entity.represent([parent], serializable: false).as_json }
+
+      expect(calls.size).to eq(2)
+      expect(result.first[:meta]).to eq({ call_index: 0 })
+      expect(result.first[:child][:meta]).to eq({ call_index: 1 })
+    end
+  end
 end

data/spec/n_plus_one_op_spec.rb

@@ -30,7 +30,7 @@ RSpec.describe 'N+1 operation' do # rubocop:disable RSpec/DescribeClass
         expect(Grape::Entity::Preloader.enabled?).to be(true)
 
         expect do
-          Book::Entity.represent(books, serializable: true, only: [:tags_by_association])
+          Book::Entity.represent(books, only: [:tags_by_association])
         end.to make_database_queries(count: 1)
            .and make_database_queries(
              count: 1,
@@ -43,7 +43,7 @@ RSpec.describe 'N+1 operation' do # rubocop:disable RSpec/DescribeClass
           expect(Grape::Entity::Preloader.enabled?).to be(true)
 
           expect do
-            Book::Entity.represent(books, serializable: true, only: [:tags_by_association])
+            Book::Entity.represent(books, only: [:tags_by_association])
           end.to make_database_queries(count: 1)
              .and make_database_queries(
                count: 1,
@@ -95,7 +95,7 @@ RSpec.describe 'N+1 operation' do # rubocop:disable RSpec/DescribeClass
       it 'single' do
         books = Book.all.load
         expect do
-          Book::Entity.represent(books, serializable: true, only: %i[tags_by_association])
+          Book::Entity.represent(books, only: %i[tags_by_association])
         end.to make_database_queries(count: 1)
           .and make_database_queries(count: 1, matching: /book_tags_by_association/)
       end
@@ -104,8 +104,7 @@ RSpec.describe 'N+1 operation' do # rubocop:disable RSpec/DescribeClass
         expect do
           User::Entity.represent(
             users,
-            serializable: true,
-            only: [books_by_association: %i[tags_by_association tags_by_callback]]
+            only: [{ books_by_association: %i[tags_by_association tags_by_callback] }]
           )
         end.to make_database_queries(count: 3)
           .and make_database_queries(count: 1, matching: /user_books_by_association/)
@@ -113,9 +112,8 @@ RSpec.describe 'N+1 operation' do # rubocop:disable RSpec/DescribeClass
           .and make_database_queries(count: 1, matching: /book_tags_by_callback/)
       end
 
-      it 'same preload_association(single preload_association after nested preload_association)' do
+      it 'same preload (single association after nested association)' do
         options = {
-          serializable: true,
           expose_books_count_by_association: true,
           only: %i[books_count_by_association]
         }
@@ -139,7 +137,7 @@ RSpec.describe 'N+1 operation' do # rubocop:disable RSpec/DescribeClass
     describe 'callback' do
       it 'single' do
         expect do
-          Book::Entity.represent(books, serializable: true, only: %i[tags_by_callback])
+          Book::Entity.represent(books, only: %i[tags_by_callback])
         end.to make_database_queries(count: 1)
           .and make_database_queries(count: 1, matching: /book_tags_by_callback/)
       end
@@ -148,8 +146,7 @@ RSpec.describe 'N+1 operation' do # rubocop:disable RSpec/DescribeClass
         expect do
           User::Entity.represent(
             users,
-            serializable: true,
-            only: [books_by_callback: %i[tags_by_association tags_by_callback]]
+            only: [{ books_by_callback: %i[tags_by_association tags_by_callback] }]
           )
         end.to make_database_queries(count: 3)
           .and make_database_queries(count: 1, matching: /books_by_callback/)
@@ -163,7 +160,6 @@ RSpec.describe 'N+1 operation' do # rubocop:disable RSpec/DescribeClass
         expect do
           Book::Entity.represent(
             books,
-            serializable: true,
             expose_book_tags_count_by_association: true,
             only: %i[tags_count_by_association]
           )
@@ -183,5 +179,19 @@ RSpec.describe 'N+1 operation' do # rubocop:disable RSpec/DescribeClass
           .and make_database_queries(count: 2, matching: /book_tags_by_association/)
       end
     end
+
+    describe 'deferred serialization' do
+      it 'preloads nested callbacks when as_json is called after serializable: false' do
+        expect do
+          User::Entity.represent(
+            users,
+            serializable: false,
+            only: [{ books_by_association: %i[tags_by_callback] }]
+          ).as_json
+        end.to make_database_queries(count: 2)
+          .and make_database_queries(count: 1, matching: /user_books_by_association/)
+          .and make_database_queries(count: 1, matching: /book_tags_by_callback/)
+      end
+    end
   end
 end

data/spec/support/models/book.rb

@@ -16,29 +16,29 @@ class Book < ApplicationRecord
 
   entity do
     expose :name
-    expose :tags_by_association, using: 'Tag::Entity', preload_association: :tags_by_association
-    expose :tags_by_callback, using: 'Tag::Entity', preload_callback: lambda { |objects, _options|
+    expose :tags_by_association, using: 'Tag::Entity', preload: :tags_by_association
+    expose :tags_by_callback, using: 'Tag::Entity', preload: lambda { |objects, _options|
       ActiveRecord::Associations::Preloader.new(
         records: objects,
         associations: :tags_by_callback
-      ).call.first.preloaded_records
+      ).call
+      objects.to_h { |object| [object, object.tags_by_callback] }
     }
-    expose :tags_count_by_association, preload_association: :tags_by_association,
-                                       preload_condition: ->(options) { options[:expose_book_tags_count_by_association] } # rubocop:disable Layout/LineLength
-    expose :tags_count_by_callback, preload_condition: ->(options) { options[:expose_book_tags_count_by_callback] },
-                                    preload_callback: lambda { |objects, _options|
-                                      ActiveRecord::Associations::Preloader.new(
-                                        records: objects,
-                                        associations: :tags_by_callback
-                                      ).call.first.preloaded_records
-                                    }
-
-    def tags_count_by_association
+    expose :tags_count_by_association, preload: [
+      :tags_by_association,
+      ->(options) { options[:expose_book_tags_count_by_association] }
+    ] do |object, _options|
       object.tags_by_association.size
     end
-
-    def tags_count_by_callback
-      object.tags_by_callback.size
-    end
+    expose :tags_count_by_callback, preload: [
+      lambda { |objects, _options|
+        ActiveRecord::Associations::Preloader.new(
+          records: objects,
+          associations: :tags_by_callback
+        ).call
+        objects.to_h { |object| [object, object.tags_by_callback.size] }
+      },
+      ->(options) { options[:expose_book_tags_count_by_callback] }
+    ]
   end
 end

data/spec/support/models/user.rb

@@ -20,54 +20,54 @@ class User < ApplicationRecord
   entity do
     expose :name
 
-    expose :books_by_association, using: 'Book::Entity', preload_association: :books_by_association
-    expose :books_by_callback, using: 'Book::Entity', preload_callback: lambda { |objects, _options|
+    expose :books_by_association, using: 'Book::Entity', preload: :books_by_association
+    expose :books_by_callback, using: 'Book::Entity', preload: lambda { |objects, _options|
       ActiveRecord::Associations::Preloader.new(
         records: objects,
         associations: :books_by_callback
-      ).call.first.preloaded_records
+      ).call
+      objects.to_h { |object| [object, object.books_by_callback] }
     }
-    expose :books_count_by_association, preload_association: :books_by_association,
-                                        preload_condition: ->(options) { options[:expose_books_count_by_association] }
-    expose :books_count_by_callback, preload_condition: ->(options) { options[:expose_books_count_by_callback] },
-                                     preload_callback: lambda { |objects, _options|
-                                       ActiveRecord::Associations::Preloader.new(
-                                         records: objects,
-                                         associations: :books_by_callback
-                                       ).call.first.preloaded_records
-                                     }
+    expose :books_count_by_association, preload: [
+      :books_by_association,
+      ->(options) { options[:expose_books_count_by_association] }
+    ] do |object, _options|
+      object.books_by_association.size
+    end
+    expose :books_count_by_callback, preload: [
+      lambda { |objects, _options|
+        ActiveRecord::Associations::Preloader.new(
+          records: objects,
+          associations: :books_by_callback
+        ).call
+        objects.to_h { |object| [object, object.books_by_callback.size] }
+      },
+      ->(options) { options[:expose_books_count_by_callback] }
+    ]
 
-    expose :tags_by_association, using: 'Tag::Entity', preload_association: :tags_by_association
-    expose :tags_by_callback, using: 'Tag::Entity', preload_callback: lambda { |objects, _options|
+    expose :tags_by_association, using: 'Tag::Entity', preload: :tags_by_association
+    expose :tags_by_callback, using: 'Tag::Entity', preload: lambda { |objects, _options|
       ActiveRecord::Associations::Preloader.new(
         records: objects,
         associations: :tags_by_callback
-      ).call.first.preloaded_records
+      ).call
+      objects.to_h { |object| [object, object.tags_by_callback] }
     }
-    expose :tags_count_by_association, preload_association: :tags_by_association,
-                                       preload_condition: ->(options) { options[:expose_user_tags_count_by_association] } # rubocop:disable Layout/LineLength
-    expose :tags_count_by_callback, preload_condition: ->(options) { options[:expose_user_tags_count_by_callback] },
-                                    preload_callback: lambda { |objects, _options|
-                                      ActiveRecord::Associations::Preloader.new(
-                                        records: objects,
-                                        associations: :tags_by_callback
-                                      ).call.first.preloaded_records
-                                    }
-
-    def books_count_by_association
-      object.books_by_association.size
-    end
-
-    def books_count_by_callback
-      object.books_by_callback.size
-    end
-
-    def tags_count_by_association
+    expose :tags_count_by_association, preload: [
+      :tags_by_association,
+      ->(options) { options[:expose_user_tags_count_by_association] }
+    ] do |object, _options|
       object.tags_by_association.size
     end
-
-    def tags_count_by_callback
-      object.tags_by_callback.size
-    end
+    expose :tags_count_by_callback, preload: [
+      lambda { |objects, _options|
+        ActiveRecord::Associations::Preloader.new(
+          records: objects,
+          associations: :tags_by_callback
+        ).call
+        objects.to_h { |object| [object, object.tags_by_callback.size] }
+      },
+      ->(options) { options[:expose_user_tags_count_by_callback] }
+    ]
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grape-entity-preloader
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - OuYangJinTing
@@ -39,7 +39,7 @@ files:
 - Rakefile
 - lib/grape/entity/preloader.rb
 - lib/grape/entity/preloader/entity.rb
-- lib/grape/entity/preloader/exposure/base.rb
+- lib/grape/entity/preloader/exposure.rb
 - lib/grape/entity/preloader/options.rb
 - lib/grape/entity/preloader/version.rb
 - sig/grape/entity/preloader.rbs
@@ -71,7 +71,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Grape::Entity::Preloader allows preload associations and callbacks for avoiding
   N+1 operations in Grape::Entity.

data/lib/grape/entity/preloader/exposure/base.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module Grape
-  class Entity
-    class Preloader
-      module Exposure
-        module Base # rubocop:disable Style/Documentation
-          extend ActiveSupport::Concern
-
-          attr_reader :preload_association, :preload_callback, :preload_condition
-
-          def initialize(_attribute, options, _conditions)
-            @preload_association = options[:preload_association]
-            @preload_callback = options[:preload_callback]
-            @preload_condition = options[:preload_condition]
-            validate_preload_options
-
-            super
-          end
-
-          private
-
-          def validate_preload_options # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/MethodLength
-            if preload_association && !preload_association.is_a?(Symbol)
-              raise ArgumentError, 'The :preload_association option must be a Symbol.'
-            end
-
-            if preload_callback && (!preload_callback.is_a?(Proc) || preload_callback.arity != 2)
-              raise ArgumentError, 'The :preload_callback option must be a Proc with 2 arguments.'
-            end
-
-            if preload_condition && (!preload_condition.is_a?(Proc) || preload_condition.arity != 1)
-              raise ArgumentError, 'The :preload_condition option must be a Proc with 1 argument.'
-            end
-
-            return unless preload_association && preload_callback
-
-            raise ArgumentError, 'The :preload_association and :preload_callback options cannot be used together.'
-          end
-        end
-      end
-    end
-  end
-end
-
-Grape::Entity::Exposure::Base.prepend(Grape::Entity::Preloader::Exposure::Base)