serega 0.21.0 → 0.30.0

data/lib/serega/attribute_normalizer.rb

@@ -54,6 +54,15 @@ class Serega
         @value_block ||= prepare_value_block
       end
 
+      #
+      # Detects value block parameters signature
+      #
+      # @return [String] value block parameters signature
+      #
+      def value_block_signature
+        @value_block_signature ||= SeregaUtils::MethodSignature.call(value_block, pos_limit: 2, keyword_args: [:ctx])
+      end
+
       #
       # Shows if attribute is specified to be hidden
       #
@@ -99,34 +108,72 @@ class Serega
         @default = prepare_default
       end
 
-      private
+      #
+      # Shows normalized preloads for current attribute
+      #
+      # @return [Hash, nil] normalized preloads of current attribute
+      #
+      def preloads
+        return @preloads if instance_variable_defined?(:@preloads)
 
-      def prepare_name
-        init_name.to_sym
+        @preloads = prepare_preloads
       end
 
       #
-      # Patched in:
-      # - plugin :formatters (wraps resulted block in formatter block and formats :const values)
+      # Shows normalized preloads_path for current attribute
       #
-      def prepare_value_block
-        value_block =
-          prepare_init_block ||
-          prepare_value_option_block ||
-          prepare_const_block ||
-          prepare_delegate_block ||
-          prepare_keyword_block
+      # @return [Array] normalized preloads_path of current attribute
+      #
+      def preloads_path
+        return @preloads_path if instance_variable_defined?(:@preloads_path)
 
-        prepare_value_block_with_default(value_block)
+        @preloads_path = prepare_preloads_path
       end
 
+      # Shows specified batch loaders names
+      # @return [Array<Symbol>] specified serializer
       #
-      # Patched in:
-      # - plugin :preloads (returns true by default if config option auto_hide_attribute_with_preloads is enabled)
-      # - plugin :batch (returns true by default if auto_hide option was set and attribute has batch loader)
-      #
+      def batch_loaders
+        @batch_loaders ||= prepare_batch_loaders
+      end
+
+      private
+
+      def prepare_name
+        init_name.to_sym
+      end
+
+      def prepare_value_block
+        init_block \
+          || init_opts[:value] \
+          || prepare_const_block \
+          || prepare_delegate_block \
+          || prepare_batch_loader_block \
+          || prepare_keyword_block
+      end
+
       def prepare_hide
-        init_opts[:hide]
+        # Return provided durectly value
+        hide = init_opts[:hide]
+        return hide if (hide == true) || (hide == false)
+
+        # Auto hide when `:preload` option provided
+        if config.auto_hide.fetch(:has_preload_option)
+          return true if preloads
+        end
+
+        # Auto hide when `:batch` option provided
+        if config.auto_hide.fetch(:has_batch_option)
+          return true if batch_loaders.any?
+        end
+
+        # Return nil for undefined value which means "not hide" but allows
+        # to change this value by plugins
+        nil
+      end
+
+      def config
+        self.class.serializer_class.config
       end
 
       def prepare_many
@@ -155,35 +202,30 @@ class Serega
         end
       end
 
-      def prepare_init_block
-        prepare_callable_proc(init_block)
-      end
+      def prepare_batch_loader_block
+        batch_opt = init_opts[:batch]
+        return unless batch_opt
 
-      def prepare_value_option_block
-        prepare_callable_proc(init_opts[:value])
+        SeregaBatch::AutoResolverFactory.get(self.class.serializer_class, name, batch_opt)
       end
 
-      def prepare_callable_proc(callable)
-        return unless callable
-
-        params_count = SeregaUtils::ParamsCount.call(callable, max_count: 2)
-        case params_count
-        when 0 then proc { |obj, _ctx| callable.call }
-        when 1 then proc { |obj, _ctx| callable.call(obj) }
-        else callable
+      def prepare_batch_loaders
+        batch_opt = init_opts[:batch]
+
+        if batch_opt.nil?
+          []
+        elsif batch_opt == true || batch_opt.respond_to?(:call)
+          [name]
+        elsif batch_opt.is_a?(Symbol)
+          [batch_opt]
+        elsif batch_opt.is_a?(String)
+          [batch_opt.to_sym]
+        else
+          use_opt = batch_opt.fetch(:use)
+          use_opt.respond_to?(:call) ? [name] : Array(use_opt).map(&:to_sym)
         end
       end
 
-      def prepare_value_block_with_default(callable)
-        default_value = default
-        return callable if default_value.nil?
-
-        proc { |obj, ctx|
-          res = callable.call(obj, ctx)
-          res.nil? ? default_value : res
-        }
-      end
-
       def prepare_default
         init_opts.fetch(:default) { many ? FROZEN_EMPTY_ARRAY : nil }
       end
