serega 0.42.0 → 0.50.0

data/lib/serega/plan_point.rb

@@ -4,162 +4,55 @@ class Serega
   #
   # Combines attribute and nested attributes
   #
-  # @private
-  class SeregaPlanPoint
-    #
-    # SeregaPlanPoint instance methods
-    #
-    # @private
-    module InstanceMethods
-      # Link to current plan this point belongs to
-      # @return [SeregaAttribute] Current plan
-      attr_reader :plan
-
-      # Shows current attribute
-      # @return [SeregaAttribute] Current attribute
-      attr_reader :attribute
-
-      # Shows child plan if exists
-      # @return [SeregaPlan, nil] Attribute serialization plan
-      attr_reader :child_plan
-
-      # Child fields to serialize
-      # @return [Hash] Attributes to serialize
-      attr_reader :modifiers
-
-      #
-      # Initializes plan point
-      #
-      # @param plan [SeregaPlan] Current plan this point belongs to
-      # @param attribute [SeregaAttribute] Attribute to construct plan point
-      # @param modifiers Serialization parameters
-      # @option modifiers [Hash] :only The only attributes to serialize
-      # @option modifiers [Hash] :except Attributes to hide
-      # @option modifiers [Hash] :with Hidden attributes to serialize additionally
-      #
-      # @return [SeregaPlanPoint] New plan point
-      #
-      def initialize(plan, attribute, modifiers = nil)
-        @plan = plan
-        @attribute = attribute
-        @modifiers = modifiers
-        set_normalized_vars
-      end
-
-      # Attribute `value`
-      # @see SeregaAttribute::AttributeInstanceMethods#value
-      def value(obj, ctx, batches: nil)
-        attribute.value(obj, ctx, batches: batches)
-      end
-
-      # Attribute `name`
-      # @see SeregaAttribute::AttributeInstanceMethods#value
-      def name
-        attribute.name
-      end
-
-      # Attribute `many` option
-      # @see SeregaAttribute::AttributeInstanceMethods#many
-      def many
-        attribute.many
-      end
-
-      # Attribute `serializer` option
-      # @see SeregaAttribute::AttributeInstanceMethods#serializer
-      def serializer
-        attribute.serializer
-      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.
-      #
-      # Presenters are unwrapped first, as preload handlers work with the
-      # serialized objects themselves.
-      #
-      # @param objects [Array] objects serialized at this point's level
-      # @return [void]
-      def run_preloads(objects)
-        return unless preloads
-
-        serializer_class = self.class.serializer_class
-        objects = objects.map(&:__getobj__) if serializer_class.presenter
-
-        handler = 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.
-      #
-      # @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
+  class SeregaPlanPoint # :nodoc:
+    # Link to current plan this point belongs to
+    attr_reader :plan
+
+    # Shows current attribute
+    attr_reader :attribute
+
+    # Attribute `name`
+    attr_reader :name
+
+    # Shows child plan if exists
+    attr_reader :child_plan
+
+    # Whether the relation values of a class are collections, for a point
+    # with a child plan
+    attr_reader :collection_classes
+
+    # Initializes plan point
+    def initialize(plan, attribute, modifiers = nil)
+      @plan = plan
+      @attribute = attribute
+      @name = attribute.name
+      @child_plan = serializer ? SeregaPlan.new(serializer, self, modifiers || FROZEN_EMPTY_HASH) : nil
+      @collection_classes = @child_plan ? {}.compare_by_identity : nil
+    end
 
-      def set_normalized_vars
-        @child_plan = prepare_child_plan
-      end
+    # Attribute `many` option
+    def many
+      attribute.many
+    end
 
-      def prepare_child_plan
-        return unless serializer
+    # Attribute `serializer` option
+    def serializer
+      attribute.serializer
+    end
 
-        fields = modifiers || FROZEN_EMPTY_HASH
+    # Attribute `batch_loaders`
+    def batch_loaders
+      attribute.batch_loaders
+    end
 
-        serializer::SeregaPlan.new(self, fields)
-      end
+    # Attribute `preloads`
+    def preloads
+      attribute.preloads
     end
 
