serega 0.35.0 → 0.37.0

data/lib/serega/batch/level.rb

@@ -0,0 +1,48 @@
+# 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

data/lib/serega/config.rb

@@ -23,7 +23,6 @@ class Serega
         delegate
         default
         preload
-        preload_path
         batch
       ].freeze,
       serialize_keys: %i[context many].freeze,
@@ -116,27 +115,26 @@ class Serega
       end
 
       # Returns :hide_by_default config option
-      # @return [Boolean, Array<Symbol>] Current :hide_by_default config option
+      # @return [Boolean, Symbol] Current :hide_by_default config option
       def hide_by_default
         opts.fetch(:hide_by_default)
       end
 
       # Sets :hide_by_default config option
       #
-      # @param value [Boolean, Array<Symbol>] false, true, or array of :preload/:batch symbols
+      # @param value [Boolean, Symbol] Accepted values:
+      #   - false (default) — nothing is hidden by default
+      #   - true — all attributes are hidden by default
+      #   - :auto — hides attributes that declare :preload or :batch
       #
-      # @return [Boolean, Array<Symbol>] New :hide_by_default config option
+      # @return [Boolean, Symbol] New :hide_by_default config option
       def hide_by_default=(value)
         opts[:hide_by_default] =
           case value
-          when true, false
-            value
-          when Array
-            invalid = value - %i[preload batch]
-            raise SeregaError, "Must have true, false, or an Array of [:preload, :batch], #{value.inspect} provided" if invalid.any?
+          when true, false, :auto
             value
           else
-            raise SeregaError, "Must have true, false, or an Array of [:preload, :batch], #{value.inspect} provided"
+            raise SeregaError, "Must have true, false, or :auto, #{value.inspect} provided"
           end
       end
 

data/lib/serega/data_builder.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Builds Data objects from serialized hashes.
+  # Used by `#to_data` / `.to_data`.
+  #
+  class SeregaDataBuilder
+    # SeregaDataBuilder class methods
+    module SeregaDataBuilderClassMethods
+      #
+      # Converts serialized Hash/Array result into a tree of Ruby Data objects
+      # following the serializer's plan structure.
+      #
+      # @param serializer [Serega] Serializer instance carrying the plan
+      # @param serialized [Hash, Array, nil] Serialized output from `#to_h`
+      #
+      # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
+      #
+      def call(serializer, serialized)
+        build(serialized, serializer.plan)
+      end
+
+      private
+
+      def build(serialized, plan)
+        case serialized
+        when Array then serialized.map { |item| hash_to_data(item, plan) }
+        when Hash then hash_to_data(serialized, plan)
+        else serialized
+        end
+      end
+
+      def hash_to_data(hash, plan)
+        hash_data = hash.to_h do |key, value|
+          child_plan = plan.points_hash.fetch(key).child_plan
+          value = build(value, child_plan) if child_plan
+          [key, value]
+        end
+
+        build_data_object(plan, hash_data)
+      end
+
+      def build_data_object(plan, hash_data)
+        plan.data_class.new(**hash_data)
+      end
+    end
+
+    extend SeregaHelpers::SerializerClassHelper
+    extend SeregaDataBuilderClassMethods
+  end
+end

data/lib/serega/object_serializer.rb

@@ -34,7 +34,13 @@ class Serega
       def serialize(object)
         return if object.nil?
 
-        array?(object, many) ? serialize_array(object) : serialize_object(object)
+        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)
+        end
       end
 
       private

data/lib/serega/plan.rb

@@ -27,6 +27,18 @@ class Serega
         cached_plan_for(opts, max_cache_size)
       end
 
+      #
+      # Returns (and caches) the Data class for the given set of field names.
+      # Uses the Array as cache key so the same Data class is reused across
+      # all plan instances with identical fields.
+      #
+      # @param point_names [Array<Symbol>] Attribute names for the Data members
+      # @return [Class] Subclass of Data
+      #
+      def data_class_for(point_names)
+        (@data_classes ||= {})[point_names] ||= Data.define(*point_names)
+      end
+
       private
 
       def cached_plan_for(opts, max_cache_size)