@@ -195,7 +237,7 @@ class Serega
         key_method_name = delegate[:method] || method_name
         delegate_to = delegate[:to]
 
-        allow_nil = delegate.fetch(:allow_nil) { self.class.serializer_class.config.delegate_default_allow_nil }
+        allow_nil = delegate.fetch(:allow_nil) { config.delegate_default_allow_nil }
 
         if allow_nil
           proc do |object|
@@ -207,6 +249,65 @@ class Serega
           end
         end
       end
+
+      # Prepares preloads
+      # @return [Hash,nil]
+      #  - Nil means no need to add preloads and nested preloads
+      #  - Hash with any keys will add preloads
+      #  - Empty hash will skip only top-level preloads, but will allow to load nested preloads
+      def prepare_preloads
+        preload = init_opts[:preload]
+
+        # Handle explicit preload option
+        if init_opts.key?(:preload)
+          return nil unless preload # return nil when false or nil
+          return SeregaUtils::FormatUserPreloads.call(preload)
+        end
+
+        # Auto-preload for delegate
+        if init_opts[:delegate] && config.auto_preload.fetch(:has_delegate_option)
+          delegate_to = init_opts[:delegate][:to]
+          return SeregaUtils::FormatUserPreloads.call(delegate_to)
+        end
+
+        # Auto-preload for serializer
+        if init_opts[:serializer] && config.auto_preload.fetch(:has_serializer_option)
+          return SeregaUtils::FormatUserPreloads.call(name)
+        end
+
+        nil
+      end
+
+      def prepare_preloads_path
+        path = init_opts.fetch(:preload_path) { default_preload_path(preloads) }
+
+        if path && path[0].is_a?(Array)
+          prepare_many_preload_paths(path)
+        else
+          prepare_one_preload_path(path)
+        end
+      end
+
+      def prepare_one_preload_path(path)
+        return unless path
+
+        case path
+        when Array
+          path.map(&:to_sym).freeze
+        else
+          [path.to_sym].freeze
+        end
+      end
+
+      def prepare_many_preload_paths(paths)
+        paths.map { |path| prepare_one_preload_path(path) }.freeze
+      end
+
+      def default_preload_path(preloads)
+        return FROZEN_EMPTY_ARRAY if !preloads || preloads.empty?
+
+        [preloads.keys.first]
+      end
     end
 
     extend Serega::SeregaHelpers::SerializerClassHelper

data/lib/serega/batch/attribute_loader.rb

@@ -0,0 +1,70 @@
+# 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]
+        def initialize(point)
+          @point = point
+          @objects = []
+          @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)
+          objects << object
+          serialized_object_attachers[object] = attacher
+        end
+
+        # Loads serialized values for all stored objects for current attribute
+        # @param context [Hash] Current serialization context
+        # @return [void]
+        def load_all(context)
+          batches = {}
+          serializer_class = point.class.serializer_class
+
+          point.batch_loaders.each do |batch_loader_name|
+            batches[batch_loader_name] ||= load_one(serializer_class, batch_loader_name, context)
+          end
+
+          serialized_object_attachers.each do |object, attacher|
+            attacher.call(object, batches)
+          end
+        end
+
+        private
+
+        # Patched in:
+        # - plugin :activerecord_preloads (preloads associations to found AR objects)
+        def load_one(serializer_class, batch_loader_name, context)
+          serializer_class.batch_loaders[batch_loader_name].load(objects, context)
+        rescue => error
+          reraise_with_serialized_attribute_details(error)
+        end
+
+        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 :point
+        attr_reader :objects
+        attr_reader :serialized_object_attachers
+      end
+
+      extend SeregaHelpers::SerializerClassHelper
+      include InstanceMethods
+    end
+  end
+end

data/lib/serega/batch/attribute_loaders.rb

@@ -0,0 +1,59 @@
+# 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
+      #
+      def initialize
+        @point_batch_loaders = []
+        @point_index = {}.compare_by_identity
+      end
+
+      # Remembers data for batch seryalization:
+      #
+      # @param point [SeregaPlanPoint] Serialization plan point
+      # @param object [Object] Serialized object
+      # @param attacher [Proc] Serialized value attacher
+      #
+      # @return [void]
+      def remember(point, object, attacher)
+        point_batch_loader = point_index[point]
+
+        unless point_batch_loader
+          serializer_class = point.class.serializer_class
+          point_batch_loader = serializer_class::SeregaBatchAttributeLoader.new(point)
+          point_batch_loaders << point_batch_loader
+          point_index[point] = point_batch_loader
+        end
+
+        point_batch_loader.store(object, attacher)
+      end
+
+      #
+      # Loads all registered batches and removes them from registered list
+      #
+      def load_all(context)
+        point_batch_loaders.each do |point_batch_loader|
+          point_batch_loader.load_all(context)
+        end
+      end
+
+      private
+
+      # keeps all point_batch_loaders list
+      attr_reader :point_batch_loaders
+
+      # keeps tracking of already added serializers
+      attr_reader :point_index
+    end
+  end
+end

