serega 0.36.0 → 0.37.0

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/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

@@ -69,10 +69,6 @@ class Serega
     # SeregaPlan instance methods
     #
     module InstanceMethods
-      # Shows if plan includes batch points
-      # @return [Array<SeregaPlanPoint>] points to serialize
-      attr_reader :has_batch_points
-
       # Parent plan point
       # @return [SeregaPlanPoint, nil]
       attr_reader :parent_plan_point
@@ -100,7 +96,6 @@ 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] }
@@ -113,6 +108,15 @@ 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.
       #
@@ -122,17 +126,6 @@ class Serega
         @data_class ||= self.class.data_class_for(point_names)
       end
 
-      #
-      # Marks current plan and top-level plans as `has_batch_points`
-      # It is needed to initialize Batch Attribute Loaders when serialization starts
-      #
-      def mark_as_has_batch_points
-        return if has_batch_points
-
-        @has_batch_points = true
-        parent_plan_point.plan.mark_as_has_batch_points if parent_plan_point # rubocop:disable Style/SafeNavigation
-      end
-
       private
 
       def attributes_points(modifiers)

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/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)

data/lib/serega.rb

@@ -21,10 +21,7 @@ require_relative "serega/errors"
 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/format_user_preloads"
 require_relative "serega/utils/method_signature"
-require_relative "serega/utils/preload_paths"
-require_relative "serega/utils/preloads_constructor"
 require_relative "serega/utils/symbol_name"
 require_relative "serega/utils/to_hash"
 require_relative "serega/attribute_value_resolvers/batch"
@@ -35,6 +32,7 @@ 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/validations/utils/check_allowed_keys"
 require_relative "serega/validations/utils/check_opt_is_bool"
@@ -49,7 +47,6 @@ require_relative "serega/validations/attribute/check_opt_batch"
 require_relative "serega/validations/attribute/check_opt_many"
 require_relative "serega/validations/attribute/check_opt_method"
 require_relative "serega/validations/attribute/check_opt_preload"
-require_relative "serega/validations/attribute/check_opt_preload_path"
 require_relative "serega/validations/attribute/check_opt_serializer"
 require_relative "serega/validations/attribute/check_opt_value"
 require_relative "serega/validations/initiate/check_modifiers"
@@ -220,6 +217,38 @@ class Serega
       batch_loaders[batch_loader.name] = batch_loader
     end
 
+    #
+    # Registers (or returns) the handler used to preload an attribute's
+    # associations onto the records gathered during serialization.
+    #
+    # The handler is called once per preloaded attribute with the gathered
+    # objects and that attribute's preloads. ORM plugins register a handler
+    # that performs the actual eager loading.
+    #
+    # @example with a block
+    #   preload_with { |objects, preloads| MyORM.eager_load(objects, preloads) }
+    #
+    # @example with a callable value
+    #   preload_with MyPreloader
+    #
+    # @param value [#call, nil] Preload handler accepting two positional arguments
+    # @param block [Proc] Preload handler accepting two positional arguments
+    #
+    # @return [#call, nil] The registered preload handler
+    #
+    def preload_with(value = nil, &block)
+      return @preload_with if value.nil? && block.nil?
+      raise SeregaError, "preload_with accepts a single callable or a block, not both" if value && block
+
+      handler = value || block
+      raise SeregaError, "preload_with value must be a Proc or respond to #call" if !handler.is_a?(Proc) && !handler.respond_to?(:call)
+
+      signature = SeregaUtils::MethodSignature.call(handler, pos_limit: 2)
+      raise SeregaError, "preload_with handler must accept two positional arguments: (objects, preloads)" unless signature == "2"
+
+      @preload_with = handler
+    end
+
     #
     # Serializes provided object to Hash
     #
@@ -342,6 +371,9 @@ class Serega
         subclass.batch(loader.name, loader.block)
       end
 
+      # Assign same preload handler
+      subclass.preload_with(preload_with) if preload_with
+
       super
     end
   end
@@ -418,11 +450,6 @@ class Serega
       self.class::SeregaDataBuilder.call(self, serialized_data)
     end
 
