serega 0.11.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b4a68e91572d22cf24e20a79cc788f647eb63e16582f0e33497eec459692de1
-  data.tar.gz: 8d3a55c8fd783b00c55cb08ed8f62c0f47cb79573ccbdc9f65c6710489d0dd0f
+  metadata.gz: 52535c7fab3897f65aec4e156ab5681e8595b4519df1e79a777688cee486a480
+  data.tar.gz: 16adbd9f036b0e23928049df873966f264db1004d2c4c1bc9e28422d687efd12
 SHA512:
-  metadata.gz: 67cb15aafd0dd90dd301a2ae79643c93204c52c26752649f96e904d2e1fe75d37709c91474c891eb73d1ee913002c214fc2c0288a613f82ad082ee385b149338
-  data.tar.gz: c421133bba5f4be2227a266bf6eb6fa6013f0320741f4e842575823d3a6d9e93bf37e8029b9fa801b2bcede964679c19fe794a1f7f0dceb10909c98251db588b
+  metadata.gz: 93a6aaefdf954556e31bd604ead1e376d5ffbb74225251e635bf5133af53da26f47e924f1f88349fa4656e228ddca573347d9f8fa15cc30bc6052f7e5dfec3bd
+  data.tar.gz: c84135d04c79aae1ccd03a3f3ac7dbed53dbf75165575afbb61ad6e32a558318cac2a8311c31b76df90fb74823facdf4677821d8f7ae8284f04782d33b04ad41

data/README.md