@@ -65,9 +77,9 @@ class Serega
       # @return [Array<SeregaPlanPoint>] points to serialize
       attr_reader :points
 
-      # Shows if plan includes batch points
-      # @return [Array<SeregaPlanPoint>] points to serialize
-      attr_reader :has_batch_points
+      # Named serialization points
+      # @return [Hash] Named points
+      attr_reader :points_hash
 
       #
       # Instantiate new serialization plan
@@ -84,9 +96,9 @@ class Serega
       # @return [SeregaPlan] Serialization plan
       #
       def initialize(parent_plan_point, modifiers)
-        @has_batch_points = false # should be before assigning points, generated points can change this attribute
         @parent_plan_point = parent_plan_point
         @points = attributes_points(modifiers)
+        @points_hash = points.to_h { |point| [point.name, point] }
       end
 
       #
@@ -97,14 +109,21 @@ class Serega
       end
 
       #
-      # Marks current plan and top-level plans as `has_batch_points`
-      # It is needed to initialize Batch Attribute Loaders when serialization starts
+      # @return [Boolean] whether any point of this plan is batch loaded
       #
-      def mark_as_has_batch_points
-        return if has_batch_points
+      def batch?
+        return @batch if defined?(@batch)
 
-        @has_batch_points = true
-        parent_plan_point.plan.mark_as_has_batch_points if parent_plan_point # rubocop:disable Style/SafeNavigation
+        @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.
+      #
+      # @return [Class] Subclass of Data
+      #
+      def data_class
+        @data_class ||= self.class.data_class_for(point_names)
       end
 
       private
@@ -130,6 +149,10 @@ class Serega
 
         points.freeze
       end
+
+      def point_names
+        @point_names ||= points.map(&:name)
+      end
     end
 
     extend ClassMethods

data/lib/serega/plan_point.rb

@@ -25,14 +25,6 @@ class Serega
       # @return [Hash] Attributes to serialize
       attr_reader :modifiers
 
-      # Shows preloads for nested attributes
-      # @return [Hash] preloads for nested attributes
-      attr_reader :preloads
-
-      # Shows preloads_path for current attribute
-      # @return [Array<Symbol>, nil] preloads path for current attribute
-      attr_reader :preloads_path
-
       #
       # Initializes plan point
       #
@@ -97,9 +89,6 @@ class Serega
 
       def set_normalized_vars
         @child_plan = prepare_child_plan
-        @preloads = prepare_preloads
-        @preloads_path = prepare_preloads_path
-        plan.mark_as_has_batch_points if batch?
       end
 
       def prepare_child_plan
@@ -109,14 +98,6 @@ class Serega
 
         serializer::SeregaPlan.new(self, fields)
       end
-
-      def prepare_preloads
-        SeregaUtils::PreloadsConstructor.call(child_plan)
-      end
-
-      def prepare_preloads_path
-        attribute.preloads_path
-      end
     end
 
     extend SeregaHelpers::SerializerClassHelper

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

@@ -7,9 +7,8 @@ class Serega
     #
     # Automatically preloads associations to serialized objects
     #
-    # It takes all defined preloads from serialized attributes (including attributes from serialized relations),
-    # merges them into single associations hash and then uses ActiveRecord::Associations::Preloader
-    # to preload all associations.
+    # Every association declared with `:preload` is loaded once during serialization using
+    # ActiveRecord::Associations::Preloader, so there are no N+1 queries.
     #
     # @example
     #   class AppSerializer < Serega
@@ -39,7 +38,7 @@ class Serega
     #     attribute :downloads_count, preload: :downloads, value: proc { |album| album.downloads.count }
     #   end
     #
