serega 0.37.1 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca01b1c5668c5ce5963e5f2b71540dae1d023eed44c6e9e026d43e63fcead4c6
-  data.tar.gz: f526d737921efe1789751b51ff15b503b0febe2d5aafbb1a57666625a14b2228
+  metadata.gz: 384da177845e2385a0100d23147cea0034860b148cd46738dc3d6ec7ea7d7eda
+  data.tar.gz: f08d482a83cb0cde30ae4c03e924f50be6aaabea24d76564bc47a7a1eadf4f98
 SHA512:
-  metadata.gz: 643c12f65a16dbce5d05a8262df0f85fc6a5055436a65d2590f0615ccba5a9cb2d1287d4ec1262b9d0f252432262e88799b55d13ca7ce5fed252c58faf9b7a1a
-  data.tar.gz: fa8ad847f04617c8ea70cf227aca9bf9ede02c1b1449afb6547b821f09cd8a27638cb5d8904ddc576dfe12c01d5cd6991a99e7cb9fa1cf28d46d2053c7650978
+  metadata.gz: c9f2f95d8a74ce4951f7acef89a1cf603fcba2f15af50d246f85d58e1456b06c03b749fef620c741f8e2482999c6f7471fb5dff9a904b275f79f039999ab7fdc
+  data.tar.gz: 69c1b8f898f81317310e875a8771db096b3d4613b34769024d66fe801554e53094fd59e3cfea923ef81bb5d837a31ef28ceadc825003c95a4a2340f6b0b0bf74

data/VERSION

@@ -1 +1 @@
-0.37.1
+0.38.0

data/lib/serega/attribute_normalizer.rb

@@ -9,10 +9,6 @@ class Serega
     # AttributeNormalizer instance methods
     #
     module AttributeNormalizerInstanceMethods
-      # Identity loader that routes relation/preload attributes through the batch
-      # mechanism. Its result is never read — the attribute's value block still
-      # computes the value.
-      AUTO_BATCH_LOADER = proc { |records| records.to_h { |record| [record, record] } }
       # Attribute initial params
       # @return [Hash] Attribute initial params
       attr_reader :init_name, :init_opts, :init_block
@@ -113,9 +109,9 @@ class Serega
       end
 
       #
-      # Shows normalized preloads for current attribute
+      # Preloads declared for this attribute, passed through as provided.
       #
-      # @return [Hash, nil] normalized preloads of current attribute
+      # @return [Object, nil] declared preloads, or nil when the attribute has none
       #
       def preloads
         return @preloads if instance_variable_defined?(:@preloads)
@@ -152,13 +148,24 @@ class Serega
 
         hide_setting = config.hide_by_default
         return true if hide_setting == true
-        return true if hide_setting == :auto && (preloads || init_opts.key?(:batch))
+        return true if hide_setting == :auto && preload_or_batch?
 
         # Return nil for undefined value which means "not hide" but allows
         # to change this value by plugins
         nil
       end
 
+      # The `hide_by_default = :auto` criterion: hide attributes that fetch extra
+      # data on demand — those declared with `:preload` or an explicit `:batch`.
+      #
+      # This is intentionally narrower than a "goes through the batch mechanism"
+      # check (`SeregaPlanPoint#batch?`): a plain relation (`serializer:` without
+      # `:preload`) is batch-processed too, but it only serializes an already-loaded
+      # nested object, so it stays visible by default.
+      def preload_or_batch?
+        !!(preloads || init_opts.key?(:batch))
+      end
+
       def config
         self.class.serializer_class.config
       end
@@ -192,14 +199,14 @@ class Serega
         AttributeValueResolvers::BatchResolver.get(self.class.serializer_class, name, batch_opt)
       end
 
+      # Batch loader names whose loaded data this attribute's value needs. Only
+      # explicit `:batch` attributes have any — everything else resolves its value
+      # from the record itself, so the list is empty (no loader to run).
       def prepare_batch_loaders
         batch_opt = init_opts[:batch]
         return explicit_batch_loaders(batch_opt) if batch_opt
-        return FROZEN_EMPTY_ARRAY unless serializer || preloads
 