@@ -415,30 +415,79 @@ UserSerializer.new(
 ```
 
 ---
-One tricky case, that you will probably never see in real life:
 
-Manually you can preload multiple associations, like this:
+#### SPECIFIC CASE #1: Serializing same object as association
+
+For example you decided to show your current user as "user" and "user_stats".
+Where stats rely on user fields and some other associations.
+You should specify `preload: nil` to preload nested associations, if any, to "user".
 
 ```ruby
-attribute :image,
-  serializer: ImageSerializer,
-  preload: { attachment: :blob },
-  value: proc { |record| record.attachment }
+class AppSerializer < Serega
+  plugin :preloads,
+    auto_preload_attributes_with_delegate: true,
+    auto_preload_attributes_with_serializer: true,
+    auto_hide_attributes_with_preload: true
+end
+
+class UserSerializer < AppSerializer
+  attribute :username
+  attribute :user_stats,
+    serializer: 'UserStatSerializer'
+    value: proc { |user| user },
+    preload: nil
+end
 ```
 
-In this case we mark last element (in this case it will be `blob`) as main,
-so nested associations, if any, will be preloaded to this `blob`.
-If you need to preload them to `attachment`,
-please specify additionally `:preload_path` option like this:
+#### SPECIFIC CASE #2: Serializing multiple associations as single relation
+
+For example "user" has two relations - "new_profile", "old_profile", and also
+profiles have "avatar" association. And you decided to serialize profiles in one
+array. You can specify `preload_path: [[:new_profile], [:old_profile]]` to
+achieve this:
+
+```ruby
+class AppSerializer < Serega
+  plugin :preloads,
+    auto_preload_attributes_with_delegate: true,
+    auto_preload_attributes_with_serializer: true
+end
+
+class UserSerializer < AppSerializer
+  attribute :username
+  attribute :profiles,
+    serializer: 'ProfileSerializer',
+    value: proc { |user| [user.new_profile, user.old_profile] },
+    preload: [:new_profile, :old_profile],
+    preload_path: [[:new_profile], [:old_profile]] # <--- like here
+end
+
+class ProfileSerializer < AppSerializer
+  attribute :avatar, serializer: 'AvatarSerializer'
+end
+
+class AvatarSerializer < AppSerializer
+end
+
+UserSerializer.new.preloads
+# => {:new_profile=>{:avatar=>{}}, :old_profile=>{:avatar=>{}}}
+```
+
+#### SPECIFIC CASE #3: Preload association through another association
 
 ```ruby
 attribute :image,
+  preload: { attachment: :blob }, # <--------- like this one
+  value: proc { |record| record.attachment },
   serializer: ImageSerializer,
-  preload: { attachment: :blob },
-  preload_path: %i[attachment],
-  value: proc { |record| record.attachment }
+  preload_path: [:attachment] # or preload_path: [:attachment, :blob]
 ```
 
+In this case we don't know if preloads defined in ImageSerializer, should be
+preloaded to `attachment` or `blob`, so please specify `preload_path` manually.
+You can specify `preload_path: nil` if you are sure that there are no preloads
+inside ImageSerializer.
+
 ---
 
 📌 Plugin `:preloads` only allows to group preloads together in single Hash, but

data/VERSION

@@ -1 +1 @@
-0.11.2
+0.12.0

data/lib/serega/attribute.rb

@@ -82,13 +82,18 @@ class Serega
       #
       # Checks if attribute must be added to serialized response
       #
-      # @param except [Hash] manually hidden attributes
-      # @param only [Hash] manually enforced exposed attributes, other attributes are enforced to be hidden
-      # @param with [Hash] manually enforced exposed attributes
+      # @param modifiers [Hash] Serialization modifiers
+      # @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 [Boolean]
       #
-      def visible?(except:, only:, with:)
+      def visible?(modifiers)
+        except = modifiers[:except] || FROZEN_EMPTY_HASH
+        only = modifiers[:only] || FROZEN_EMPTY_HASH
+        with = modifiers[:with] || FROZEN_EMPTY_HASH
+
         return false if except.member?(name) && except[name].empty?
         return true if only.member?(name)
         return true if with.member?(name)

data/lib/serega/attribute_normalizer.rb

@@ -107,6 +107,7 @@ class Serega
       #
       # 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 prepare_hide
         init_opts[:hide]
@@ -135,7 +136,7 @@ class Serega
       def prepare_keyword_block
         key_method_name = key
         proc do |object|
-          handle_no_method_error { object.public_send(key_method_name) }
+          object.public_send(key_method_name)
         end
       end
 
@@ -150,24 +151,14 @@ class Serega
 
         if allow_nil
           proc do |object|
-            handle_no_method_error do
-              object.public_send(delegate_to)&.public_send(key_method_name)
-            end
+            object.public_send(delegate_to)&.public_send(key_method_name)
           end
         else
           proc do |object|
-            handle_no_method_error do
-              object.public_send(delegate_to).public_send(key_method_name)
-            end
+            object.public_send(delegate_to).public_send(key_method_name)
           end
         end
       end
-
-      def handle_no_method_error
-        yield
-      rescue NoMethodError => error
-        raise error, "NoMethodError when serializing '#{name}' attribute in #{self.class.serializer_class}\n\n#{error.message}", error.backtrace
-      end
     end
 
     extend Serega::SeregaHelpers::SerializerClassHelper

data/lib/serega/object_serializer.rb

@@ -47,6 +47,10 @@ 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
       end
 
@@ -85,6 +89,13 @@ class Serega
       def array?(object, many)
         many.nil? ? object.is_a?(Enumerable) : many
       end
+
+      def reraise_with_serialized_attribute_details(error, point)
+        raise error.exception(<<~MESSAGE.strip)
+          #{error.message}
+          (when serializing '#{point.name}' attribute in #{self.class.serializer_class})
+        MESSAGE
+      end
     end
 
     extend Serega::SeregaHelpers::SerializerClassHelper

data/lib/serega/plan.rb

@@ -22,34 +22,22 @@ class Serega
       #
       def call(opts)
         max_cache_size = serializer_class.config.max_cached_plans_per_serializer_count
-        return plan_for(opts) if max_cache_size.zero?
+        return new(opts) if max_cache_size.zero?
 
         cached_plan_for(opts, max_cache_size)
       end
 
       private
 
-      def plan_for(opts)
-        new(**modifiers(opts))
-      end
-
       def cached_plan_for(opts, max_cache_size)
         @cache ||= {}
         cache_key = construct_cache_key(opts)
 
-        plan = @cache[cache_key] ||= plan_for(opts)
+        plan = @cache[cache_key] ||= new(opts)
         @cache.shift if @cache.length > max_cache_size
         plan
       end
 
-      def modifiers(opts)
-        {
-          only: opts[:only] || FROZEN_EMPTY_HASH,
-          except: opts[:except] || FROZEN_EMPTY_HASH,
-          with: opts[:with] || FROZEN_EMPTY_HASH
-        }
-      end
-
       def construct_cache_key(opts, cache_key = nil)
         return nil if opts.empty?
 
@@ -69,10 +57,14 @@ class Serega
     # SeregaPlan instance methods
     #
     module InstanceMethods
-      # Parent plan point, if exists
+      # Parent plan point
       # @return [SeregaPlanPoint, nil]
       attr_reader :parent_plan_point
 
+      # Sets new parent plan point
+      # @return [SeregaPlanPoint] new parent plan point
+      attr_writer :parent_plan_point
+
       # Serialization points
       # @return [Array<SeregaPlanPoint>] points to serialize
       attr_reader :points
@@ -80,17 +72,15 @@ class Serega
       #
       # Instantiate new serialization plan.
       #
-      # @param opts Serialization parameters
-      # @option opts [Hash] :only The only attributes to serialize
-      # @option opts [Hash] :except Attributes to hide
-      # @option opts [Hash] :with Attributes (usually marked hide: true`) to serialize additionally
-      # @option opts [Hash] :with Attributes (usually marked hide: true`) to serialize additionally
+      # @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 [SeregaPlan] Serialization plan
       #