-    # @return [Hash] merged preloads of all serialized attributes
-    def preloads
-      @preloads ||= SeregaUtils::PreloadsConstructor.call(plan)
-    end
-
     private
 
     attr_reader :opts
@@ -453,20 +480,19 @@ class Serega
       self.class::CheckSerializeParams.new(opts).validate unless opts.empty?
 
       opts[:context] ||= {}
-      opts[:batch_loaders] = SeregaBatch::AttributeLoaders.new if plan.has_batch_points
+      opts[:batch_loaders] = SeregaBatch::AttributeLoaders.new(opts[:context])
       opts[:many] = object.is_a?(Enumerable) unless opts.key?(:many)
       opts[:plan] = plan
       opts
     end
 
     # Patched in:
-    # - plugin :activerecord_preloads (loads defined :preloads to object)
     # - plugin :root (wraps result `{ root => result }`)
     # - plugin :context_metadata (adds context metadata to final result)
     # - 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[:context])
+      opts[:batch_loaders].load_all
       result
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.36.0
+  version: 0.37.0
 platform: ruby
 authors:
 - Andrey Glushkov
@@ -35,6 +35,7 @@ files:
 - 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
@@ -45,7 +46,6 @@ files:
 - lib/serega/plan_point.rb
 - lib/serega/plugins.rb
 - lib/serega/plugins/activerecord_preloads/activerecord_preloads.rb
-- lib/serega/plugins/activerecord_preloads/lib/active_record_objects.rb
 - lib/serega/plugins/activerecord_preloads/lib/preloader.rb
 - lib/serega/plugins/camel_case/camel_case.rb
 - lib/serega/plugins/context_metadata/context_metadata.rb
@@ -73,10 +73,7 @@ files:
 - lib/serega/plugins/string_modifiers/string_modifiers.rb
 - lib/serega/utils/enum_deep_dup.rb
 - lib/serega/utils/enum_deep_freeze.rb
-- lib/serega/utils/format_user_preloads.rb
 - lib/serega/utils/method_signature.rb
-- lib/serega/utils/preload_paths.rb
-- lib/serega/utils/preloads_constructor.rb
 - lib/serega/utils/symbol_name.rb
 - lib/serega/utils/to_hash.rb
 - lib/serega/validations/attribute/check_block.rb
@@ -88,7 +85,6 @@ files:
 - lib/serega/validations/attribute/check_opt_many.rb
 - lib/serega/validations/attribute/check_opt_method.rb
 - lib/serega/validations/attribute/check_opt_preload.rb
-- lib/serega/validations/attribute/check_opt_preload_path.rb
 - lib/serega/validations/attribute/check_opt_serializer.rb
 - lib/serega/validations/attribute/check_opt_value.rb
 - lib/serega/validations/check_attribute_params.rb
@@ -122,7 +118,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.13
 specification_version: 4
 summary: JSON Serializer
 test_files: []

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

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    module ActiverecordPreloads
-      # Detects and returns found ActiveRecord objects
-      class ActiveRecordObjects
-        class << self
-          # Iterates over provided data and selects ActiveRecord objects
-          # @param data [Hash,Array,Object] any data
-          # @return [Array] Found ActiveRecord objects
-          def call(data)
-            res = []
-            extract(data, res)
-            res
-          end
-
-          private
-
-          def extract(data, res)
-            case data
-            when ActiveRecord::Base then res << data
-            when Array then data.each { |value| extract(value, res) }
-            when Hash then data.each_value { |value| extract(value, res) }
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/serega/utils/format_user_preloads.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaUtils
-    #
-    # Utility that helps to transform user provided preloads to hash
-    #
-    class FormatUserPreloads
-      class << self
-        #
-        # Transforms user provided preloads to hash
-        #
-        # @param value [Array,Hash,String,Symbol,nil,false] preloads
-        #
-        # @return [Hash] preloads transformed to hash
-        #
-        def call(value)
-          case value
-          when Array then array_to_hash(value)
-          when FalseClass then nil_to_hash(value)
-          when Hash then hash_to_hash(value)
-          when NilClass then nil_to_hash(value)
-          when String then string_to_hash(value)
-          when Symbol then symbol_to_hash(value)
-          else raise Serega::SeregaError,
-            "Preload option value can consist from Symbols, Arrays, Hashes (#{value.class} #{value.inspect} was provided)"
-          end
-        end
-
-        private
-
-        def array_to_hash(values)
-          values.each_with_object({}) do |value, obj|
-            obj.merge!(call(value))
-          end
-        end
-
-        def hash_to_hash(values)
-          values.each_with_object({}) do |(key, value), obj|
-            obj[key.to_sym] = call(value)
-          end
-        end
-
-        def nil_to_hash(_value)
-          {}
-        end
-
-        def string_to_hash(value)
-          {value.to_sym => {}}
-        end
-
-        def symbol_to_hash(value)
-          {value => {}}
-        end
-      end
-    end
-  end
-end