-        loader_name = :"__auto_batch_#{name}__"
-        self.class.serializer_class.batch(loader_name, AUTO_BATCH_LOADER)
-        [loader_name]
+        FROZEN_EMPTY_ARRAY
       end
 
       def explicit_batch_loaders(batch_opt)

data/lib/serega/engine/level.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Batch feature main module
+  #
+  module SeregaEngine
+    #
+    # One serialization level: all objects serialized under a single plan and the
+    # result containers they fill. Objects from different parents that share a plan
+    # (e.g. every user's posts) accumulate into one level, so a named batch loader
+    # or preload runs once over the whole set. A deeper level (its own plan) loads
+    # separately.
+    #
+    class Level
+      # @param serializer [SeregaObjectSerializer] serializer that resolves this level
+      def initialize(serializer)
+        @serializer = serializer
+        @objects = []
+        @containers = []
+        @results = {}.compare_by_identity
+      end
+
+      # @return [Array] Objects serialized at this level
+      attr_reader :objects
+
+      # @return [Array<Hash>] Result container per object (filled in place)
+      attr_reader :containers
+
+      # Accumulates a chunk of objects into this level, creating one empty result
+      # container per object. The containers are returned so the caller can hand
+      # them to its parent; they are filled in place later during #process.
+      #
+      # @param objects [Array] objects serialized at this level
+      # @return [Array<Hash>] the created containers, aligned with objects
+      def add(objects)
+        containers = Array.new(objects.size) { {} }
+        @objects.concat(objects)
+        @containers.concat(containers)
+        containers
+      end
+
+      # Resolves every attribute of this level onto the containers.
+      # @return [void]
+      def process
+        @serializer.process(self)
+      end
+
+      # Loads a named batch loader once for this level's objects.
+      # @param loader [SeregaEngine::Loader] Named batch loader
+      # @return [Object] Loaded values
+      def fetch(loader)
+        @results[loader] ||= loader.load(@objects, @serializer.context)
+      end
+    end
+  end
+end

data/lib/serega/engine/level_queue.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Batch feature main module
+  #
+  module SeregaEngine
+    #
+    # Level-order queue of serialization levels for one serialization run.
+    #
+    # `#serialize` on the object serializer enqueues a level (objects + their result
+    # containers) instead of resolving values inline. `#run` then processes the
+    # queue: each level resolves its attributes and, for relations, enqueues child
+    # levels — which the loop picks up because it re-reads the size each iteration.
+    # Processing level-by-level lets a named batch loader and preloads run once per
+    # level over all of its objects.
+    #
+    class LevelQueue
+      def initialize
+        @levels = []
+        @levels_by_plan = {}.compare_by_identity
+      end
+
+      # Adds objects to the level for their plan (creating it on first use), so
+      # objects serialized under the same plan — even from different parents —
+      # share one level and load once. The level creates a result container per
+      # object and returns them for the caller to embed in its parent.
+      #
+      # @param serializer [SeregaObjectSerializer] serializer that resolves the level
+      # @param objects [Array] objects serialized at this level
+      #
+      # @return [Array<Hash>] the created result containers, aligned with objects
+      def enqueue(serializer, objects)
+        level = @levels_by_plan[serializer.plan]
+        unless level
+          level = Level.new(serializer)
+          @levels_by_plan[serializer.plan] = level
+          @levels << level
+        end
+        level.add(objects)
+      end
+
+      # Processes every level, including child levels enqueued while processing.
+      # @return [void]
+      def run
+        i = 0
+        while i < @levels.size
+          @levels[i].process
+          i += 1
+        end
+      end
+    end
+  end
+end

data/lib/serega/{batch → engine}/loader.rb

@@ -4,7 +4,7 @@ class Serega
   #
   # Batch feature main module
   #
-  module SeregaBatch
+  module SeregaEngine
     #
     #  Batch loader
     #

data/lib/serega/object_serializer.rb

@@ -2,15 +2,19 @@
 
 class Serega
   #
-  # Low-level class that is used by more high-level SeregaSerializer
-  # to construct serialized to hash response
+  # Low-level class used by the serializer to construct the serialized response.
+  #
+  # Serialization is level-by-level. `#serialize` builds the result container(s)
+  # and enqueues this level; the batch queue later calls `#process` for each level,
+  # which resolves every attribute for every object and enqueues child levels for
+  # relations.
   #
   class SeregaObjectSerializer
     #
     # SeregaObjectSerializer instance methods
     #
     module InstanceMethods