-      def initialize(only:, except:, with:, parent_plan_point: nil)
-        @parent_plan_point = parent_plan_point
-        @points = attributes_points(only: only, except: except, with: with)
+      def initialize(modifiers)
+        @points = attributes_points(modifiers)
       end
 
       #
@@ -102,7 +92,10 @@ class Serega
 
       private
 
-      def attributes_points(only:, except:, with:)
+      def attributes_points(modifiers)
+        only = modifiers[:only] || FROZEN_EMPTY_HASH
+        except = modifiers[:except] || FROZEN_EMPTY_HASH
+        with = modifiers[:with] || FROZEN_EMPTY_HASH
         points = []
 
         serializer_class.attributes.each_value do |attribute|
@@ -114,7 +107,9 @@ class Serega
               {only: only[name], with: with[name], except: except[name]}
             end
 
-          points << serializer_class::SeregaPlanPoint.new(attribute, self, child_fields)
+          point = serializer_class::SeregaPlanPoint.new(attribute, child_fields)
+          point.plan = self
+          points << point.freeze
         end
 
         points.freeze

data/lib/serega/plan_point.rb

@@ -13,7 +13,7 @@ class Serega
 
       # Link to current plan this point belongs to
       # @return [SeregaAttribute] Current plan
-      attr_reader :plan
+      attr_accessor :plan
 
       # Shows current attribute
       # @return [SeregaAttribute] Current attribute
@@ -24,8 +24,8 @@ class Serega
       attr_reader :child_plan
 
       # Child fields to serialize
-      # @return [SeregaPlan, nil] Attribute serialization plan
-      attr_reader :child_fields
+      # @return [Hash] Attributes to serialize
+      attr_reader :modifiers
 
       # @!method name
       #   Attribute `name`
@@ -44,18 +44,18 @@ class Serega
       #
       # Initializes plan point
       #
-      # @param plan [SeregaPlan] Plan where this point belongs to.
       # @param attribute [SeregaAttribute] Attribute to construct plan point
-      # @param child_fields [Hash, nil] Child fields (:only, :with, :except)
+      # @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(attribute, plan = nil, child_fields = nil)
-        @plan = plan
+      def initialize(attribute, modifiers = nil)
         @attribute = attribute
-        @child_fields = child_fields
+        @modifiers = modifiers
         set_normalized_vars
-        freeze
       end
 
       #
@@ -77,14 +77,11 @@ class Serega
       def prepare_child_plan
         return unless serializer
 
-        fields = child_fields || FROZEN_EMPTY_HASH
+        fields = modifiers || FROZEN_EMPTY_HASH
 
-        serializer::SeregaPlan.new(
-          parent_plan_point: self,
-          only: fields[:only] || FROZEN_EMPTY_HASH,
-          with: fields[:with] || FROZEN_EMPTY_HASH,
-          except: fields[:except] || FROZEN_EMPTY_HASH
-        )
+        plan = serializer::SeregaPlan.new(fields)
+        plan.parent_plan_point = self
+        plan
       end
     end
 

data/lib/serega/plugins/batch/lib/loader.rb

@@ -60,6 +60,10 @@ class Serega
 
           private
 
+          def keys
+            @keys ||= {}
+          end
+
           def each_key
             keys.each do |key, containers|
               containers.each do |container|
@@ -74,16 +78,30 @@ class Serega
           def keys_values
             ids = keys.keys
 
-            point.batch[:loader].call(ids, object_serializer.context, point).tap do |vals|
-              next if vals.is_a?(Hash)
+            keys_values = load_keys_values(ids)
+            validate(keys_values)
 
