serega 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe523bff250ef512761ea848c60d5cc5468742509a60e675bb089a666b95ad50
-  data.tar.gz: 33c44df17578c3026d6b80d9c63152b4d4b238646b94feb93a849f2dd3b4d387
+  metadata.gz: 52535c7fab3897f65aec4e156ab5681e8595b4519df1e79a777688cee486a480
+  data.tar.gz: 16adbd9f036b0e23928049df873966f264db1004d2c4c1bc9e28422d687efd12
 SHA512:
-  metadata.gz: 7f8041f6459fd5560f27c8f069c509df43c129ef87383227d7bee90ebad6489b4db983a5de4e7e7b767dabb22a02012fe8b1fba3cb21dd9963a0adadd444c756
-  data.tar.gz: 55b4f299cad5da8f009fb0162ce2c558a0c01821db7318e7cf1d7ffc5915bdccfbc843ea924fe8fdcb5352897b1a871b4c8c829b8e585d3bfa6e03fe0a8c4abf
+  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.1
+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/batch.rb

@@ -79,8 +79,15 @@ class Serega
       # @return [void]
       #
       def self.load_plugin(serializer_class, **_opts)
+        require_relative "./lib/batch_config"
         require_relative "./lib/loader"
         require_relative "./lib/loaders"
+        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/object_serializer"
+        require_relative "./lib/modules/plan_point"
         require_relative "./lib/validations/check_batch_opt_key"
         require_relative "./lib/validations/check_batch_opt_loader"
         require_relative "./lib/validations/check_opt_batch"
@@ -136,97 +143,6 @@ class Serega
         config.batch.default_key = opts[:default_key] if opts.key?(:default_key)
       end
 
-      #
-      # Batch loader config
-      #
-      class BatchConfig
-        attr_reader :opts
-
-        def initialize(opts)
-          @opts = opts
-        end
-
-        #
-        # Defines batch loader
-        #
-        # @param loader_name [Symbol] Batch loader name, that is used when defining attribute with batch loader.
-        # @param block [Proc] Block that can accept 3 parameters - keys, context, plan_point
-        #   and returns hash where ids are keys and values are batch loaded objects/
-        #
-        # @return [void]
-        #
-        def define(loader_name, &block)
-          unless block
-            raise SeregaError, "Block must be given to #define method"
-          end
-
-          params = block.parameters
-          if params.count > 3 || !params.all? { |param| (param[0] == :req) || (param[0] == :opt) }
-            raise SeregaError, "Block can have maximum 3 regular parameters"
-          end
-
-          loaders[loader_name] = block
-        end
-
-        # Shows defined loaders
-        # @return [Hash] defined loaders
-        def loaders
-          opts[:loaders]
-        end
-
-        #
-        # Finds previously defined batch loader by name
-        #
-        # @param loader_name [Symbol]
-        #
-        # @return [Proc] batch loader block
-        def fetch_loader(loader_name)
-          loaders[loader_name] || (raise SeregaError, "Batch loader with name `#{loader_name.inspect}` was not defined. Define example: config.batch.define(:#{loader_name}) { |keys, ctx, points| ... }")
-        end
-
-        # Shows option to auto hide attributes with :batch specified
-        # @return [Boolean, nil] option value
-        def auto_hide
-          opts[:auto_hide]
-        end
-
-        # @param value [Boolean] New :auto_hide option value
-        # @return [Boolean] New option value
-        def auto_hide=(value)
-          raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
-          opts[:auto_hide] = value
-        end
-
-        # Shows default key for :batch option
-        # @return [Symbol, nil] default key for :batch option
-        def default_key
-          opts[:default_key]
-        end
-
-        # @param value [Symbol] New :default_key option value
-        # @return [Boolean] New option value
-        def default_key=(value)
-          raise SeregaError, "Must be a Symbol, #{value.inspect} provided" unless value.is_a?(Symbol)
-          opts[:default_key] = value
-        end
-      end
-
-      #
-      # Config class additional/patched instance methods
-      #
-      # @see Serega::SeregaConfig
-      #
-      module ConfigInstanceMethods
-        #
-        # Returns all batch loaders registered for current serializer
-        #
-        # @return [Serega::SeregaPlugins::Batch::BatchConfig] configuration for batch loaded attributes
-        #
-        def batch
-          @batch ||= BatchConfig.new(opts.fetch(:batch))
-        end
-      end
-
       #
       # Serega class additional/patched class methods
       #
