serega 0.37.2 → 0.39.0

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,85 +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
+      # 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
 
-      def serialize_array(objects)
-        objects.map { |object| serialize_object(object) }
-      end
+        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)
 
-      # 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
-          SeregaUtils::SerializedAttributeError.call(error, point)
+          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
+      # How to serialize `object`, deciding whether the result is a collection or a
+      # single object and checking the object type 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 SeregaUtils::CollectionDetector.call(object) ? :many : :one
+        when TrueClass then SeregaUtils::CollectionDetector.call(object) ? :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,27 @@ 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.
+      # Objects are wrapped only when the Presenter class has custom methods.
+      #
+      # @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)
+        return objects unless serializer_class.custom_presenter?
+
+        objects.map(&:__getobj__)
       end
     end
 

data/lib/serega/plugins/explicit_many_option/explicit_many_option.rb

@@ -6,7 +6,8 @@ class Serega
     # Plugin :explicit_many_option
     #
     # Plugin requires to add :many option when adding relationships
-    # (relationships are attributes with :serializer option specified)
+    # (relationships are attributes with the :serializer option or a block
+    # defining a nested serializer)
     #
     # Adding this plugin makes it clearer to find if relationship returns array or single object
     #
@@ -56,7 +57,7 @@ class Serega
         def check_opts
           super
 
-          CheckOptMany.call(opts)
+          CheckOptMany.call(opts, block)
         end
       end
     end

data/lib/serega/plugins/explicit_many_option/validations/check_opt_many.rb

@@ -10,23 +10,25 @@ class Serega
         class << self
           #
           # Checks attribute :many option must be provided with relations
+          # (attributes with the :serializer option or a block defining
+          # a nested serializer)
           #
           # @param opts [Hash] Attribute options
+          # @param block [nil, Proc] Attribute block
           #
           # @raise [SeregaError] Attribute validation error
           #
           # @return [void]
           #
-          def call(opts)
-            serializer = opts[:serializer]
-            return unless serializer
+          def call(opts, block = nil)
+            return if !opts[:serializer] && !block
 
             many_option_exists = opts.key?(:many)
             return if many_option_exists
 
             raise SeregaError,
               "Attribute option :many [Boolean] must be provided" \
-              " for attributes with :serializer option"
+              " for attributes with :serializer option or a block"
           end
         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

@@ -15,13 +15,19 @@ class Serega
     # - The original object is accessible via __getobj__ (standard SimpleDelegator API).
     # - The serialization context is accessible via the private method __ctx__.
     #
+    # Objects are wrapped in the Presenter only when the serializer's Presenter
+    # class (or an inherited one) was actually extended with custom methods —
+    # a bare `plugin :presenter` adds no wrapping overhead. The check is
+    # denormalized: `SerializerClass.custom_presenter?` is asked once per
+    # object serializer and the result is reused for the whole level.
+    #
     #   class UserSerializer < Serega
     #     plugin :presenter
     #
     #     attribute :name
     #     attribute :role
     #
-    #     class Presenter
+    #     presenter do
     #       def name
     #         [first_name, last_name].compact.join(' ') # first_name/last_name delegated to object
     #       end
@@ -31,6 +37,9 @@ class Serega
     #       end
     #     end
     #   end
+    #
+    # The `presenter do ... end` block is evaluated inside the serializer's own
+    # Presenter class, so multiple blocks accumulate.
     module Presenter
       # @return [Symbol] Plugin name
       def self.plugin_name
@@ -62,6 +71,11 @@ class Serega
         presenter_class = Class.new(Presenter)
         presenter_class.serializer_class = serializer_class
         serializer_class.const_set(:Presenter, presenter_class)
+
+        # The presenter's unwrap method returns the serialized object itself,
+        # not an association — it must never be auto-preloaded.
+        config = serializer_class.config
+        config.auto_preload_excluded_methods = config.auto_preload_excluded_methods | [:__getobj__]
       end
 
       # Presenter class
@@ -97,6 +111,44 @@ class Serega
         extend SeregaHelpers::SerializerClassHelper
         extend Forwardable
         include InstanceMethods
+
+        # Tracks whether user code was added to the Presenter class.
+        #
+        # These singleton methods are defined after the base class body above,
+        # so the plugin's own includes do not mark the base class as modified.
+        # Lazy delegators defined by #method_missing do mark the class, but
+        # they can appear only on presenters that are already wrapping.
+        class << self
+          #
+          # Checks if this Presenter class (or an inherited one) was extended
+          # with custom user code and therefore objects must be wrapped
+          #
+          # @return [Boolean] whether custom presenter methods were defined
+          #
+          def modified?
+            return true if defined?(@modified)
+            return false if equal?(Presenter) # the plugin's base class — the walk stops here
+
+            superclass.modified?
+          end
+
+          def include(*modules)
+            @modified = true
+            super
+          end
+
+          def prepend(*modules)
+            @modified = true
+            super
+          end
+
+          private
+
+          def method_added(name)
+            @modified = true
+            super
+          end
+        end
       end
 
       #
@@ -105,6 +157,36 @@ class Serega
       # @see Serega
       #
       module ClassMethods
+        #
+        # Defines presenter methods — evaluates the block inside the
+        # serializer's own Presenter class. Multiple blocks accumulate.
+        #
+        #   presenter do
+        #     def name
+        #       [first_name, last_name].compact.join(" ")
+        #     end
+        #   end
+        #
+        # @return [void]
+        #
+        def presenter(&block)
+          raise SeregaError, "Provide a block with presenter methods: `presenter do ... end`" unless block
+
+          self::Presenter.class_exec(&block)
+          nil
+        end
+
+        #
+        # Checks if the serializer's Presenter class (or an inherited one) was
+        # extended with custom user code. When it was not, serialized objects
+        # are not wrapped in the Presenter at all.
+        #
+        # @return [Boolean] whether custom presenter methods were defined
+        #
+        def custom_presenter?
+          self::Presenter.modified?
+        end
+
         private
 
         def inherited(subclass)