-              attribute_name = "#{point.class.serializer_class}.#{point.name}"
-              raise SeregaError, "Batch loader for `#{attribute_name}` must return Hash, but #{vals.inspect} was returned"
-            end
+            keys_values
           end
 
-          def keys
-            @keys ||= {}
+          def load_keys_values(ids)
+            point.batch[:loader].call(ids, object_serializer.context, point)
+          rescue => error
+            raise reraise_with_serialized_attribute_details(error, point)
+          end
+
+          def validate(keys_values)
+            return if keys_values.is_a?(Hash)
+
+            attribute_name = "#{point.class.serializer_class}.#{point.name}"
+            raise SeregaError, "Batch loader for `#{attribute_name}` must return Hash, but #{keys_values.inspect} was returned"
+          end
+
+          def reraise_with_serialized_attribute_details(error, point)
+            raise error.exception(<<~MESSAGE.strip)
+              #{error.message}
+              (when serializing '#{point.name}' attribute in #{self.class.serializer_class})
+            MESSAGE
           end
         end
 

data/lib/serega/plugins/batch/lib/modules/attribute_normalizer.rb

@@ -49,9 +49,7 @@ class Serega
           key = batch[:key] || self.class.serializer_class.config.batch.default_key
           proc_key =
             if key.is_a?(Symbol)
-              proc do |object|
-                handle_no_method_error { object.public_send(key) }
-              end
+              proc { |object| object.public_send(key) }
             else
               key
             end
@@ -61,12 +59,6 @@ class Serega
 
           {loader: loader, key: proc_key, default: default}
         end
-
-        def handle_no_method_error
-          yield
-        rescue NoMethodError => error
-          raise error, "NoMethodError when serializing '#{name}' attribute in #{self.class.serializer_class}\n\n#{error.message}", error.backtrace
-        end
       end
     end
   end

data/lib/serega/plugins/metadata/metadata.rb

@@ -194,6 +194,11 @@ class Serega
             next unless metadata
 
             deep_merge_metadata(hash, metadata)
+          rescue => error
+            raise error.exception(<<~MESSAGE.strip)
+              #{error.message}
+              (when serializing meta_attribute #{meta_attribute.path.inspect} in #{self.class})
+            MESSAGE
           end
         end
 

data/lib/serega/plugins/preloads/lib/modules/attribute.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaAttribute additional/patched instance methods
+      #
+      # @see Serega::SeregaAttribute::AttributeInstanceMethods
+      #
+      module AttributeInstanceMethods
+        # @return [Hash, nil] normalized preloads of current attribute
+        attr_reader :preloads
+
+        # @return [Array] normalized preloads_path of current attribute
+        attr_reader :preloads_path
+
+        private
+
+        def set_normalized_vars(normalizer)
+          super
+          @preloads = normalizer.preloads
+          @preloads_path = normalizer.preloads_path
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/modules/attribute_normalizer.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaAttributeNormalizer additional/patched instance methods
+      #
+      # @see SeregaAttributeNormalizer::AttributeNormalizerInstanceMethods
+      #
+      module AttributeNormalizerInstanceMethods
+        # @return [Hash,nil] normalized attribute preloads
+        def preloads
+          return @preloads if instance_variable_defined?(:@preloads)
+
+          @preloads = prepare_preloads
+        end
+
+        # @return [Array, nil] normalized attribute preloads path
+        def preloads_path
+          return @preloads_path if instance_variable_defined?(:@preloads_path)
+
+          @preloads_path = prepare_preloads_path
+        end
+
+        private
+
+        #
+        # Patched in:
+        # - plugin :batch (extension :preloads - skips auto preloads when batch option provided)
+        #
+        def prepare_preloads
+          opts = init_opts
+          preloads_provided = opts.key?(:preload)
+          preloads =
+            if preloads_provided
+              opts[:preload]
+            elsif opts.key?(:serializer) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_serializer
+              key
+            elsif opts.key?(:delegate) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_delegate
+              opts[:delegate].fetch(:to)
+            end
+
+          # Nil and empty hash differs as we can preload nested results to
+          # empty hash, but we will skip nested preloading if nil or false provided
+          return if preloads_provided && !preloads
+
+          FormatUserPreloads.call(preloads)
+        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
+
+        #
+        # Patch for original `prepare_hide` method
+        # @see
+        #
+        # Marks attribute hidden if auto_hide_attribute_with_preloads option was set and attribute has preloads
+        #
+        def prepare_hide
+          res = super
+          return res unless res.nil?
+
+          if preloads && !preloads.empty?
+            self.class.serializer_class.config.preloads.auto_hide_attributes_with_preload || nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/modules/check_attribute_params.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
+      #
+      # @see Serega::SeregaValidations::CheckAttributeParams
+      #
+      module CheckAttributeParamsInstanceMethods
+        private
+
+        def check_opts
+          super
+          CheckOptPreload.call(opts)
+          CheckOptPreloadPath.call(opts)
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/modules/config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Config class additional/patched instance methods
+      #
+      # @see Serega::SeregaConfig
+      #
+      module ConfigInstanceMethods
+        # @return [Serega::SeregaPlugins::Preloads::PreloadsConfig] `preloads` plugin config
+        def preloads
+          @preloads ||= PreloadsConfig.new(opts.fetch(:preloads))
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/modules/plan_point.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Serega::SeregaPlanPoint additional/patched instance methods
+      #
+      # @see Serega::SeregaPlanPoint::InstanceMethods
+      #
+      module PlanPointInstanceMethods
+        #
+        # @return [Hash] preloads for nested attributes
+        #
+        attr_reader :preloads
+
+        #
+        # @return [Array<Symbol>] preloads path for current attribute
+        #
+        attr_reader :preloads_path
+
+        private
+
+        def set_normalized_vars
+          super
+
+          @preloads = prepare_preloads
+          @preloads_path = prepare_preloads_path
+        end
+
+        def prepare_preloads
+          PreloadsConstructor.call(child_plan)
+        end
+
+        def prepare_preloads_path
+          attribute.preloads_path
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/preload_paths.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Utility that helps to transform preloads to array of paths
+      #
+      # 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 value [Array,Hash,String,Symbol,nil,false] preloads
+          #
+          # @return [Hash] preloads transformed to hash
+          #
+          def call(preloads, path = [], result = [])
+            preloads = FormatUserPreloads.call(preloads)
+
+            preloads.each do |key, nested_preloads|
+              path << key
+              result << path.dup
+
+              call(nested_preloads, path, result)
+              path.pop
+            end
+
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/preloads_config.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaPlugins
+    module Preloads
+      #
+      # Config for `preloads` plugin
+      #
+      class PreloadsConfig
+        # @return [Hash] preloads plugin options
+        attr_reader :opts
+
+        #
+        # Initializes context_metadata config object
+        #
+        # @param opts [Hash] options
+        #
+        # @return [Serega::SeregaPlugins::Metadata::MetadataConfig]
+        #
+        def initialize(opts)
+          @opts = opts
+        end
+
+        # @!method auto_preload_attributes_with_delegate
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_preload_attributes_with_delegate=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        # @!method auto_preload_attributes_with_serializer
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_preload_attributes_with_serializer=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        # @!method auto_hide_attributes_with_preload
+        #   @return [Boolean, nil] option value
+        #
+        # @!method auto_hide_attributes_with_preload=(value)
+        #   @param value [Boolean] New option value
+        #   @return [Boolean] New option value
+        #
+        %i[
+          auto_preload_attributes_with_delegate
+          auto_preload_attributes_with_serializer
+          auto_hide_attributes_with_preload
+        ].each do |method_name|
+          define_method(method_name) do
+            opts.fetch(method_name)
+          end
+
+          define_method("#{method_name}=") do |value|
+            raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
+            opts[method_name] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/plugins/preloads/lib/preloads_constructor.rb

@@ -35,8 +35,9 @@ class Serega
               append_current(preloads, current_preloads)
               next unless child_plan
 
-              child_preloads = dig?(preloads, point.preloads_path)
-              append_many(child_preloads, child_plan)
+              each_child_preloads(preloads, point.preloads_path) do |child_preloads|
+                append_many(child_preloads, child_plan)
+              end
             end
           end
 
@@ -50,14 +51,26 @@ class Serega
             end
           end
 
-          def dig?(hash, path)
-            return hash if !path || path.empty?
+          def each_child_preloads(preloads, preloads_path)
+            return yield(preloads) if preloads_path.nil?
 
-            path.each do |point|
-              hash = hash[point]
+            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?
 
-            hash
+            preloads_path.each do |path|
+              preloads = preloads.fetch(path)
+            end
+
+            preloads
           end
         end
       end

data/lib/serega/plugins/preloads/preloads.rb

@@ -79,6 +79,18 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
+        require_relative "./lib/format_user_preloads"
+        require_relative "./lib/modules/attribute"
+        require_relative "./lib/modules/attribute_normalizer"
+        require_relative "./lib/modules/check_attribute_params"
+        require_relative "./lib/modules/config"
+        require_relative "./lib/modules/plan_point"
+        require_relative "./lib/preload_paths"
+        require_relative "./lib/preloads_config"
+        require_relative "./lib/preloads_constructor"
+        require_relative "./validations/check_opt_preload"
+        require_relative "./validations/check_opt_preload_path"
+
         serializer_class.include(InstanceMethods)
         serializer_class::SeregaAttribute.include(AttributeInstanceMethods)
         serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
@@ -86,12 +98,6 @@ class Serega
         serializer_class::SeregaPlanPoint.include(PlanPointInstanceMethods)
 
         serializer_class::CheckAttributeParams.include(CheckAttributeParamsInstanceMethods)
-
-        require_relative "./lib/format_user_preloads"
-        require_relative "./lib/main_preload_path"
-        require_relative "./lib/preloads_constructor"
-        require_relative "./validations/check_opt_preload"
-        require_relative "./validations/check_opt_preload_path"
       end
 
       #
@@ -125,210 +131,6 @@ class Serega
           @preloads ||= PreloadsConstructor.call(plan)
         end
       end
-
-      #
-      # Config for `preloads` plugin
-      #
-      class PreloadsConfig
-        # @return [Hash] preloads plugin options
-        attr_reader :opts
-
-        #
-        # Initializes context_metadata config object
-        #
-        # @param opts [Hash] options
-        #
-        # @return [Serega::SeregaPlugins::Metadata::MetadataConfig]
-        #
-        def initialize(opts)
-          @opts = opts
-        end
-
-        # @!method auto_preload_attributes_with_delegate
-        #   @return [Boolean, nil] option value
-        #
-        # @!method auto_preload_attributes_with_delegate=(value)
-        #   @param value [Boolean] New option value
-        #   @return [Boolean] New option value
-        #
-        # @!method auto_preload_attributes_with_serializer
-        #   @return [Boolean, nil] option value
-        #
-        # @!method auto_preload_attributes_with_serializer=(value)
-        #   @param value [Boolean] New option value
-        #   @return [Boolean] New option value
-        #
-        # @!method auto_hide_attributes_with_preload
-        #   @return [Boolean, nil] option value
-        #
-        # @!method auto_hide_attributes_with_preload=(value)
-        #   @param value [Boolean] New option value
-        #   @return [Boolean] New option value
-        #
-        %i[
-          auto_preload_attributes_with_delegate
-          auto_preload_attributes_with_serializer
-          auto_hide_attributes_with_preload
-        ].each do |method_name|
-          define_method(method_name) do
-            opts.fetch(method_name)
-          end
-
-          define_method("#{method_name}=") do |value|
-            raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
-            opts[method_name] = value
-          end
-        end
-      end
-
-      #
-      # Config class additional/patched instance methods
-      #
-      # @see Serega::SeregaConfig
-      #
-      module ConfigInstanceMethods
-        # @return [Serega::SeregaPlugins::Preloads::PreloadsConfig] `preloads` plugin config
-        def preloads
-          @preloads ||= PreloadsConfig.new(opts.fetch(:preloads))
-        end
-      end
-
-      #
-      # Serega::SeregaAttribute additional/patched instance methods
-      #
-      # @see Serega::SeregaAttribute::AttributeInstanceMethods
-      #
-      module AttributeInstanceMethods
-        # @return [Hash, nil] normalized preloads of current attribute
-        attr_reader :preloads
-
-        # @return [Array] normalized preloads_path of current attribute
-        attr_reader :preloads_path
-
-        private
-
-        def set_normalized_vars(normalizer)
-          super
-          @preloads = normalizer.preloads
-          @preloads_path = normalizer.preloads_path
-        end
-      end
-
-      #
-      # SeregaAttributeNormalizer additional/patched instance methods
-      #
-      # @see SeregaAttributeNormalizer::AttributeInstanceMethods
-      #
-      module AttributeNormalizerInstanceMethods
-        # @return [Hash,nil] normalized attribute preloads
-        def preloads
-          return @preloads if instance_variable_defined?(:@preloads)
-
-          @preloads = prepare_preloads
-        end
-
-        # @return [Array, nil] normalized attribute preloads path
-        def preloads_path
-          return @preloads_path if instance_variable_defined?(:@preloads_path)
-
-          @preloads_path = prepare_preloads_path
-        end
-
-        private
-
-        #
-        # Patched in:
-        # - plugin :batch (extension :preloads - skips auto preloads when batch option provided)
-        #
-        def prepare_preloads
-          opts = init_opts
-          preloads_provided = opts.key?(:preload)
-          preloads =
-            if preloads_provided
-              opts[:preload]
-            elsif opts.key?(:serializer) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_serializer
-              key
-            elsif opts.key?(:delegate) && self.class.serializer_class.config.preloads.auto_preload_attributes_with_delegate
-              opts[:delegate].fetch(:to)
-            end
-
-          # Nil and empty hash differs as we can preload nested results to
-          # empty hash, but we will skip nested preloading if nil or false provided
-          return if preloads_provided && !preloads
-
-          FormatUserPreloads.call(preloads)
-        end
-
-        def prepare_preloads_path
-          opts = init_opts
-          path = Array(opts[:preload_path]).map!(&:to_sym).freeze
-          path = MainPreloadPath.call(preloads) if path.empty?
-          path
-        end
-
-        #
-        # Patch for original `prepare_hide` method
-        #
-        # Marks attribute hidden if auto_hide_attribute_with_preloads option was set and attribute has preloads
-        #
-        def prepare_hide
-          res = super
-          return res unless res.nil?
-
-          if preloads && !preloads.empty?
-            self.class.serializer_class.config.preloads.auto_hide_attributes_with_preload || nil
-          end
-        end
-      end
-
-      #
-      # Serega::SeregaPlanPoint additional/patched instance methods
-      #
-      # @see Serega::SeregaPlanPoint::InstanceMethods
-      #
-      module PlanPointInstanceMethods
-        #
-        # @return [Hash] preloads for nested attributes
-        #
-        attr_reader :preloads
-
-        #
-        # @return [Array<Symbol>] preloads path for current attribute
-        #
-        attr_reader :preloads_path
-
-        private
-
-        def set_normalized_vars
-          super
-
-          @preloads = prepare_preloads
-          @preloads_path = prepare_preloads_path
-        end
-
-        def prepare_preloads
-          PreloadsConstructor.call(child_plan)
-        end
-
-        def prepare_preloads_path
-          attribute.preloads_path
-        end
-      end
-
-      #
-      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
-      #
-      # @see Serega::SeregaValidations::CheckAttributeParams
-      #
-      module CheckAttributeParamsInstanceMethods
-        private
-
-        def check_opts
-          super
-          CheckOptPreload.call(opts)
-          CheckOptPreloadPath.call(opts)
-        end
-      end
     end
 
     register_plugin(Preloads.plugin_name, Preloads)

data/lib/serega/plugins/preloads/validations/check_opt_preload_path.rb

@@ -18,30 +18,69 @@ class Serega
           # @return [void]
           #
           def call(opts)
-            return unless opts.key?(:preload_path)
+            return if exactly_nil?(opts, :preload_path) # allow to provide nil anyway
 
-            value = opts[:preload_path]
-            raise SeregaError, "Invalid option :preload_path => #{value.inspect}. Can be provided only when :preload option provided" unless opts[:preload]
-            raise SeregaError, "Invalid option :preload_path => #{value.inspect}. Can be provided only when :serializer option provided" unless opts[:serializer]
+            path = opts[:preload_path]
+            check_usage_with_other_options(path, opts)
+            return unless opts[:serializer]
 
-            path = Array(value).map!(&:to_sym)
-            preloads = FormatUserPreloads.call(opts[:preload])
-            allowed_paths = paths(preloads)
-            raise SeregaError, "Invalid option :preload_path => #{value.inspect}. Can be one of #{allowed_paths.inspect[1..-2]}" unless allowed_paths.include?(path)
+            check_allowed(path, opts)
           end
 
           private
 
-          def paths(preloads, path = [], result = [])
-            preloads.each do |key, nested_preloads|
-              path << key
-              result << path.dup
+          def exactly_nil?(opts, opt_name)
+            opts.fetch(opt_name, false).nil?
+          end
+
+          def check_allowed(path, opts)
+            allowed_paths = PreloadPaths.call(opts[:preload])
+            check_required_when_many_allowed(path, allowed_paths)
+            check_in_allowed(path, allowed_paths)
+          end
+
+          def check_usage_with_other_options(path, opts)
+            return unless path
+
+            preload = opts[:preload]
+            raise SeregaError, "Invalid option preload_path: #{path.inspect}. Can be provided only when :preload option provided" unless preload
 
-              paths(nested_preloads, path, result)
-              path.pop
+            serializer = opts[:serializer]
+            raise SeregaError, "Invalid option preload_path: #{path.inspect}. Can be provided only when :serializer option provided" unless serializer
+          end
+
+          def check_required_when_many_allowed(path, allowed)
+            return if path || (allowed.size < 2)
+
+            raise SeregaError, "Option :preload_path must be provided. Possible values: #{allowed.inspect[1..-2]}"
+          end
+
+          def check_in_allowed(path, allowed)
+            return if !path && allowed.size <= 1
+
+            if multiple_preload_paths_provided?(path)
+              check_many(path, allowed)
+            else
+              check_one(path, allowed)
             end
+          end
+
+          def check_one(path, allowed)
+            formatted_path = Array(path).map(&:to_sym)
+            return if allowed.include?(formatted_path)
+
+            raise SeregaError,
+              "Invalid preload_path (#{path.inspect}). " \
+              "Can be one of #{allowed.inspect[1..-2]}"
+          end
+
+          def check_many(paths, allowed)
+            paths.each { |path| check_one(path, allowed) }
+          end
 
-            result
+          # Check value is Array in Array
+          def multiple_preload_paths_provided?(value)
+            value.is_a?(Array) && value[0].is_a?(Array)
           end
         end
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.11.2
+  version: 0.12.0
 platform: ruby
 authors:
 - Andrey Glushkov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-30 00:00:00.000000000 Z
+date: 2023-07-10 00:00:00.000000000 Z
 dependencies: []
 description: |
   JSON Serializer
@@ -73,7 +73,13 @@ files:
 - lib/serega/plugins/metadata/validations/check_opts.rb
 - lib/serega/plugins/metadata/validations/check_path.rb
 - lib/serega/plugins/preloads/lib/format_user_preloads.rb
-- lib/serega/plugins/preloads/lib/main_preload_path.rb
+- lib/serega/plugins/preloads/lib/modules/attribute.rb
+- lib/serega/plugins/preloads/lib/modules/attribute_normalizer.rb
+- lib/serega/plugins/preloads/lib/modules/check_attribute_params.rb
+- lib/serega/plugins/preloads/lib/modules/config.rb
+- lib/serega/plugins/preloads/lib/modules/plan_point.rb
+- lib/serega/plugins/preloads/lib/preload_paths.rb
+- lib/serega/plugins/preloads/lib/preloads_config.rb
 - lib/serega/plugins/preloads/lib/preloads_constructor.rb
 - lib/serega/plugins/preloads/preloads.rb
 - lib/serega/plugins/preloads/validations/check_opt_preload.rb

data/lib/serega/plugins/preloads/lib/main_preload_path.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-class Serega
-  module SeregaPlugins
-    module Preloads
-      #
-      # Class that constructs main preloads path.
-      #
-      # When we have nested preloads we will use this path to dig to `main` element and
-      # assign nested preloads to it.
-      #
-      # By default its a path to latest provided preload
-      #
-      # @example
-      #  MainPreloadPath.(a: { b: { c: {} }, d: {} }) # => [:a, :d]
-      #
-      class MainPreloadPath
-        class << self
-          # Finds default preload path
-          #
-          # @param preloads [Hash] Formatted user provided preloads hash
-          #
-          # @return [Array<Symbol>] Preloads path to `main` element
-          def call(preloads)
-            return FROZEN_EMPTY_ARRAY if !preloads || preloads.empty?
-
-            main_path(preloads).freeze
-          end
-
-          private
-
-          # Generates path (Array) to the last included resource.
-          # We need to know this path to include nested associations.
-          #
-          #  main_path(a: { b: { c: {} }, d: {} }) # => [:a, :d]
-          #
-          def main_path(hash, path = [])
-            current_level = path.size
-
-            hash.each do |key, data|
-              path.pop(path.size - current_level)
-              path << key
-
-              main_path(data, path)
-            end
-
-            path
-          end
-        end
-      end
-    end
-  end
-end