-    extend SeregaHelpers::SerializerClassHelper
-    include InstanceMethods
+    # Attribute `conditional?`
+    def conditional?
+      attribute.conditional?
+    end
   end
 end

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

@@ -2,97 +2,30 @@
 
 class Serega
   module SeregaPlugins
+    # `plugin :activerecord_preloads` loads every `:preload` of the serialized
+    # fields once, with `ActiveRecord::Associations::Preloader`
     #
-    # Plugin :activerecord_preloads
-    #
-    # Automatically preloads associations to serialized objects
-    #
-    # 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
-    #     config.auto_preload = true
-    #     plugin :activerecord_preloads
-    #   end
-    #
-    #   class AlbumSerializer < AppSerializer
-    #     # no preloads
-    #     attribute :title
-    #
-    #     # preloads :downloads, as manually specified
-    #     attribute :downloads_count, preload: :downloads, value: proc { |album| album.downloads.count }
-    #   end
-    #
-    #   class UserSerializer < AppSerializer
-    #     # no preloads
-    #     attribute :username
-    #
-    #     # preloads :user_stats, as auto_preload is enabled for :delegate attributes
-    #     attribute :comments_count, delegate: { to: :user_stats }
-    #
-    #     # preloads :albums, as auto_preload is enabled for :serializer attributes
-    #     attribute :albums, serializer: AlbumSerializer
-    #   end
-    #
-    #   UserSerializer.to_h(users)
-    #   # 1 query to load :user_stats for all users
-    #   # + 1 query to load :albums for all users
-    #   # + 1 query to load :downloads for all albums
-    #   # = 3 queries total, regardless of how many users/albums are serialized
+    # ```ruby
+    # class AppSerializer < Serega
+    #   plugin :activerecord_preloads
+    #   config.auto_preload = true
+    # end
+    # ```
     #
+    # See [ActiveRecord preloads](https://github.com/andreyruby/serega/blob/master/docs/preloads.md#activerecord).
     module ActiverecordPreloads
-      #
-      # @return [Symbol] Plugin name
-      #
-      # @private
-      def self.plugin_name
-        :activerecord_preloads
-      end
-
-      # Checks requirements to load plugin
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param opts [Hash] plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.before_load_plugin(serializer_class, **opts)
-        opts.each_key do |key|
-          raise SeregaError, "Plugin #{plugin_name.inspect} does not accept the #{key.inspect} option. No options are allowed"
+      # Adds the plugin to the serializer
+      def self.apply(serializer_class, **opts) # :nodoc:
+        unless opts.empty?
+          raise SeregaError, "Plugin :activerecord_preloads does not accept the #{opts.keys.first.inspect} option. No options are allowed"
         end
-      end
 
-      #
-      # Applies plugin code to specific serializer
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param _opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.load_plugin(serializer_class, **_opts)
         require_relative "lib/preloader"
-      end
 
-      #
-      # Registers the ActiveRecord preload handler
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param _opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.after_load_plugin(serializer_class, **_opts)
         serializer_class.preload_with do |objects, preloads|
           Preloader.preload(objects, preloads)
         end
       end
     end
-
-    register_plugin(ActiverecordPreloads.plugin_name, ActiverecordPreloads)
   end
 end

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

@@ -4,16 +4,9 @@ class Serega
   module SeregaPlugins
     module ActiverecordPreloads
       # Handles preloads for different types of initial records
-      # @private
-      class Preloader
+      class Preloader # :nodoc:
         class << self
           # Preloads associations to records
-          #
-          # @param object [Object] record(s)
-          # @param preloads [Hash] associations names
-          #
-          # @return [Object] provided object with preloaded associations
-          #
           def preload(object, preloads)
             return object if object.nil? || (object.is_a?(Array) && object.empty?)
 
@@ -23,9 +16,7 @@ class Serega
             preload_handler.preload(object, preloads)
           end
 