data/lib/serega/batch/auto_resolver.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaBatch
+    #
+    # Automatically generated resolver for batch_loader
+    #
+    class AutoResolver
+      attr_reader :loader_name
+      attr_reader :id_method
+
+      def initialize(loader_name, id_method)
+        @loader_name = loader_name
+        @id_method = id_method
+      end
+
+      # Finds object attribute value from hash of batch_loaded values for all
+      # serialized objects
+      def call(obj, batches:)
+        batches.fetch(loader_name)[obj.public_send(id_method)]
+      end
+    end
+  end
+end

data/lib/serega/batch/auto_resolver_factory.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaBatch
+    #
+    # Factory generates callable object that should be able to take
+    # batch loaded results, current object, and find attribute value for this
+    # object
+    #
+    class AutoResolverFactory
+      #
+      # Generates callable block to find attribute value when attribute with :batch
+      # option has no block or manual :value option.
+      #
+      # It handles this cases:
+      # - `attribute :foo, batch: true`
+      # - `attribute :foo, batch: FooLoader`
+      # - `attribute :foo, batch: { id: :foo_id }`
+      # - `attribute :foo, batch: { use: FooLoader, id: foo_id }`
+      # - `attribute :foo, batch: { use: :foo_loader, id: foo_id }`
+      #
+      # In other cases we should never call tis method here.
+      #
+      def self.get(serializer_class, attribute_name, batch_opt)
+        if batch_opt == true                        # ex: `batch: true`
+          loader_name = attribute_name
+          loader_id_method = :id
+        elsif batch_opt.respond_to?(:call)          # ex: `batch: FooLoader`
+          serializer_class.batch_loader(attribute_name, batch_opt)
+          loader_name = attribute_name
+          loader_id_method = :id
+        else
+          use = batch_opt[:use]
+          loader_id_method = batch_opt[:id] || :id
+
+          if use.respond_to?(:call)                 # ex: `batch: { use: FooLoader }`
+            loader_name = attribute_name
+            serializer_class.batch_loader(loader_name, use)
+          else                                      # ex: `batch: { use: :foo }` || batch: { id: :some_id }
+            loader_name = use || attribute_name
+          end
+        end
+
+        AutoResolver.new(loader_name, loader_id_method)
+      end
+    end
+  end
+end

data/lib/serega/batch/loader.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+class Serega
+  #
+  # Batch feature main module
+  #
+  module SeregaBatch
+    #
+    #  Batch loader
+    #
+    class Loader
+      #
+      # BatchLoader instance methods
+      #
+      module InstanceMethods
+        # BatchLoader initial params
+        # @return [Hash] BatchLoader initial params
+        attr_reader :initials
+
+        # BatchLoader name
+        # @return [Symbol] BatchLoader name
+        attr_reader :name
+
+        # BatchLoader block
+        # @return [#call] BatchLoader block
+        attr_reader :block
+
+        #
+        # Initializes new batch loader
+        #
+        # @param name [Symbol, String] Name of attribute
+        # @param block [#call] BatchLoader block
+        #
+        def initialize(name:, block:)
+          serializer_class = self.class.serializer_class
+          serializer_class::CheckBatchLoaderParams.new(name, block).validate
+
+          @initials = SeregaUtils::EnumDeepFreeze.call(name: name, block: block)
+          @name = name.to_sym
+          @block = block
+          @signature = SeregaUtils::MethodSignature.call(block, pos_limit: 2, keyword_args: [:ctx])
+        end
+
+        # Serializes values for objects
+        # @param objects [Array] Serialized objects
+        # @param context [Hash] Serialization context
+        # @return [void]
+        def load(objects, context)
+          case signature
+          when "1" then block.call(objects)
+          when "2" then block.call(objects, context)
+          else block.call(objects, ctx: context) # "1_ctx"
+          end
+        end
+
+        private
+
+        # BatchLoader block signature
+        # @return [String] BatchLoader block signature
+        attr_reader :signature
+      end
+
+      extend SeregaHelpers::SerializerClassHelper
+      include InstanceMethods
+    end
+  end
+end

data/lib/serega/config.rb