data/lib/serega/utils/preload_paths.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaUtils
-    #
-    # Utility that helps to transform preloads to array of paths
-    # It is used to validate manually set `:preload_path` attribute option has one of allowed values.
-    # `:preload_path` option can be used to specify where nested preloads must be attached.
-    #
-    # Example:
-    #
-    #   call({ a: { b: { c: {}, d: {} } }, e: {} })
-    #
-    #   => [
-    #        [:a],
-    #        [:a, :b],
-    #        [:a, :b, :c],
-    #        [:a, :b, :d],
-    #        [:e]
-    #      ]
-    class PreloadPaths
-      class << self
-        #
-        # Transforms user provided preloads to array of paths
-        #
-        # @param preloads [Array,Hash,String,Symbol,nil,false] association(s) to preload
-        #
-        # @return [Array] transformed preloads
-        #
-        def call(preloads)
-          formatted_preloads = FormatUserPreloads.call(preloads)
-          return FROZEN_EMPTY_ARRAY if formatted_preloads.empty?
-
-          paths(formatted_preloads, [], [])
-        end
-
-        private
-
-        def paths(formatted_preloads, path, result)
-          formatted_preloads.each do |key, nested_preloads|
-            path << key
-            result << path.dup
-
-            paths(nested_preloads, path, result)
-            path.pop
-          end
-
-          result
-        end
-      end
-    end
-  end
-end

data/lib/serega/utils/preloads_constructor.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaUtils
-    #
-    # Finds preloads for provided attributes plan
-    #
-    class PreloadsConstructor
-      class << self
-        #
-        # Constructs preloads hash for given attributes plan
-        #
-        # @param plan [Array<SeregaPlanPoint>] Serialization plan
-        #
-        # @return [Hash]
-        #
-        def call(plan)
-          return FROZEN_EMPTY_HASH unless plan
-
-          preloads = {}
-          append_many(preloads, plan)
-          preloads
-        end
-
-        private
-
-        def append_many(preloads, plan)
-          plan.points.each do |point|
-            current_preloads = point.attribute.preloads
-            next unless current_preloads
-
-            child_plan = point.child_plan
-            current_preloads = SeregaUtils::EnumDeepDup.call(current_preloads) if child_plan
-            append_current(preloads, current_preloads)
-            next unless child_plan
-
-            each_child_preloads(preloads, point.preloads_path) do |child_preloads|
-              append_many(child_preloads, child_plan)
-            end
-          end
-        end
-
-        def append_current(preloads, current_preloads)
-          merge(preloads, current_preloads) unless current_preloads.empty?
-        end
-
-        def merge(preloads, current_preloads)
-          preloads.merge!(current_preloads) do |_key, value_one, value_two|
-            merge(value_one, value_two)
-          end
-        end
-
-        def each_child_preloads(preloads, preloads_path)
-          return yield(preloads) if preloads_path.nil?
-
-          if preloads_path[0].is_a?(Array)
-            preloads_path.each do |path|
-              yield dig_fetch(preloads, path)
-            end
-          else
-            yield dig_fetch(preloads, preloads_path)
-          end
-        end
-
-        def dig_fetch(preloads, preloads_path)
-          return preloads if !preloads_path || preloads_path.empty?
-
-          preloads_path.each do |path|
-            preloads = preloads.fetch(path)
-          end
-
-          preloads
-        end
-      end
-    end
-  end
-end