-    #   UserSerializer.to_h(user) # => preloads {users_stats: {}, albums: { downloads: {} }}
+    #   UserSerializer.to_h(user)
     #
     module ActiverecordPreloads
       #
@@ -72,62 +71,18 @@ class Serega
       #
       def self.load_plugin(serializer_class, **_opts)
         require_relative "lib/preloader"
-        require_relative "lib/active_record_objects"
-
-        serializer_class.include(InstanceMethods)
-        serializer_class::SeregaBatchAttributeLoader.include(BatchAttributeLoaderInstanceMethods)
       end
 
       #
-      # Overrides SeregaBatch::AttributeLoader class instance methods
+      # Registers the ActiveRecord preload handler
       #
-      module BatchAttributeLoaderInstanceMethods
-        private
-
-        # Preloads associations to batch-generated data
-        def load_one(serializer_class, batch_loader_name, context)
-          batch_loaded_data = super
-
-          preloads = point.preloads
-          return batch_loaded_data if preloads.empty?
-
-          ar_objects = ActiveRecordObjects.call(batch_loaded_data)
-          Preloader.preload(ar_objects, preloads)
-
-          batch_loaded_data
-        end
-      end
-
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] Plugin options
       #
-      # Overrides Serega class instance methods
+      # @return [void]
       #
-      module InstanceMethods
-        #
-        # Preloads associations to object
-        #
-        # @param object [Object] Any object
-        # @return provided object
-        #
-        def preload_associations_to(object)
-          return object if object.nil? || (object.is_a?(Array) && object.empty?)
-
-          preloads = preloads() # `preloads()` method comes from :preloads plugin
-          return object if preloads.empty?
-
-          Preloader.preload(object, preloads)
-          object
-        end
-
-        private
-
-        #
-        # Override original #serialize method
-        # Preloads associations to object before serialization
-        #
-        def serialize(object, _opts)
-          preload_associations_to(object)
-          super
-        end
+      def self.after_load_plugin(serializer_class, **_opts)
+        serializer_class.preload_with { |objects, preloads| Preloader.preload(objects, preloads) }
       end
     end
 

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

@@ -14,7 +14,7 @@ class Serega
           # @return [Object] provided object with preloaded associations
           #
           def preload(object, preloads)
-            return object if object.nil? || (object.is_a?(Array) && object.empty?) || preloads.empty?
+            return object if object.nil? || (object.is_a?(Array) && object.empty?)
 
             preload_handler = handlers.find { |handler| handler.fit?(object) }
             raise SeregaError, "Can't preload #{preloads.inspect} to #{object.inspect}" unless preload_handler

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

@@ -69,6 +69,7 @@ class Serega
         serializer_class::SeregaPlanPoint.include(PlanPointInstanceMethods)
         serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
         serializer_class::SeregaObjectSerializer.include(ObjectSerializerInstanceMethods)
+        serializer_class::SeregaDataBuilder.extend(DataBuilderClassMethods)
       end
 
       #
@@ -215,6 +216,7 @@ class Serega
           when "1" then condition.call(object)
           when "2" then condition.call(object, context)
           when "1_ctx" then condition.call(object, ctx: context)
+          when "2_ctx" then condition.call(object, context, ctx: context)
           else # "0"
             condition.call
           end
@@ -239,6 +241,27 @@ class Serega
         end
       end
 
+      #
+      # SeregaDataBuilder additional/patched class methods
+      #
+      # Overrides `build_data_object` to handle plans where some keys were skipped
+      # by `:if`/`:unless`/`:if_value`/`:unless_value` conditions, so the Data class
+      # is built from the actually-present keys rather than the full plan.
+      #
+      # @see Serega::SeregaDataBuilder
+      #
+      module DataBuilderClassMethods
+        private
+
+        def build_data_object(plan, hash_data)
+          if hash_data.size < plan.points.size
+            plan.class.data_class_for(hash_data.keys).new(**hash_data)
+          else
+            super
+          end
+        end
+      end
+
       #
       # SeregaObjectSerializer additional/patched class methods
       #

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