@@ -248,138 +164,6 @@ class Serega
         end
       end
 
-      #
-      # Serega::SeregaValidations::CheckAttributeParams additional/patched class methods
-      #
-      # @see Serega::SeregaValidations::CheckAttributeParams
-      #
-      module CheckAttributeParamsInstanceMethods
-        private
-
-        def check_opts
-          super
-
-          CheckOptBatch.call(opts, block, self.class.serializer_class)
-        end
-      end
-
-      #
-      # Serega::SeregaAttribute additional/patched class methods
-      #
-      # @see Serega::SeregaAttribute
-      #
-      module AttributeInstanceMethods
-        #
-        # @return [nil, Hash] :batch option
-        #
-        attr_reader :batch
-
-        private
-
-        def set_normalized_vars(normalizer)
-          super
-          @batch = normalizer.batch
-        end
-      end
-
-      #
-      # SeregaAttributeNormalizer additional/patched instance methods
-      #
-      # @see SeregaAttributeNormalizer::AttributeInstanceMethods
-      #
-      module AttributeNormalizerInstanceMethods
-        #
-        # Returns normalized attribute :batch option with prepared :key and
-        # :default options. Option :loader will be prepared at serialization
-        # time as loaders are usually defined after attributes.
-        #
-        # @return [Hash] attribute :batch normalized options
-        #
-        def batch
-          return @batch if instance_variable_defined?(:@batch)
-
-          @batch = prepare_batch
-        end
-
-        private
-
-        #
-        # Patch for original `prepare_hide` method
-        #
-        # Marks attribute hidden if auto_hide option was set and attribute has batch loader
-        #
-        def prepare_hide
-          res = super
-          return res unless res.nil?
-
-          if batch
-            self.class.serializer_class.config.batch.auto_hide || nil
-          end
-        end
-
-        def prepare_batch
-          batch = init_opts[:batch]
-          return unless batch
-
-          # take loader
-          loader = batch[:loader]
-
-          # take key
-          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
-            else
-              key
-            end
-
-          # take default value
-          default = batch.fetch(:default) { many ? FROZEN_EMPTY_ARRAY : nil }
-
-          {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
-
-      #
-      # Serega::SeregaPlanPoint additional/patched class methods
-      #
-      # @see SeregaAttribute
-      #
-      module PlanPointInstanceMethods
-        #
-        # Returns attribute :batch option with prepared loader
-        # @return [Hash] attribute :batch option
-        #
-        attr_reader :batch
-
-        private
-
-        def set_normalized_vars
-          super
-          @batch = prepare_batch
-        end
-
-        def prepare_batch
-          batch = attribute.batch
-          if batch
-            loader = batch[:loader]
-            if loader.is_a?(Symbol)
-              batch_config = attribute.class.serializer_class.config.batch
-              batch[:loader] = batch_config.fetch_loader(loader)
-            end
-          end
-          batch
-        end
-      end
-
       #
       # Serega additional/patched instance methods
       #
@@ -398,28 +182,6 @@ class Serega
           result
         end
       end
-
-      #
-      # SeregaObjectSerializer additional/patched class methods
-      #
-      # @see Serega::SeregaObjectSerializer
-      #
-      module SeregaObjectSerializerInstanceMethods
-        private
-
-        def attach_value(object, point, container)
-          batch = point.batch
-          return super unless batch
-
-          remember_key_for_batch_loading(batch, object, point, container)
-        end
-
-        def remember_key_for_batch_loading(batch, object, point, container)
-          key = batch[:key].call(object, context)
-          opts[:batch_loaders].get(point, self).remember(key, container)
-          container[point.name] = nil # Reserve attribute place in resulted hash. We will set correct value later
-        end
-      end
     end
 
     register_plugin(Batch.plugin_name, Batch)