@@ -122,14 +204,28 @@ class Serega
       # @see Serega::SeregaObjectSerializer
       #
       module SeregaObjectSerializerInstanceMethods
+        # The custom-presenter check is made once per object serializer here
+        # and its result is reused for every enqueued chunk of the level.
+        def initialize(**opts)
+          super
+          @wrap_in_presenter = self.class.serializer_class.custom_presenter?
+        end
+
         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. Objects are not wrapped when the Presenter class has
+        # no custom methods — such wrapping would only add overhead and break
+        # class checks (object.is_a?, Hash === object) without changing anything.
         #
-        def serialize_object(object)
-          object = self.class.serializer_class::Presenter.new(object, context)
-          super
+        def enqueue(objects)
+          return super unless @wrap_in_presenter
+
+          presenter = self.class.serializer_class::Presenter
+          presenters = objects.map { |object| presenter.new(object, context) }
+          super(presenters)
         end
       end
     end

data/lib/serega/plugins/root/root.rb

@@ -244,7 +244,7 @@ class Serega
           return opts[:root] if opts.key?(:root)
 
           root = self.class.config.root
-          (opts.fetch(:many) { object.is_a?(Enumerable) }) ? root.many : root.one
+          (opts.fetch(:many) { SeregaUtils::CollectionDetector.call(object) }) ? root.many : root.one
         end
       end
 

data/lib/serega/utils/collection_detector.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaUtils
+    #
+    # Utility to check if an object should be serialized as a collection.
+    #
+    # Hashes and Structs are Enumerable, but enumerate their own member
+    # values, so they are treated as single objects.
+    #
+    class CollectionDetector
+      class << self
+        #
+        # Checks if provided object is a collection of objects
+        #
+        # @param object [Object] Serialized object
+        #
+        # @return [Boolean] whether object should be serialized as a collection
+        #
+        def call(object)
+          object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)
+        end
+      end
+    end
+  end
+end

data/lib/serega/validations/attribute/check_block.rb

@@ -10,25 +10,30 @@ class Serega
       # Attribute `block` parameter validator
       #
       class CheckBlock
+        # Explains the changed attribute block behavior. Shown when the block
+        # looks like an old-style value block — it accepts parameters or
+        # defines no attributes.
+        ERROR_MESSAGE =
+          "Attribute block now defines a nested serializer:" \
+          " it is executed in the context of a new serializer class and must define its attributes." \
+          " Defining the attribute value with a block is not supported anymore," \
+          " use the `value: <callable>` option instead."
+
         class << self
           #
           # Checks block parameter provided with attribute.
-          # Must have up to two arguments - object and context. Context can be
-          # also provided as keyword argument :ctx.
-          #
-          # @example without arguments
-          #   attribute(:email) { CONSTANT_EMAIL }
-          #
-          # @example with one argument
-          #   attribute(:email) { |obj| obj.confirmed_email }
           #
-          # @example with two arguments
-          #   attribute(:email) { |obj, context| context['is_current'] ? obj.email : nil }
+          # The block defines attributes of a nested anonymous serializer, so
+          # it is executed in the context of that serializer and must accept
+          # no parameters.
           #
-          # @example with one argument and keyword context
-          #   attribute(:email) { |obj, ctx:| obj.email if ctx[:show] }
+          # @example
+          #   attribute :statistics, method: :itself do
+          #     attribute :likes_count
+          #     attribute :comments_count
+          #   end
           #
-          # @param block [Proc] Block that returns serialized attribute value
+          # @param block [Proc] Block that defines nested serializer attributes
           #
           # @raise [SeregaError] SeregaError that block has invalid arguments
           #
@@ -37,48 +42,8 @@ class Serega
           def call(block)
             return unless block
 
-            check_block(block)
-          end
-
-          private
-
-          def check_block(block)
-            signature = SeregaUtils::MethodSignature.call(block, pos_limit: 2, keyword_args: [:ctx, :batches])
-
-            raise SeregaError, signature_error unless valid_signature?(signature)
-          end
-
-          def valid_signature?(signature)
-            case signature
-            when "0"             # no parameters
-              true
-            when "1"             # call(object)
-              true
-            when "1_ctx"         # call(object, ctx:)
-              true
-            when "1_batches"     # call(object, batches:)
-              true
-            when "1_batches_ctx" # call(object, batches:, ctx:)
-              true
-            when "2"             # call(object, context)
-              true
-            when "2_batches_ctx" # call(object, context, batches:, ctx:) (proc with no params)
-              true
-            else
-              false
-            end
-          end
-
-          def signature_error
-            <<~ERROR.strip
-              Invalid attribute block parameters, valid parameters signatures:
-              - ()                       # no parameters
-              - (object)                 # one positional parameter
-              - (object, ctx:)           # one positional parameter and :ctx keyword
-              - (object, batches:)       # one positional parameter and :batches keyword
-              - (object, ctx:, batches:) # one positional parameter, :ctx, and :batches keywords
-              - (object, context)        # two positional parameters
-            ERROR
+            signature = SeregaUtils::MethodSignature.call(block, pos_limit: 0)
+            raise SeregaError, ERROR_MESSAGE unless signature == "0"
           end
         end
       end