-      attr_reader :context, :plan, :many, :opts, :batch_loaders
+      attr_reader :context, :plan, :many, :opts, :level_queue
 
       # @param plan [SeregaPlan] Serialization plan
       # @param context [Hash] Serialization context
@@ -23,92 +27,86 @@ class Serega
         @plan = plan
         @many = many
         @opts = opts
-        @batch_loaders = opts[:batch_loaders]
+        @level_queue = opts[:level_queue]
       end
 
-      # Serializes object(s)
+      # Enqueues this level and returns its result container(s). The containers are
+      # returned immediately but filled in place once the queue is processed.
       #
-      # @param object [Object] Serialized object
+      # @param object [Object] Serialized object(s)
       #
       # @return [Hash, Array<Hash>, nil] Serialized object(s)
       def serialize(object)
         return if object.nil?
 
-        if array?(object, many)
-          batch_loaders.add_objects(plan, object.to_a) if plan.batch?
-          serialize_array(object)
-        else
-          batch_loaders.add_objects(plan, [object]) if plan.batch?
-          serialize_object(object)
+        case serialize_mode(object)
+        when :many then enqueue(object.to_a)
+        when :many_for_one then enqueue([object]) # `many` on, but a sole object was given — wrap it, don't raise
+        else enqueue([object])[0] # :one
         end
       end
 
-      private
-
-      def serialize_array(objects)
-        objects.map { |object| serialize_object(object) }
-      end
-
-      # Patched in:
-      # - plugin :presenter (makes presenter_object and serializes it)
-      def serialize_object(object)
-        plan.points.each_with_object({}) do |point, container|
-          serialize_point(object, point, container)
-        rescue => error
-          reraise_with_serialized_attribute_details(error, point)
+      # Resolves every attribute of one level onto its containers. For each point,
+      # preloads and batch loaders run once over all of the level's objects; the
+      # value is then resolved and assigned per object, in attribute order.
+      #
+      # @param level [SeregaEngine::Level] level to resolve
+      # @return [void]
+      def process(level)
+        objects = level.objects
+
+        plan.points.each do |point|
+          point.run_preloads(objects)
+          batches = point.load_batches(level)
+          # One child serializer per relation point per level (reused for every object),
+          # instead of one per object — child objects are grouped into one child level anyway.
+          child_serializer = point.child_serializer(context: context, **opts)
+
+          objects.each_with_index do |object, index|
+            resolve_point(object, point, level.containers[index], batches, child_serializer)
+          rescue => error
+            SeregaUtils::SerializedAttributeError.call(error, point)
+          end
         end
       end
 
+      private
+
+      # Enqueues this chunk of objects onto the queue and returns their result
+      # containers. This is where objects enter their level, so every object a
+      # point resolves against and a batch loader receives has the same shape.
+      #
       # Patched in:
-      # - plugin :if (conditionally skips serializing this point)
-      def serialize_point(object, point, container)
-        if point.batch?
-          attacher = lambda { |obj, batches| attach_value(obj, point, container, batches: batches) }
-          batch_loaders.remember(point, object, attacher)
-          container[point.name] = nil # Reserve attribute place in resulted hash. We will set correct value later
-        else
-          attach_value(object, point, container, batches: nil)
-        end
+      # - plugin :presenter (wraps each object in a Presenter before enqueueing)
+      def enqueue(objects)
+        level_queue.enqueue(self, objects)
       end
 
-      def attach_value(object, point, container, batches: nil)
+      # Patched in:
+      # - plugin :if (skips the point for objects failing an :if/:unless condition)
+      def resolve_point(object, point, container, batches, child_serializer)
         value = point.value(object, context, batches: batches)
-        final_value = final_value(value, point)
-        attach_final_value(final_value, point, container)
+        final_value = child_serializer ? child_serializer.serialize(value) : value
+        write_value(final_value, point, container)
       end
 
       # Patched in:
-      # - plugin :if (conditionally skips attaching)
-      def attach_final_value(final_value, point, container)
+      # - plugin :if (skips assigning when an :if_value/:unless_value condition fails)
+      def write_value(final_value, point, container)
         container[point.name] = final_value
       end
 