@@ -47,6 +47,8 @@ class Serega
               true
             when "1_ctx"  # (object, :ctx)
               true
+            when "2_ctx"  # (object, context, :ctx)
+              true
             else
               false
             end
@@ -55,10 +57,11 @@ class Serega
           def signature_error
             <<~ERROR.strip
               Invalid attribute option :if parameters, valid parameters signatures:
-              - ()                # no parameters
-              - (object)          # one positional parameter
-              - (object, context) # two positional parameters
-              - (object, :ctx)    # one positional parameter and :ctx keyword
+              - ()                     # no parameters
+              - (object)               # one positional parameter
+              - (object, context)      # two positional parameters
+              - (object, :ctx)         # one positional parameter and :ctx keyword
+              - (object, context, :ctx) # two positional parameters and :ctx keyword
             ERROR
           end
         end

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

@@ -52,6 +52,8 @@ class Serega
               true
             when "1_ctx"  # (value, :ctx)
               true
+            when "2_ctx"  # (value, context, :ctx)
+              true
             else
               false
             end
@@ -60,10 +62,11 @@ class Serega
           def signature_error
             <<~ERROR.strip
               Invalid attribute option :if_value parameters, valid parameters signatures:
-              - ()               # no parameters
-              - (value)          # one positional parameter
-              - (value, context) # two positional parameters
-              - (value, :ctx)    # one positional parameter and :ctx keyword
+              - ()                     # no parameters
+              - (value)                # one positional parameter
+              - (value, context)       # two positional parameters
+              - (value, :ctx)          # one positional parameter and :ctx keyword
+              - (value, context, :ctx) # two positional parameters and :ctx keyword
             ERROR
           end
         end

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

@@ -47,6 +47,8 @@ class Serega
               true
             when "1_ctx"  # (object, :ctx)
               true
+            when "2_ctx"  # (object, context, :ctx)
+              true
             else
               false
             end
@@ -55,10 +57,11 @@ class Serega
           def signature_error
             <<~ERROR.strip
               Invalid attribute option :unless parameters, valid parameters signatures:
-              - ()                # no parameters
-              - (object)          # one positional parameter
-              - (object, context) # two positional parameters
-              - (object, :ctx)    # one positional parameter and :ctx keyword
+              - ()                      # no parameters
+              - (object)                # one positional parameter
+              - (object, context)       # two positional parameters
+              - (object, :ctx)          # one positional parameter and :ctx keyword
+              - (object, context, :ctx) # two positional parameters and :ctx keyword
             ERROR
           end
         end

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

@@ -52,6 +52,8 @@ class Serega
               true
             when "1_ctx"  # (value, :ctx)
               true
+            when "2_ctx"  # (value, context, :ctx)
+              true
             else
               false
             end
@@ -60,10 +62,11 @@ class Serega
           def signature_error
             <<~ERROR.strip
               Invalid attribute option :unless_value parameters, valid parameters signatures:
-              - ()               # no parameters
-              - (value)          # one positional parameter
-              - (value, context) # two positional parameters
-              - (value, :ctx)    # one positional parameter and :ctx keyword
+              - ()                     # no parameters
+              - (value)                # one positional parameter
+              - (value, context)       # two positional parameters
+              - (value, :ctx)          # one positional parameter and :ctx keyword
+              - (value, context, :ctx) # two positional parameters and :ctx keyword
             ERROR
           end
         end

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