-          # Returns handlers which will try to check if serialized object fits for preloading using this handler
-          #
-          # @return [Array] Registered preload adapters for different types of initial records
+          # Returns handlers which will try to check if the object to serialize fits for preloading using this handler
           def handlers
             @handlers ||= [
               ActiverecordRelation,
@@ -38,47 +29,22 @@ class Serega
       end
 
       # Associations loader for prepared records
-      # @private
-      class Loader
-        # :nocov: We can check only one version of activerecord
-
+      class Loader # :nodoc:
         # Preloads associations to records
-        #
-        # @param records [Array<ActiveRecord::Base>] records
-        # @param associations [Hash] associations names
-        #
-        # @return [void]
-        #
         def self.call(records, associations)
-          if ActiveRecord::VERSION::MAJOR >= 7
-            ActiveRecord::Associations::Preloader.new(records: records, associations: associations).call
-          else
-            ActiveRecord::Associations::Preloader.new.preload(records, associations)
-          end
+          ActiveRecord::Associations::Preloader.new(records: records, associations: associations).call
         end
-        # :nocov:
       end
 
       # Preloader adapter for ActiveRecord object
-      # @private
-      class ActiverecordObject
+      class ActiverecordObject # :nodoc:
         class << self
-          #
           # Checks object is kind of ActiveRecord::Base
-          #
-          # @param object [Object] object
-          #
-          # @return [Boolean] whether object is kind of ActiveRecord::Base
           def fit?(object)
             object.is_a?(ActiveRecord::Base)
           end
 
-          #
           # Preloads associations to ActiveRecord::Base record
-          #
-          # @param record [ActiveRecord::Base] record
-          #
-          # @return [Object] provided record with preloaded associations
           def preload(record, preloads)
             Loader.call([record], preloads)
             record
@@ -87,25 +53,14 @@ class Serega
       end
 
       # Preloader adapter for ActiveRecord::Relation
-      # @private
-      class ActiverecordRelation
+      class ActiverecordRelation # :nodoc:
         class << self
-          #
           # Checks object is kind of ActiveRecord::Relation
-          #
-          # @param object [Object] object to check
-          #
-          # @return [Boolean] whether object is kind of ActiveRecord::Relation
           def fit?(object)
             object.is_a?(ActiveRecord::Relation)
           end
 
-          #
           # Preloads associations to ActiveRecord::Relation
-          #
-          # @param scope [ActiveRecord::Relation] scope
-          #
-          # @return [ActiveRecord::Relation] provided scope with preloaded associations
           def preload(scope, preloads)
             scope.load
             Loader.call(scope.to_a, preloads)
@@ -115,27 +70,16 @@ class Serega
       end
 
       # Preloader adapter for Array of ActiveRecord objects
-      # @private
-      class ActiverecordArray
+      class ActiverecordArray # :nodoc:
         class << self
-          #
           # Checks object is an array of ActiveRecord::Base objects
-          #
-          # @param object [Object] object
-          #
-          # @return [Boolean] whether object is an array with ActiveRecord objects (and all objects have same class)
           def fit?(object)
             object.is_a?(Array) &&
               ActiverecordObject.fit?(object.first) &&
               same_kind?(object)
           end
 
-          #
           # Preloads associations to array with ActiveRecord::Base objects
-          #
-          # @param records [Array<ActiveRecord::Base>] ActiveRecord records
-          #
-          # @return [Array<ActiveRecord::Base>] provided records with preloaded associations
           def preload(records, preloads)
             Loader.call(records, preloads)
             records
@@ -151,26 +95,15 @@ class Serega
       end
 
       # Preloader adapter for Enumerator with ActiveRecord objects
-      # @private
-      class ActiverecordEnumerator
+      class ActiverecordEnumerator # :nodoc:
         class << self
-          #
           # Checks object is an Enumerator with each value is a ActiveRecord::Base object
-          #
-          # @param object [Object] object
-          #
-          # @return [Boolean] whether object is an Enumerator with each value is a ActiveRecord::Base object
           def fit?(object)
             object.is_a?(Enumerator) &&
               ActiverecordArray.fit?(object.to_a)
           end
 
-          #
           # Preloads associations to Enumerator with ActiveRecord::Base objects
-          #
-          # @param enum [Enumerator<ActiveRecord::Base>] enum
-          #
-          # @return [Enumerator<ActiveRecord::Base>] provided enumerator with preloaded associations
           def preload(enum, preloads)
             ActiverecordArray.preload(enum.to_a, preloads)
             enum