-      def final_value(value, point)
-        point.child_plan ? relation_value(value, point) : value
-      end
-
-      def relation_value(value, point)
-        child_serializer(point).serialize(value)
-      end
-
-      def child_serializer(point)
-        point.child_object_serializer.new(
-          context: context,
-          plan: point.child_plan,
-          many: point.many,
-          **opts
-        )
-      end
-
-      def array?(object, many)
-        many.nil? ? object.is_a?(Enumerable) : many
-      end
-
-      def reraise_with_serialized_attribute_details(error, point)
-        raise error.exception(<<~MESSAGE.strip)
-          #{error.message}
-          (when serializing '#{point.name}' attribute in #{self.class.serializer_class})
-        MESSAGE
+      # How to serialize `object`, deciding whether the result is a collection or a
+      # single object and reading `Enumerable` only once:
+      # - :many         — `many` is on and the object is a collection
+      # - :many_for_one — `many` is on but a sole object was given (wrap it, don't raise)
+      # - :one          — serialize the object on its own
+      def serialize_mode(object)
+        case many
+        when NilClass then object.is_a?(Enumerable) ? :many : :one
+        when TrueClass then object.is_a?(Enumerable) ? :many : :many_for_one
+        else :one # many == false
+        end
       end
     end
 

data/lib/serega/plan.rb

@@ -108,15 +108,6 @@ class Serega
         self.class.serializer_class
       end
 
-      #
-      # @return [Boolean] whether any point of this plan is batch loaded
-      #
-      def batch?
-        return @batch if defined?(@batch)
-
-        @batch = points.any?(&:batch?)
-      end
-
       # Returns the Data class whose members match this plan's serialized fields.
       # Delegates to the class-level cache so identical field sets share one Data class.
       #

data/lib/serega/plan_point.rb

@@ -68,23 +68,74 @@ class Serega
         attribute.serializer
       end
 
-      def batch?
-        !attribute.batch_loaders.empty?
-      end
-
       # Attribute `batch_loaders`
       # @see SeregaAttribute::AttributeInstanceMethods#batch_loaders
       def batch_loaders
         attribute.batch_loaders
       end
 
+      # Attribute `preloads`
+      # @see SeregaAttribute::AttributeInstanceMethods#preloads
+      def preloads
+        attribute.preloads
+      end
+
+      # Runs this point's declared preloads over the given objects using the
+      # serializer's registered preload handler.
+      #
+      # @param objects [Array] objects serialized at this point's level
+      # @return [void]
+      def run_preloads(objects)
+        return unless preloads
+
+        handler = self.class.serializer_class.preload_with
+        unless handler
+          raise SeregaError, "The :preload option requires a preload handler. Register one with `preload_with` (the :activerecord_preloads plugin does this for you)."
+        end
+
+        handler.call(objects, preloads)
+      rescue => error
+        SeregaUtils::SerializedAttributeError.call(error, self)
+      end
+
+      # Loads the batch loaders this point's value needs, each once for the whole
+      # level, and returns them keyed by loader name for #value to read from.
       #
-      # @return [SeregaObjectSerializer] object serializer for child plan
+      # @param level [SeregaEngine::Level] level whose objects are loaded for
+      # @return [Hash, nil] loaded data per loader name, or nil when none are needed
+      def load_batches(level)
+        names = batch_loaders
+        return if names.empty?
+
+        loaders = self.class.serializer_class.batch_loaders
+        names.each_with_object({}) do |name, batches|
+          batches[name] = level.fetch(loaders[name])
+        end
+      rescue => error
+        SeregaUtils::SerializedAttributeError.call(error, self)
+      end
+
+      #
+      # @return [Class<SeregaObjectSerializer>] object serializer class for child plan
       #
       def child_object_serializer
         serializer::SeregaObjectSerializer
       end
 
+      # Builds the object serializer that serializes this point's relation, or nil
+      # when the point has no child plan (a plain attribute). The point owns the
+      # static config (child plan, serializer class, `many`); the caller injects the
+      # runtime `context` and `opts`.
+      #
+      # @param context [Hash] serialization context
+      # @param opts [Hash] extra object-serializer options (e.g. the level queue)
+      # @return [SeregaObjectSerializer, nil] serializer for the child level
+      def child_serializer(context:, **opts)
+        return unless child_plan
+
+        child_object_serializer.new(context: context, plan: child_plan, many: many, **opts)
+      end
+
       private
 
       def set_normalized_vars

data/lib/serega/plugins/activerecord_preloads/activerecord_preloads.rb

@@ -82,7 +82,25 @@ class Serega
       # @return [void]
       #
       def self.after_load_plugin(serializer_class, **_opts)
-        serializer_class.preload_with { |objects, preloads| Preloader.preload(objects, preloads) }
+        serializer_class.preload_with do |objects, preloads|
+          Preloader.preload(ActiverecordPreloads.records(serializer_class, objects), preloads)
+        end
+      end
+
+      #
+      # The underlying records to preload onto. The :presenter plugin wraps every
+      # serialized object in a SimpleDelegator, but ActiveRecord's Preloader needs
+      # the real records, so unwrap them via #__getobj__ when presenter is used.
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param objects [Array] objects serialized at the current level
+      #
+      # @return [Array] the underlying records
+      #
+      def self.records(serializer_class, objects)
+        return objects unless serializer_class.plugin_used?(:presenter)
+
+        objects.map(&:__getobj__)
       end
     end
 

data/lib/serega/plugins/if/if.rb

@@ -42,9 +42,6 @@ class Serega
     #  end
     #
     module If
-      # This value must be returned to identify that serialization key was skipped
-      KEY_SKIPPED = :_key_skipped_with_serega_if_plugin
-
       # @return [Symbol] Plugin name
       def self.plugin_name
         :if
@@ -270,16 +267,18 @@ class Serega
       module ObjectSerializerInstanceMethods
         private
 
-        def serialize_point(object, point, _container)
-          return KEY_SKIPPED unless point.satisfy_if_conditions?(object, context)
+        # Skip the whole point for this object (its value is never resolved).
+        def resolve_point(object, point, _container, _batches, _child_plan)
+          return unless point.satisfy_if_conditions?(object, context)
+
           super
         end
 
-        def attach_final_value(value, point, container)
-          unless point.satisfy_if_value_conditions?(value, context)
-            container.delete(point.name) # remove reserved placeholder
-            return KEY_SKIPPED
-          end
+        # Skip only the assignment based on the resolved value. Levels resolve
+        # points in attribute order, so simply not assigning keeps the remaining
+        # keys in declared order — no slot to reserve or delete.
+        def write_value(value, point, _container)
+          return unless point.satisfy_if_value_conditions?(value, context)
 
           super
         end

data/lib/serega/plugins/presenter/presenter.rb

@@ -125,11 +125,14 @@ class Serega
         private
 
         #
-        # Replaces serialized object with Presenter.new(object, ctx)
+        # Wraps each serialized object in Presenter.new(object, ctx) before it is
+        # enqueued, so the whole level — value resolution and batch loaders alike —
+        # sees presenters.
         #
-        def serialize_object(object)
-          object = self.class.serializer_class::Presenter.new(object, context)
-          super
+        def enqueue(objects)
+          presenter = self.class.serializer_class::Presenter
+          presenters = objects.map { |object| presenter.new(object, context) }
+          super(presenters)
         end
       end
     end

data/lib/serega/utils/serialized_attribute_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaUtils
+    #
+    # Reraises an error, adding which attribute and serializer were being
+    # serialized when it happened. Shared by the synchronous serialization walk
+    # and the batch attach phase so the message stays identical for every
+    # attribute, whether its value is resolved inline or during batch loading.
+    #
+    module SerializedAttributeError
+      module_function
+
+      #
+      # @param error [Exception] Original error
+      # @param point [SeregaPlanPoint] Plan point being serialized
+      #
+      # @return [void]
+      #
+      def call(error, point)
+        raise error.exception(<<~MESSAGE.strip)
+          #{error.message}
+          (when serializing '#{point.name}' attribute in #{point.class.serializer_class})
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/serega.rb

@@ -22,6 +22,7 @@ require_relative "serega/helpers/serializer_class_helper"
 require_relative "serega/utils/enum_deep_dup"
 require_relative "serega/utils/enum_deep_freeze"
 require_relative "serega/utils/method_signature"
+require_relative "serega/utils/serialized_attribute_error"
 require_relative "serega/utils/symbol_name"
 require_relative "serega/utils/to_hash"
 require_relative "serega/attribute_value_resolvers/batch"
@@ -30,10 +31,9 @@ require_relative "serega/attribute_value_resolvers/delegate"
 require_relative "serega/attribute_value_resolvers/keyword"
 require_relative "serega/attribute"
 require_relative "serega/attribute_normalizer"
-require_relative "serega/batch/attribute_loader"
-require_relative "serega/batch/attribute_loaders"
-require_relative "serega/batch/level"
-require_relative "serega/batch/loader"
+require_relative "serega/engine/level_queue"
+require_relative "serega/engine/level"
+require_relative "serega/engine/loader"
 require_relative "serega/validations/utils/check_allowed_keys"
 require_relative "serega/validations/utils/check_opt_is_bool"
 require_relative "serega/validations/utils/check_opt_is_hash"
@@ -85,15 +85,10 @@ class Serega
   check_batch_loader_params_class.serializer_class = self
   const_set(:CheckBatchLoaderParams, check_batch_loader_params_class)
 
-  # Assigns `SeregaBatchLoader` constant to current class
-  batch_loader_class = Class.new(SeregaBatch::Loader)
-  batch_loader_class.serializer_class = self
-  const_set(:SeregaBatchLoader, batch_loader_class)
-
-  # Assigns `SeregaBatchAttributeLoader` constant to current class
-  batch_attribute_loader_class = Class.new(SeregaBatch::AttributeLoader)
-  batch_attribute_loader_class.serializer_class = self
-  const_set(:SeregaBatchAttributeLoader, batch_attribute_loader_class)
+  # Assigns `SeregaEngineLoader` constant to current class
+  engine_loader_class = Class.new(SeregaEngine::Loader)
+  engine_loader_class.serializer_class = self
+  const_set(:SeregaEngineLoader, engine_loader_class)
 
   #
   # Serializers class methods
@@ -213,7 +208,7 @@ class Serega
     def batch(name, value = nil, &block)
       raise SeregaError, "Batch loader must be defined with a callable value or block" if (value && block) || (!value && !block)
 
-      batch_loader = self::SeregaBatchLoader.new(name: name, block: value || block)
+      batch_loader = self::SeregaEngineLoader.new(name: name, block: value || block)
       batch_loaders[batch_loader.name] = batch_loader
     end
 
@@ -332,13 +327,9 @@ class Serega
       plan_point_class.serializer_class = subclass
       subclass.const_set(:SeregaPlanPoint, plan_point_class)
 
-      batch_loader_class = Class.new(self::SeregaBatchLoader)
-      batch_loader_class.serializer_class = subclass
-      subclass.const_set(:SeregaBatchLoader, batch_loader_class)
-
-      batch_attribute_loader_class = Class.new(self::SeregaBatchAttributeLoader)
-      batch_attribute_loader_class.serializer_class = subclass
-      subclass.const_set(:SeregaBatchAttributeLoader, batch_attribute_loader_class)
+      engine_loader_class = Class.new(self::SeregaEngineLoader)
+      engine_loader_class.serializer_class = subclass
+      subclass.const_set(:SeregaEngineLoader, engine_loader_class)
 
       object_serializer_class = Class.new(self::SeregaObjectSerializer)
       object_serializer_class.serializer_class = subclass
@@ -480,7 +471,7 @@ class Serega
       self.class::CheckSerializeParams.new(opts).validate unless opts.empty?
 
       opts[:context] ||= {}
-      opts[:batch_loaders] = SeregaBatch::AttributeLoaders.new(opts[:context])
+      opts[:level_queue] = SeregaEngine::LevelQueue.new
       opts[:many] = object.is_a?(Enumerable) unless opts.key?(:many)
       opts[:plan] = plan
       opts
@@ -492,7 +483,7 @@ class Serega
     # - plugin :metadata (adds metadata to final result)
     def serialize(object, opts)
       result = self.class::SeregaObjectSerializer.new(**opts).serialize(object)
-      opts[:batch_loaders].load_all
+      opts[:level_queue].run
       result
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.37.1
+  version: 0.38.0
 platform: ruby
 authors:
 - Andrey Glushkov
@@ -33,12 +33,11 @@ files:
 - lib/serega/attribute_value_resolvers/const.rb
 - lib/serega/attribute_value_resolvers/delegate.rb
 - lib/serega/attribute_value_resolvers/keyword.rb
-- lib/serega/batch/attribute_loader.rb
-- lib/serega/batch/attribute_loaders.rb
-- lib/serega/batch/level.rb
-- lib/serega/batch/loader.rb
 - lib/serega/config.rb
 - lib/serega/data_builder.rb
+- lib/serega/engine/level.rb
+- lib/serega/engine/level_queue.rb
+- lib/serega/engine/loader.rb
 - lib/serega/errors.rb
 - lib/serega/helpers/serializer_class_helper.rb
 - lib/serega/object_serializer.rb
@@ -74,6 +73,7 @@ files:
 - lib/serega/utils/enum_deep_dup.rb
 - lib/serega/utils/enum_deep_freeze.rb
 - lib/serega/utils/method_signature.rb
+- lib/serega/utils/serialized_attribute_error.rb
 - lib/serega/utils/symbol_name.rb
 - lib/serega/utils/to_hash.rb
 - lib/serega/validations/attribute/check_block.rb

data/lib/serega/batch/attribute_loader.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  #
-  # Batch feature main module
-  #
-  module SeregaBatch
-    # Remembers data required to batch load single attribute
-    class AttributeLoader
-      # Instance methods for AttributeLoader
-      module InstanceMethods
-        # @param point [SeregaPlanPoint]
-        # @param level [SeregaBatch::Level] Shared objects and results for this point's plan level
-        def initialize(point, level)
-          @point = point
-          @level = level
-          @serialized_object_attachers = []
-        end
-
-        # Stores object with attacher to find and attach attribute values in batch later.
-        # @param object [Object] Serialized object
-        # @param attacher [Proc] Proc that attaches found values to originated attributes
-        # @return [void]
-        def store(object, attacher)
-          serialized_object_attachers << [object, attacher]
-        end
-
-        # Preloads this attribute's associations onto the level's objects, once for
-        # the attribute (not per named batch loader), via the serializer's registered
-        # `preload_with` handler. Raises when `:preload` is declared but no handler
-        # exists, so a declared preload never silently does nothing.
-        # @return [void]
-        def preload_associations
-          preloads = point.attribute.preloads
-          return unless preloads
-
-          handler = point.class.serializer_class.preload_with
-          unless handler
-            raise SeregaError, "The :preload option requires a preload handler. Register one with `preload_with` (the :activerecord_preloads plugin does this for you)."
-          end
-
-          handler.call(level.objects, preloads)
-        rescue => error
-          reraise_with_serialized_attribute_details(error)
-        end
-
-        # Loads a single named batch for this level's objects. Caching across
-        # attributes that reuse the loader is handled by the Level.
-        # @param loader [SeregaBatch::Loader] Named batch loader
-        # @return [Object] Loaded batch values
-        def load_batch(loader)
-          level.load(loader)
-        rescue => error
-          reraise_with_serialized_attribute_details(error)
-        end
-
-        # Attaches already loaded batch values to every stored object.
-        # @param batches [Hash] Loaded values grouped by batch loader name
-        # @return [void]
-        def attach(batches)
-          serialized_object_attachers.each do |object, attacher|
-            attacher.call(object, batches)
-          end
-        end
-
-        attr_reader :point
-        attr_reader :level
-
-        private
-
-        def reraise_with_serialized_attribute_details(error)
-          raise error.exception(<<~MESSAGE.strip)
-            #{error.message}
-            (when serializing '#{point.name}' attribute in #{point.class.serializer_class})
-          MESSAGE
-        end
-
-        attr_reader :serialized_object_attachers
-      end
-
-      extend SeregaHelpers::SerializerClassHelper
-      include InstanceMethods
-    end
-  end
-end

data/lib/serega/batch/attribute_loaders.rb

@@ -1,108 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  #
-  # Batch feature main module
-  #
-  module SeregaBatch
-    #
-    # Batch loaders
-    #
-    # Remembers data required to batch load all attributes
-    class AttributeLoaders
-      #
-      # Initializes new batch loaders
-      #
-      # @param context [Hash] Serialization context, constant for the whole run
-      #
-      def initialize(context)
-        @context = context
-        @attribute_loaders = []
-        @point_index = {}.compare_by_identity
-        @levels = {}.compare_by_identity
-      end
-
-      # Gathers a chunk of objects serialized at a plan level, so every attribute at
-      # that level shares one set of objects to batch load against.
-      #
-      # @param plan [SeregaPlan] Plan serializing these objects
-      # @param objects [Array] Objects being serialized at this level
-      #
-      # @return [void]
-      def add_objects(plan, objects)
-        level_for(plan).add_objects(objects)
-      end
-
-      # Remembers data for batch serialization:
-      #
-      # @param point [SeregaPlanPoint] Serialization plan point
-      # @param object [Object] Serialized object
-      # @param attacher [Proc] Serialized value attacher
-      #
-      # @return [void]
-      def remember(point, object, attacher)
-        attribute_loader = point_index[point]
-
-        unless attribute_loader
-          serializer_class = point.class.serializer_class
-          attribute_loader = serializer_class::SeregaBatchAttributeLoader.new(point, level_for(point.plan))
-          attribute_loaders << attribute_loader
-          point_index[point] = attribute_loader
-        end
-
-        attribute_loader.store(object, attacher)
-      end
-
-      #
-      # Loads all registered batches and attaches loaded values.
-      #
-      # Iterates over each loader including loaders added during iteration
-      # (child serializers discovered inside a batch flush add new loaders).
-      def load_all
-        i = 0
-        while i < attribute_loaders.size
-          attribute_loader = attribute_loaders[i]
-          attribute_loader.attach(load_batches(attribute_loader))
-          i += 1
-        end
-      end
-
-      private
-
-      # Serialization context shared by every level
-      attr_reader :context
-
-      # keeps all AttributeLoader instances
-      attr_reader :attribute_loaders
-
-      # keeps tracking of already added points
-      attr_reader :point_index
-
-      # keeps one Level per plan (compare_by_identity: plan instance identifies a level)
-      attr_reader :levels
-
-      def level_for(plan)
-        levels[plan] ||= Level.new(context)
-      end
-
-      # Builds the { batch_loader_name => loaded_values } hash for one attribute.
-      #
-      # Loading is delegated to the attribute's Level, which loads each named batch
-      # once for the whole level: attributes sharing a loader over the same objects
-      # reuse a single result, deeper levels load separately.
-      def load_batches(attribute_loader)
-        attribute_loader.preload_associations
-
-        point = attribute_loader.point
-        serializer_class = point.class.serializer_class
-
-        batches = {}
-        point.batch_loaders.each do |batch_loader_name|
-          loader = serializer_class.batch_loaders[batch_loader_name]
-          batches[batch_loader_name] = attribute_loader.load_batch(loader)
-        end
-        batches
-      end
-    end
-  end
-end

data/lib/serega/batch/level.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  #
-  # Batch feature main module
-  #
-  module SeregaBatch
-    #
-    # Objects serialized at one plan level, together with their loaded batch results.
-    #
-    # Every attribute serialized at the same level shares one Level, so a named batch
-    # loader reused by several of them runs once for the whole set of objects. The same
-    # loader over a different level (deeper nesting) uses a different Level and loads
-    # again.
-    #
-    class Level
-      # @return [Array] Objects gathered for this level
-      attr_reader :objects
-
-      # @param context [Hash] Serialization context
-      def initialize(context)
-        @context = context
-        @objects = []
-        @results = {}.compare_by_identity
-      end
-
-      # Adds a chunk of serialized objects to this level.
-      # @param objects [Array] Objects being serialized at this level
-      # @return [void]
-      def add_objects(objects)
-        @objects.concat(objects)
-      end
-
-      # Loads and returns values for the given batch loader, once per loader.
-      #
-      # Freezes the gathered objects on the first load: all of a level's objects
-      # are added before any of its batches load, so sealing the set here guards
-      # against a later stray `add_objects` and against a loader mutating it.
-      #
-      # @param loader [SeregaBatch::Loader] Named batch loader
-      # @return [Object] Loaded values
-      def load(loader)
-        @objects.freeze
-        @results[loader] ||= loader.load(@objects, @context)
-      end
-    end
-  end
-end