@@ -92,6 +92,7 @@ class Serega
         serializer_class.extend(ClassMethods)
         serializer_class.include(InstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
+        serializer_class::SeregaDataBuilder.extend(DataBuilderClassMethods)
       end
 
       #
@@ -214,6 +215,22 @@ class Serega
       # @see Serega
       #
       module InstanceMethods
+        #
+        # Serializes provided object to a tree of Ruby Data objects.
+        # When a root key is configured, the result is wrapped in an outer Data object
+        # whose members include the root key plus any metadata keys.
+        #
+        # @param object [Object] Serialized object
+        # @param opts [Hash, nil] Serializing options (`:root`, `:many`, `:context`, etc.)
+        #
+        # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
+        #
+        def to_data(object, opts = nil)
+          opts = prepare_initial_serialization_opts(object, opts)
+          serialized_data = serialize(object, opts)
+          self.class::SeregaDataBuilder.call(self, serialized_data, opts)
+        end
+
         private
 
         def serialize(object, opts)
@@ -230,6 +247,69 @@ class Serega
           (opts.fetch(:many) { object.is_a?(Enumerable) }) ? root.many : root.one
         end
       end
+
+      #
+      # SeregaDataBuilder additional/patched class methods
+      #
+      # Overrides `call` to handle the root key: the serialized result is
+      # unwrapped from the root key, converted to a Data tree by the base
+      # implementation, and then re-wrapped together with any metadata keys
+      # in an outer Data object. Metadata values (arbitrary hashes/arrays)
+      # are recursively converted to Data objects via `deep_hash_to_data`.
+      #
+      # When the root key is `nil` (disabled), delegates directly to the base.
+      #
+      # @see Serega::SeregaDataBuilder
+      #
+      module DataBuilderClassMethods
+        #
+        # @param serializer [Serega] Serializer instance carrying the plan
+        # @param serialized_result [Hash, Array, nil] Full serialized output (possibly wrapped under root key)
+        # @param serialization_opts [Hash] Serialization options used to determine the root key
+        #
+        # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
+        #
+        def call(serializer, serialized_result, serialization_opts)
+          root_key = resolve_root_key(serializer, serialization_opts)
+          return super(serializer, serialized_result) unless root_key
+
+          root_data = super(serializer, serialized_result.fetch(root_key))
+          build_data_objects(serialized_result, root_key, root_data)
+        end
+
+        private
+
+        def resolve_root_key(serializer, serialization_opts)
+          if serialization_opts.key?(:root)
+            serialization_opts[:root]
+          else
+            config_root = serializer.class.config.root
+            serialization_opts[:many] ? config_root.many : config_root.one
+          end
+        end
+
+        def build_data_objects(serialized_result, root_key, root_data)
+          converted_hash =
+            serialized_result.to_h do |key, val|
+              value = (key == root_key) ? root_data : deep_hash_to_data(val)
+              [key, value]
+            end
+
+          Data.define(*converted_hash.keys).new(**converted_hash)
+        end
+
+        def deep_hash_to_data(value)
+          case value
+          when Hash
+            converted = value.transform_values { |nested| deep_hash_to_data(nested) }
+            Data.define(*value.keys).new(**converted)
+          when Array
+            value.map { |item| deep_hash_to_data(item) }
+          else
+            value
+          end
+        end
+      end
     end
 
     register_plugin(Root.plugin_name, Root)

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

@@ -19,6 +19,17 @@ class Serega
           def call(opts)
             return unless opts.key?(:preload)
 
+            check_opt_preload(opts)
+            check_usage_with_other_params(opts)
+          end
+
+          private
+
+          def check_opt_preload(opts)
+            raise SeregaError, "Option :preload value can not be `true`" if opts[:preload] == true
+          end
+
+          def check_usage_with_other_params(opts)
             raise SeregaError, "Option :preload can not be used together with option :const" if opts.key?(:const)
           end
         end

data/lib/serega/validations/check_attribute_params.rb

@@ -65,7 +65,6 @@ class Serega
           Attribute::CheckOptMethod.call(opts, block)
           Attribute::CheckOptMany.call(opts)
           Attribute::CheckOptPreload.call(opts)
-          Attribute::CheckOptPreloadPath.call(opts)
           Attribute::CheckOptSerializer.call(opts)
           Attribute::CheckOptValue.call(opts, block)
           Attribute::CheckOptBatch.call(self.class.serializer_class, opts, block)