serega 0.37.0 → 0.37.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf4c5f1a34256084ebedcba18d08dcdc30f9a3090ca3b555a7ee91fc8e0dfc44
-  data.tar.gz: 05022337ad49d098c50f25c267f33a2db6c210b169f3243b88c010a5f9bc519e
+  metadata.gz: fe536c6d684f24508a5153d1fc679cd451d2360ab3d752ff2ba08a2249b264c9
+  data.tar.gz: 0110de5fca4df251b1101daaba232bf1fcace80b6290bb95e35a8c892fc1ce1b
 SHA512:
-  metadata.gz: a9b5a2797086500903904617124810a4401f0a223ea75ba88d78c6cf3cba90157e9ff666f54fd76183fbbed4ab54d7be33704fd7c45665537e825f5f0f67222c
-  data.tar.gz: 150fcf62d92d01076c61d38a4189a31d789904fc643c2ce06c569280099d598582e3e07b7ff32a3482e0754d47045123dcf7f01baf7f7f65afebe2c1465e3c93
+  metadata.gz: 5a7f60a35e6791337f15772efeb2dfa0363ff96bb99f815c849c1fb5b40125854802b39ef492bea078f6bb614171b29b8f0e5409e421c52e6f24bf39eabfffdd
+  data.tar.gz: 2d3adb93d754ed3fb42581e5a45493e30e3f1fbb1cda8c68956e5cc047be42417f8cd487074cae5ce11fe72dbfa633ba32ccdc52dd002de17f349b7532c10f4f

data/README.md

@@ -530,12 +530,12 @@ attribute is serialized:
 
 ```ruby
 class UserSerializer < Serega
+  attribute :name
+  attribute :posts, serializer: PostSerializer, preload: :posts
+
   # `objects` is the gathered users; `preloads` is this attribute's
   # `:preload` value (`:posts`). `MyORM.preload` does the eager loading.
   preload_with { |objects, preloads| MyORM.preload(objects, preloads) }
-
-  attribute :name
-  attribute :posts, serializer: PostSerializer, preload: :posts
 end
 ```
 
@@ -547,6 +547,33 @@ objects can be plain Ruby objects too: the handler decides where the data comes
 from (another ORM, an HTTP API, a cache) and how to attach it to the objects,
 by whatever rules you define.
 
+The handler runs **once per preloaded attribute**, not once per distinct
+`:preload` value. If the same `:preload` is declared on several attributes, the
+handler is invoked once for each of them over the same objects, so it should
+check whether the data is already loaded before loading it again. (The
+`:activerecord_preloads` handler relies on `ActiveRecord::Associations::Preloader`,
+which already skips associations that are loaded.)
+
+Because you choose the `:preload` value, it doubles as a **discriminator**: give
+two attributes different `:preload` values and branch on `preloads` inside the
+handler — no need for the value to be a real association name.
+
+```ruby
+class PostSerializer < Serega
+  attribute :owner,  serializer: UserSerializer, preload: :owner
+  attribute :author, serializer: UserSerializer, preload: :author
+
+  # Both attributes load the same person, but from different sources.
+  preload_with do |objects, preloads|
+    case preloads
+    when :owner  then load_owners(objects)   # e.g. from the DB
+    when :author then load_authors(objects)  # e.g. from an external API
+    else MyORM.preload(objects, preloads)
+    end
+  end
+end
+```
+
 ---
 
 ## Plugins

data/VERSION

@@ -1 +1 @@
-0.37.0
+0.37.2

data/lib/serega/attribute_normalizer.rb

@@ -9,10 +9,6 @@ class Serega
     # AttributeNormalizer instance methods
     #
     module AttributeNormalizerInstanceMethods
-      # Identity loader that routes relation/preload attributes through the batch
-      # mechanism. Its result is never read — the attribute's value block still
-      # computes the value.
-      AUTO_BATCH_LOADER = proc { |records| records.to_h { |record| [record, record] } }
       # Attribute initial params
       # @return [Hash] Attribute initial params
       attr_reader :init_name, :init_opts, :init_block
@@ -152,13 +148,24 @@ class Serega
 
         hide_setting = config.hide_by_default
         return true if hide_setting == true
-        return true if hide_setting == :auto && (preloads || init_opts.key?(:batch))
+        return true if hide_setting == :auto && preload_or_batch?
 
         # Return nil for undefined value which means "not hide" but allows
         # to change this value by plugins
         nil
       end
 
+      # The `hide_by_default = :auto` criterion: hide attributes that fetch extra
+      # data on demand — those declared with `:preload` or an explicit `:batch`.
+      #
+      # This is intentionally narrower than a "goes through the batch mechanism"
+      # check (`SeregaPlanPoint#batch?`): a plain relation (`serializer:` without
+      # `:preload`) is batch-processed too, but it only serializes an already-loaded
+      # nested object, so it stays visible by default.
+      def preload_or_batch?
+        !!(preloads || init_opts.key?(:batch))
+      end
+
       def config
         self.class.serializer_class.config
       end
@@ -197,9 +204,11 @@ class Serega
         return explicit_batch_loaders(batch_opt) if batch_opt
         return FROZEN_EMPTY_ARRAY unless serializer || preloads
 