@@ -13,12 +13,30 @@ class Serega
     DEFAULTS = {
       plugins: [],
       initiate_keys: %i[only with except check_initiate_params].freeze,
-      attribute_keys: %i[method value serializer many hide const delegate default].freeze,
+      attribute_keys: %i[
+        method
+        value
+        serializer
+        many
+        hide
+        const
+        delegate
+        default
+        preload
+        preload_path
+        batch
+      ].freeze,
       serialize_keys: %i[context many].freeze,
       check_attribute_name: true,
       check_initiate_params: true,
       delegate_default_allow_nil: false,
       max_cached_plans_per_serializer_count: 0,
+      auto_preload: {has_delegate_option: false, has_serializer_option: false},
+      auto_hide: {has_preload_option: false, has_batch_option: false},
+      # auto_preload_attributes_with_delegate: false,
+      # auto_preload_attributes_with_serializer: false,
+      # auto_hide_attributes_with_preload: false,
+      # hide_batch_attributes: false,
       to_json: (SeregaJSON.adapter == :oj) ? SeregaJSON::OjDump : SeregaJSON::JSONDump,
       from_json: (SeregaJSON.adapter == :oj) ? SeregaJSON::OjLoad : SeregaJSON::JSONLoad
     }.freeze
@@ -102,6 +120,46 @@ class Serega
         opts[:delegate_default_allow_nil] = value
       end
 
+      # @return [Hash] auto_hide option
+      def auto_hide
+        opts.fetch(:auto_hide)
+      end
+
+      # Validates and sets auto_hide option
+      # @return [Hash] New auto_hide option with attributes that trigger auto hide
+      def auto_hide=(value)
+        opts[:auto_hide] =
+          case value
+          when true then {has_preload_option: true, has_batch_option: true}
+          when false then {has_preload_option: false, has_batch_option: false}
+          when Hash
+            SeregaValidations::Utils::CheckAllowedKeys.call(value, %i[has_preload_option has_batch_option], "auto_hide")
+            {has_preload_option: !!value[:has_preload_option], has_batch_option: !!value[:has_batch_option]}
+          else
+            raise SeregaError, "Must have boolean value or Hash, #{value.inspect} provided"
+          end
+      end
+
+      # @return [Hash] auto_preload option
+      def auto_preload
+        opts.fetch(:auto_preload)
+      end
+
+      # Validates and sets auto_preload option
+      # @return [Hash] New auto_preload option with attributes that trigger auto preload
+      def auto_preload=(value)
+        opts[:auto_preload] =
+          case value
+          when true then {has_delegate_option: true, has_serializer_option: true}
+          when false then {has_delegate_option: false, has_serializer_option: false}
+          when Hash
+            SeregaValidations::Utils::CheckAllowedKeys.call(value, %i[has_delegate_option has_serializer_option], "auto_preload")
+            {has_delegate_option: !!value[:has_delegate_option], has_serializer_option: !!value[:has_serializer_option]}
+          else
+            raise SeregaError, "Must have boolean value or Hash, #{value.inspect} provided"
+          end
+      end
+
       # Returns :max_cached_plans_per_serializer_count config option
       # @return [Boolean] Current :max_cached_plans_per_serializer_count config option
       def max_cached_plans_per_serializer_count

data/lib/serega/object_serializer.rb

@@ -10,7 +10,7 @@ class Serega
     # SeregaObjectSerializer instance methods
     #
     module InstanceMethods
-      attr_reader :context, :plan, :many, :opts
+      attr_reader :context, :plan, :many, :opts, :batch_loaders
 
       # @param plan [SeregaPlan] Serialization plan
       # @param context [Hash] Serialization context
@@ -23,6 +23,7 @@ class Serega
         @plan = plan
         @many = many
         @opts = opts
+        @batch_loaders = opts[:batch_loaders]
       end
 
       # Serializes object(s)
@@ -47,8 +48,6 @@ class Serega
       def serialize_object(object)
         plan.points.each_with_object({}) do |point, container|
           serialize_point(object, point, container)
-        rescue SeregaError
-          raise
         rescue => error
           reraise_with_serialized_attribute_details(error, point)
         end
@@ -57,20 +56,23 @@ class Serega
       # Patched in:
       # - plugin :if (conditionally skips serializing this point)
       def serialize_point(object, point, container)
-        attach_value(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
       end
 
-      # Patched in:
-      # - plugin :batch (remembers key for batch loading values instead of attaching)
-      def attach_value(object, point, container)
-        value = point.value(object, context)
+      def attach_value(object, point, container, batches: nil)
+        value = point.value(object, context, batches: batches)
         final_value = final_value(value, point)
         attach_final_value(final_value, point, container)
       end
 
       # Patched in:
       # - plugin :if (conditionally skips attaching)
-      # - plugin :batch :if extension (removes prepared key)
       def attach_final_value(final_value, point, container)
         container[point.name] = final_value
       end

data/lib/serega/plan.rb

@@ -65,6 +65,10 @@ 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
+
       #
       # Instantiate new serialization plan
       #
@@ -80,6 +84,7 @@ 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)
       end
@@ -91,6 +96,17 @@ class Serega
         self.class.serializer_class
       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)