-        loader_name = :"__auto_batch_#{name}__"
-        self.class.serializer_class.batch(loader_name, AUTO_BATCH_LOADER)
-        [loader_name]
+        # Relations and preloads only need to be routed through the batch phase
+        # (so objects are gathered per level and preloads run) — there is nothing
+        # to load, since the value comes from the attribute's own resolver. Mark
+        # them with the reserved marker; the batch machinery skips it.
+        [SeregaBatch::AUTO_BATCH_LOADER_NAME]
       end
 
       def explicit_batch_loaders(batch_opt)

data/lib/serega/batch/attribute_loader.rb

@@ -41,7 +41,7 @@ class Serega
 
           handler.call(level.objects, preloads)
         rescue => error
-          reraise_with_serialized_attribute_details(error)
+          SeregaUtils::SerializedAttributeError.call(error, point)
         end
 
         # Loads a single named batch for this level's objects. Caching across
@@ -51,16 +51,20 @@ class Serega
         def load_batch(loader)
           level.load(loader)
         rescue => error
-          reraise_with_serialized_attribute_details(error)
+          SeregaUtils::SerializedAttributeError.call(error, point)
         end
 
         # Attaches already loaded batch values to every stored object.
+        # Value resolution happens here (inside the attacher), so errors are
+        # annotated with the attribute, matching the synchronous walk.
         # @param batches [Hash] Loaded values grouped by batch loader name
         # @return [void]
         def attach(batches)
           serialized_object_attachers.each do |object, attacher|
             attacher.call(object, batches)
           end
+        rescue => error
+          SeregaUtils::SerializedAttributeError.call(error, point)
         end
 
         attr_reader :point
@@ -68,13 +72,6 @@ class Serega
 
         private
 
-        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 :serialized_object_attachers
       end
 

data/lib/serega/batch/attribute_loaders.rb

@@ -5,6 +5,11 @@ class Serega
   # Batch feature main module
   #
   module SeregaBatch
+    # Reserved batch-loader name that marks relation/preload attributes as
+    # batch-processed. It has no registered loader — the attribute's value comes
+    # from its own resolver — so `load_batches` skips it (nothing to load).
+    AUTO_BATCH_LOADER_NAME = :__auto_batch__
+
     #
     # Batch loaders
     #
@@ -98,6 +103,10 @@ class Serega
 
         batches = {}
         point.batch_loaders.each do |batch_loader_name|
+          # Auto-batched relations/preloads carry the marker, not a real loader:
+          # their value comes from their own resolver, so there is nothing to load.
+          next if batch_loader_name == AUTO_BATCH_LOADER_NAME
+
           loader = serializer_class.batch_loaders[batch_loader_name]
           batches[batch_loader_name] = attribute_loader.load_batch(loader)
         end

data/lib/serega/object_serializer.rb

@@ -55,7 +55,7 @@ class Serega
         plan.points.each_with_object({}) do |point, container|
           serialize_point(object, point, container)
         rescue => error
-          reraise_with_serialized_attribute_details(error, point)
+          SeregaUtils::SerializedAttributeError.call(error, point)
         end
       end
 
@@ -103,13 +103,6 @@ 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/plugins/if/if.rb

@@ -275,8 +275,11 @@ class Serega
           super
         end
 
-        def attach_final_value(value, point, _container)
-          return KEY_SKIPPED unless point.satisfy_if_value_conditions?(value, context)
+        def attach_final_value(value, point, container)
+          unless point.satisfy_if_value_conditions?(value, context)
+            container.delete(point.name) # remove reserved placeholder
+            return KEY_SKIPPED
+          end
 
           super
         end

data/lib/serega/utils/serialized_attribute_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaUtils
+    #
+    # Reraises an error, adding which attribute and serializer were being
+    # serialized when it happened. Shared by the synchronous serialization walk
+    # and the batch attach phase so the message stays identical for every
+    # attribute, whether its value is resolved inline or during batch loading.
+    #
+    module SerializedAttributeError
+      module_function
+
+      #
+      # @param error [Exception] Original error
+      # @param point [SeregaPlanPoint] Plan point being serialized
+      #
+      # @return [void]
+      #
+      def call(error, point)
+        raise error.exception(<<~MESSAGE.strip)
+          #{error.message}
+          (when serializing '#{point.name}' attribute in #{point.class.serializer_class})
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/serega.rb

@@ -22,6 +22,7 @@ require_relative "serega/helpers/serializer_class_helper"
 require_relative "serega/utils/enum_deep_dup"
 require_relative "serega/utils/enum_deep_freeze"
 require_relative "serega/utils/method_signature"
+require_relative "serega/utils/serialized_attribute_error"
 require_relative "serega/utils/symbol_name"
 require_relative "serega/utils/to_hash"
 require_relative "serega/attribute_value_resolvers/batch"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.37.0
+  version: 0.37.2
 platform: ruby
 authors:
 - Andrey Glushkov
@@ -74,6 +74,7 @@ files:
 - lib/serega/utils/enum_deep_dup.rb
 - lib/serega/utils/enum_deep_freeze.rb
 - lib/serega/utils/method_signature.rb
+- lib/serega/utils/serialized_attribute_error.rb
 - lib/serega/utils/symbol_name.rb
 - lib/serega/utils/to_hash.rb
 - lib/serega/validations/attribute/check_block.rb