serega 0.38.0 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 384da177845e2385a0100d23147cea0034860b148cd46738dc3d6ec7ea7d7eda
-  data.tar.gz: f08d482a83cb0cde30ae4c03e924f50be6aaabea24d76564bc47a7a1eadf4f98
+  metadata.gz: a223242ae8bce14755fa2cbb444ff78728d95fccb0ce3077c212706e39e4ddcc
+  data.tar.gz: b8e1d3bdf11a57091cfd22eb31bb017979382df4b2166b05f746d064dc486f6e
 SHA512:
-  metadata.gz: c9f2f95d8a74ce4951f7acef89a1cf603fcba2f15af50d246f85d58e1456b06c03b749fef620c741f8e2482999c6f7471fb5dff9a904b275f79f039999ab7fdc
-  data.tar.gz: 69c1b8f898f81317310e875a8771db096b3d4613b34769024d66fe801554e53094fd59e3cfea923ef81bb5d837a31ef28ceadc825003c95a4a2340f6b0b0bf74
+  metadata.gz: d815a4a17625533c34659451851c33806bd4d1e0bf862945b2118d52315726184322c55d989378cf8ac7f9b4d04a392dfa344af196491b984ddc1d094d15c063
+  data.tar.gz: ecf2be1cff661bfe8e99103748276969f72442b04b8308dd136d137dc88f28dfb543ad73a5e0880a31eb6f6c4a6a51e6ccab307a92f867551ff4b19b56d38f73

data/README.md

@@ -78,8 +78,24 @@ class UserSerializer < Serega
   # serialized object
   attribute :first_name, method: :old_first_name
 
-  # Block is used to define attribute value
-  attribute(:first_name) { |user| user.profile&.first_name }
+  # Attribute blocks below require a base serializer for nested serializers.
+  # See the "Defining a nested serializer with a block" section below.
+  config.base_serializer = Serega
+
+  # Method :itself is handy to serialize the same object with a nested set of
+  # attributes. Note: with the :presenter plugin the serialized value will be
+  # the Presenter instance itself; use `method: :__getobj__` to serialize the
+  # original unwrapped object instead.
+  attribute :statistics, method: :itself do
+    attribute :likes_count
+    attribute :comments_count
+  end
+
+  # Block defines a nested serializer for the attribute value.
+  # See the "Defining a nested serializer with a block" section below.
+  attribute :author do
+    attribute :name
+  end
 
   # Option :value can be used with a Proc or callable object to define
   # attribute value
@@ -114,13 +130,13 @@ class UserSerializer < Serega
 
   # Option `:many` specifies a has_many relationship. It is optional.
   # If not specified, it is defined during serialization by checking
-  # `object.is_a?(Enumerable)`
+  # `object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)`
   # Also the `:many` changes the default value from `nil` to `[]`.
   attribute :posts, serializer: PostSerializer, many: true
 
   # Option `:preload` allows to specify associations to preload to
   # attribute value
-  attribute(:email, preload: :emails) { |user| user.emails.find(&:verified?) }
+  attribute :email, preload: :emails, value: proc { |user| user.emails.find(&:verified?) }
 
   # Options `:if, :unless, :if_value and :unless_value` can be specified
   # when `:if` plugin is enabled. They hide the attribute key and value from the
@@ -139,6 +155,70 @@ class UserSerializer < Serega
 end
 ```
 
+### Defining a nested serializer with a block
+
+An attribute block defines an anonymous nested serializer. The attribute value
+is found as usual — by the attribute name or the `:method`, `:value`,
+`:delegate`, `:batch` option — and is serialized by this nested serializer.
+
+The nested serializer is a regular subclass of an explicitly chosen **base
+serializer** — usually a settings-only serializer holding your plugins and
+configuration. Choose it with the `base_serializer:` attribute option or the
+`config.base_serializer` setting (attribute option wins; an error is raised
+when none is set):
+
+```ruby
+class AppSerializer < Serega
+  plugin :activerecord_preloads
+
+  # Nested serializers defined with attribute blocks will inherit from
+  # AppSerializer
+  config.base_serializer = self
+end
+
+class UserSerializer < AppSerializer
+  attribute :first_name
+
+  # Serializes user.author with a nested serializer inherited from AppSerializer
+  attribute :author do
+    attribute :name
+  end
+
+  # Serializes the user itself, exposing only counters
+  attribute :statistics, method: :itself, base_serializer: StatsBaseSerializer do
+    attribute :likes_count
+    attribute :comments_count
+  end
+end
+
+UserSerializer.to_h(user)
+# => {first_name: "Bruce", author: {name: "Bob"}, statistics: {likes_count: 10, comments_count: 3}}
+```
+
+The nested serializer inherits everything the base serializer has — plugins,
+config, attributes, batch loaders, the preload handler — through the regular
+inheritance mechanism. Any serializer can be used as a base: if it has
+attributes, they are serialized by the nested serializer too, together with
+the attributes defined in the block. Anything the base does not provide can
+be declared inside the block:
+
+```ruby
+attribute :statistics, method: :itself do
+  batch(:stats) { |users| Stats.for_users(users) } # => { user_id => stat }
+
+  attribute :likes_count, batch: :stats, value: proc { |user, batches:| batches[:stats][user.id].likes }
+end
+```
+
+Things to keep in mind:
+
+- The nested serializer is created at the moment the attribute is defined.
+  Changes made to the base serializer later do not affect already defined
+  nested serializers.
+- Errors raised while serializing nested attributes are reported with a
+  readable serializer label, for example:
+  `(when serializing 'comments_count' attribute in UserSerializer.<statistics>)`.
+
 ### Serializing
 
 We can serialize objects using class method `.call` aliased as `.to_h` and
@@ -183,15 +263,6 @@ serializer.to_h(user1)
 serializer.to_h(user2)
 ```
 
----
-⚠️ When you serialize the `Struct` object, specify manually `many: false`. As Struct
-is Enumerable and we check `object.is_a?(Enumerable)` to detect if we should
-return array.
-
-```ruby
-UserSerializer.to_h(user_struct, many: false)
-```
-
 ### Selecting Fields
 
 By default, all attributes are serialized (except marked as `hide: true`).
@@ -312,9 +383,9 @@ current_user or any.
 
 ```ruby
 class UserSerializer < Serega
-  attribute(:email) do |user, ctx|
+  attribute :email, value: proc { |user, ctx|
     user.email if ctx[:current_user] == user
-  end
+  }
 end
 
 user = OpenStruct.new(email: 'email@example.com')
@@ -339,15 +410,18 @@ class UserSerializer < Serega
   batch :comments_count, ->(users) { Comment.where(user: users).group(:user_id).count }
   batch :comments_count, CommentsCountLoader # Example with callable class
 
-  # Full attribute example
-  attribute :comments_count, batch: { use: :comments_count },
-    value: proc { |user, batch:| batch[:comments_count][user.id] }
+  # Use a loader by its name
+  attribute :comments_count, batch: :comments_count
 
-  # Shorter version
-  attribute :comments_count, batch: { use: :comments_count, id: :id } # Equivalent, id: :id is default
+  # Equivalent — when the attribute name matches the loader name
+  attribute :comments_count, batch: true
 
-  # Shortest version
-  attribute :comments_count, batch: true # Equivalent
+  # Equivalent — the default value resolution spelled out
+  attribute :comments_count, batch: :comments_count,
+    value: proc { |user, batches:| batches[:comments_count][user.id] }
+
+  # Hash form — needed only for sub-options, for example a custom `:id` method
+  attribute :comments_count, batch: { use: :comments_count, id: :uuid }
 end
 ```
 
@@ -382,7 +456,7 @@ class UserSerializer < Serega
   # Summarize likes
   attribute :likes_count,
     batch: { use: [:facebook_likes, :twitter_likes] },
-    value: { |user, batch:| batch[:facebook_likes][user.id] + batch[:twitter_likes][user.id] }
+    value: proc { |user, batches:| batches[:facebook_likes][user.id] + batches[:twitter_likes][user.id] }
 end
 ```
 
@@ -390,6 +464,13 @@ end
 
 Here are the default options. Other options can be added with plugins.
 
+⚠️ Attributes are prepared at the moment they are defined. If a config option
+influences attributes (`auto_preload`, `hide_by_default`, `batch_id_option`,
+formatters, etc.), changing it affects only attributes defined **after** the
+change — including nested serializers defined with attribute blocks, which
+are created at their definition point. Configure the serializer before
+defining attributes.
+
 ```ruby
 class AppSerializer < Serega
   # With `activerecord_preloads` plugin it automatically adds `preload` option
@@ -413,6 +494,13 @@ class AppSerializer < Serega
   #   proc { |object, batches:| batches[:counter][object.id] }
   config.batch_id_option = :id
 
+  # Parent class for nested serializers defined with attribute blocks.
+  # Usually a settings-only serializer, e.g. `config.base_serializer = self`
+  # in an application base serializer class. There is no default — an
+  # attribute block raises an error when no base serializer is chosen (it can
+  # also be provided per-attribute with the `base_serializer:` option).
+  config.base_serializer = self
+
   # Disable/enable validation of modifiers (`:with, :except, :only`)
   # By default, this validation is enabled.
   # After disabling, all requested incorrect attributes will be skipped.
@@ -793,7 +881,7 @@ class UserSerializer < Serega
 end
 ```
 
-With the plugin, they move into a clean class:
+With the plugin, they move into a `presenter do ... end` block:
 
 ```ruby
 class UserSerializer < Serega
@@ -802,7 +890,7 @@ class UserSerializer < Serega
   attribute :name
   attribute :role
 
-  class Presenter
+  presenter do
     def name
       [first_name, last_name].compact.join(' ')
     end
@@ -814,6 +902,9 @@ class UserSerializer < Serega
 end
 ```
 
+The block is evaluated inside the serializer's own `Presenter` class, so
+multiple `presenter` blocks accumulate.
+
 `Presenter` inherits from `SimpleDelegator`, so every method of the serialized
 object is available directly inside presenter methods. Any method not explicitly
 defined on `Presenter` is resolved via `method_missing` on the first call, which
@@ -825,6 +916,12 @@ The original wrapped object is accessible via `__getobj__` (standard
 
 The serialization context is accessible via the private method `__ctx__`.
 
+Objects are wrapped in the `Presenter` only when the serializer's `Presenter`
+class (or an inherited one) actually defines custom methods. Loading the
+plugin in a base serializer adds no overhead to serializers that don't
+customize their presenters — their attribute values, batch loaders and value
+callables keep receiving the raw objects.
+
 ### Plugin :string_modifiers
 
 Allows to specify modifiers as strings.
@@ -973,7 +1070,8 @@ end
 ### Plugin :explicit_many_option
 
 The plugin requires adding a `:many` option when adding relationships
-(attributes with the `:serializer` option).
+(attributes with the `:serializer` option or a block defining a nested
+serializer).
 
 Adding this plugin makes it clearer to find if some relationship is an array or
 a single object.

data/VERSION

@@ -1 +1 @@
-0.38.0
+0.39.0

data/lib/serega/attribute.rb

@@ -45,10 +45,10 @@ class Serega
       # @option opts [Symbol] :method Object method name to fetch attribute value
       # @option opts [Hash] :delegate Allows to fetch value from nested object
       # @option opts [Boolean] :hide Specify `true` to not serialize this attribute by default
-      # @option opts [Boolean] :many Specifies has_many relationship. By default is detected via object.is_a?(Enumerable)
+      # @option opts [Boolean] :many Specifies has_many relationship. By default is detected via object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)
       # @option opts [Proc, #call] :value Custom block or callable to find attribute value
       # @option opts [Serega, Proc] :serializer Relationship serializer class. Use `proc { MySerializer }` if serializers have cross references
-      # @param block [Proc] Custom block to find attribute value
+      # @param block [Proc] Defines attributes of a nested anonymous serializer
       #
       def initialize(name:, opts: {}, block: nil)
         serializer_class = self.class.serializer_class
@@ -88,7 +88,7 @@ class Serega
       # @return [Object] Serialized attribute value
       #
       def value(object, context, batches: nil)
-        # Signatires should match allowed signatures in CheckOptValue and CheckBlock
+        # Signatures should match allowed signatures in CheckOptValue
         result =
           case value_block_signature
           when "1" then value_block.call(object)

data/lib/serega/attribute_normalizer.rb

@@ -133,8 +133,7 @@ class Serega
       end
 
       def prepare_value_block
-        init_block \
-          || init_opts[:value] \
+        init_opts[:value] \
           || prepare_const_block \
           || prepare_delegate_block \
           || prepare_batch_loader_block \
@@ -175,7 +174,73 @@ class Serega
       end
 
       def prepare_serializer
-        init_opts[:serializer]
+        block = init_block
+        return init_opts[:serializer] unless block
+
+        prepare_block_serializer(block)
+      end
+
+      # Builds an anonymous nested serializer from the attribute block.
+      #
+      # The serializer is a regular subclass of an explicitly chosen base —
+      # the :base_serializer attribute option or `config.base_serializer` —
+      # so it inherits everything the base has: plugins, config, attributes,
+      # batch loaders, the preload handler. Nested values can be any objects,
+      # which is why the base is chosen explicitly instead of inheriting from
+      # the current serializer. Its `inspect` is overridden to
+      # `CurrentSerializer.<attribute_name>` so error messages and debugging
+      # output point back to the defining attribute.
+      # Guards against cyclic definitions before building: inheriting the base
+      # serializer copies its attributes, and copying a block attribute builds
+      # its nested serializer — meeting the same block again while it is being
+      # built means the base serializer (transitively) contains the block
+      # attribute being built, so inheriting from it would recurse forever.
+      # The "in progress" mark is kept on the block itself — its identity is
+      # what defines the cycle (the same Proc object is shared by all copies
+      # of the attribute).
+      def prepare_block_serializer(block)
+        if block.instance_variable_defined?(:@serega_building_nested_serializer)
+          raise SeregaError,
+            "Can not define a nested serializer for attribute :#{name} —" \
+            " its base serializer #{block_base_serializer.inspect} (transitively)" \
+            " contains this same block attribute (cyclic definition)"
+        end
+
+        block.instance_variable_set(:@serega_building_nested_serializer, true)
+        begin
+          build_block_serializer(block)
+        ensure
+          block.remove_instance_variable(:@serega_building_nested_serializer)
+        end
+      end
+
+      def build_block_serializer(block)
+        label = "#{self.class.serializer_class.inspect}.<#{name}>"
+
+        serializer = Class.new(block_base_serializer) do
+          define_singleton_method(:inspect) { label }
+          define_singleton_method(:to_s) { label }
+          instance_exec(&block)
+        end
+
+        # An empty nested serializer means the block was intended as an
+        # old-style value block — raise the explaining error.
+        raise SeregaError, SeregaValidations::Attribute::CheckBlock::ERROR_MESSAGE if serializer.attributes.empty?
+
+        serializer
+      end
+
+      # Base class for the nested serializer. Must be chosen explicitly —
+      # usually a settings-only serializer holding plugins and configuration
+      # (e.g. `config.base_serializer = self` in an application base class).
+      def block_base_serializer
+        base_serializer = init_opts[:base_serializer] || config.base_serializer
+        return base_serializer if base_serializer
+
+        raise SeregaError,
+          "Attribute block requires a base serializer for the nested serializer." \
+          " Provide the `base_serializer: <SerializerClass>` attribute option" \
+          " or set `config.base_serializer = <SerializerClass>`"
       end
 
       def prepare_method_name
@@ -250,16 +315,26 @@ class Serega
 
         # Auto-preload the delegated association
         if config.auto_preload.fetch(:has_delegate_option) && init_opts[:delegate]
-          return init_opts[:delegate][:to]
+          return auto_preload_value(init_opts[:delegate][:to])
         end
 
         # Auto-preload the nested serializer's association
-        if config.auto_preload.fetch(:has_serializer_option) && init_opts[:serializer] && !init_opts.key?(:batch)
-          return method_name
+        # (a block defines a nested serializer, same as the :serializer option)
+        if config.auto_preload.fetch(:has_serializer_option) && (init_opts[:serializer] || init_block) && !init_opts.key?(:batch)
+          return auto_preload_value(method_name)
         end
 
         nil
       end
+
+      # Skips auto-preloading of methods that return the serialized object
+      # itself (:itself by default) — they are not associations,
+      # so preloading them would fail or make no sense.
+      def auto_preload_value(preload_method)
+        return nil if config.auto_preload_excluded_methods.include?(preload_method.to_sym)
+
+        preload_method
+      end
     end
 
     extend Serega::SeregaHelpers::SerializerClassHelper

data/lib/serega/attribute_value_resolvers/batch.rb

@@ -18,6 +18,7 @@ class Serega
       # It handles this cases:
       # - `attribute :foo, batch: true`
       # - `attribute :foo, batch: FooLoader`
+      # - `attribute :foo, batch: :foo_loader`
       # - `attribute :foo, batch: { id: :foo_id }`
       # - `attribute :foo, batch: { use: FooLoader, id: foo_id }`
       # - `attribute :foo, batch: { use: :foo_loader, id: foo_id }`
@@ -32,6 +33,9 @@ class Serega
           serializer_class.batch(attribute_name, batch_opt)
           batch_name = attribute_name
           batch_id_method = default_method
+        elsif batch_opt.is_a?(Symbol) || batch_opt.is_a?(String) # ex: `batch: :foo_loader`
+          batch_name = batch_opt.to_sym
+          batch_id_method = default_method
         else
           use = batch_opt[:use]
           batch_id_method = batch_opt[:id] || default_method

data/lib/serega/config.rb

@@ -24,6 +24,7 @@ class Serega
         default
         preload
         batch
+        base_serializer
       ].freeze,
       serialize_keys: %i[context many].freeze,
       check_attribute_name: true,
@@ -31,8 +32,10 @@ class Serega
       delegate_default_allow_nil: false,
       max_cached_plans_per_serializer_count: 0,
       auto_preload: {has_delegate_option: false, has_serializer_option: false},
+      auto_preload_excluded_methods: %i[itself].freeze,
       hide_by_default: false,
-      batch_id_option: :id
+      batch_id_option: :id,
+      base_serializer: nil
     }.freeze
     # :nocov:
 
@@ -114,6 +117,50 @@ class Serega
         opts[:delegate_default_allow_nil] = value
       end
 
+      # Returns :auto_preload_excluded_methods config option — methods that are
+      # never auto-preloaded, as they return the serialized object itself and
+      # not an association
+      # @return [Array<Symbol>] Current :auto_preload_excluded_methods config option
+      def auto_preload_excluded_methods
+        opts.fetch(:auto_preload_excluded_methods)
+      end
+
+      # Sets :auto_preload_excluded_methods config option — methods that are
+      # never auto-preloaded. Applies to the `:method` option of attributes
+      # with a serializer and to the `delegate: {to: ...}` option.
+      #
+      # @param value [Array<Symbol>] Method names to skip in auto-preload
+      #
+      # @return [Array<Symbol>] New :auto_preload_excluded_methods config option
+      def auto_preload_excluded_methods=(value)
+        unless value.is_a?(Array) && value.all?(Symbol)
+          raise SeregaError, "Must be an Array of Symbols, #{value.inspect} provided"
+        end
+
+        opts[:auto_preload_excluded_methods] = value
+      end
+
+      # Returns :base_serializer config option — the parent class for nested
+      # serializers defined with attribute blocks
+      # @return [Class, nil] Current :base_serializer config option
+      def base_serializer
+        opts.fetch(:base_serializer)
+      end
+
+      # Sets :base_serializer config option — the parent class for nested
+      # serializers defined with attribute blocks. Usually a settings-only
+      # serializer, e.g. `config.base_serializer = self` in an application
+      # base serializer class.
+      #
+      # @param value [Class] Serega or its subclass
+      #
+      # @return [Class] New :base_serializer config option
+      def base_serializer=(value)
+        raise SeregaError, "Must be a Serega subclass, #{value.inspect} provided" if !value.is_a?(Class) || !(value <= Serega)
+
+        opts[:base_serializer] = value
+      end
+
       # Returns :hide_by_default config option
       # @return [Boolean, Symbol] Current :hide_by_default config option
       def hide_by_default

data/lib/serega/object_serializer.rb

@@ -97,14 +97,14 @@ class Serega
       end
 
       # How to serialize `object`, deciding whether the result is a collection or a
-      # single object and reading `Enumerable` only once:
+      # single object and checking the object type only once:
       # - :many         — `many` is on and the object is a collection
       # - :many_for_one — `many` is on but a sole object was given (wrap it, don't raise)
       # - :one          — serialize the object on its own
       def serialize_mode(object)
         case many
-        when NilClass then object.is_a?(Enumerable) ? :many : :one
-        when TrueClass then object.is_a?(Enumerable) ? :many : :many_for_one
+        when NilClass then SeregaUtils::CollectionDetector.call(object) ? :many : :one
+        when TrueClass then SeregaUtils::CollectionDetector.call(object) ? :many : :many_for_one
         else :one # many == false
         end
       end

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

@@ -91,6 +91,7 @@ class Serega
       # The underlying records to preload onto. The :presenter plugin wraps every
       # serialized object in a SimpleDelegator, but ActiveRecord's Preloader needs
       # the real records, so unwrap them via #__getobj__ when presenter is used.
+      # Objects are wrapped only when the Presenter class has custom methods.
       #
       # @param serializer_class [Class<Serega>] Current serializer class
       # @param objects [Array] objects serialized at the current level
@@ -99,6 +100,7 @@ class Serega
       #
       def self.records(serializer_class, objects)
         return objects unless serializer_class.plugin_used?(:presenter)
+        return objects unless serializer_class.custom_presenter?
 
         objects.map(&:__getobj__)
       end

data/lib/serega/plugins/explicit_many_option/explicit_many_option.rb

@@ -6,7 +6,8 @@ class Serega
     # Plugin :explicit_many_option
     #
     # Plugin requires to add :many option when adding relationships
-    # (relationships are attributes with :serializer option specified)
+    # (relationships are attributes with the :serializer option or a block
+    # defining a nested serializer)
     #
     # Adding this plugin makes it clearer to find if relationship returns array or single object
     #
@@ -56,7 +57,7 @@ class Serega
         def check_opts
           super
 
-          CheckOptMany.call(opts)
+          CheckOptMany.call(opts, block)
         end
       end
     end

data/lib/serega/plugins/explicit_many_option/validations/check_opt_many.rb

@@ -10,23 +10,25 @@ class Serega
         class << self
           #
           # Checks attribute :many option must be provided with relations
+          # (attributes with the :serializer option or a block defining
+          # a nested serializer)
           #
           # @param opts [Hash] Attribute options
+          # @param block [nil, Proc] Attribute block
           #
           # @raise [SeregaError] Attribute validation error
           #
           # @return [void]
           #
-          def call(opts)
-            serializer = opts[:serializer]
-            return unless serializer
+          def call(opts, block = nil)
+            return if !opts[:serializer] && !block
 
             many_option_exists = opts.key?(:many)
             return if many_option_exists
 
             raise SeregaError,
               "Attribute option :many [Boolean] must be provided" \
-              " for attributes with :serializer option"
+              " for attributes with :serializer option or a block"
           end
         end
       end

data/lib/serega/plugins/presenter/presenter.rb

@@ -15,13 +15,19 @@ class Serega
     # - The original object is accessible via __getobj__ (standard SimpleDelegator API).
     # - The serialization context is accessible via the private method __ctx__.
     #
+    # Objects are wrapped in the Presenter only when the serializer's Presenter
+    # class (or an inherited one) was actually extended with custom methods —
+    # a bare `plugin :presenter` adds no wrapping overhead. The check is
+    # denormalized: `SerializerClass.custom_presenter?` is asked once per
+    # object serializer and the result is reused for the whole level.
+    #
     #   class UserSerializer < Serega
     #     plugin :presenter
     #
     #     attribute :name
     #     attribute :role
     #
-    #     class Presenter
+    #     presenter do
     #       def name
     #         [first_name, last_name].compact.join(' ') # first_name/last_name delegated to object
     #       end
@@ -31,6 +37,9 @@ class Serega
     #       end
     #     end
     #   end
+    #
+    # The `presenter do ... end` block is evaluated inside the serializer's own
+    # Presenter class, so multiple blocks accumulate.
     module Presenter
       # @return [Symbol] Plugin name
       def self.plugin_name
@@ -62,6 +71,11 @@ class Serega
         presenter_class = Class.new(Presenter)
         presenter_class.serializer_class = serializer_class
         serializer_class.const_set(:Presenter, presenter_class)
+
+        # The presenter's unwrap method returns the serialized object itself,
+        # not an association — it must never be auto-preloaded.
+        config = serializer_class.config
+        config.auto_preload_excluded_methods = config.auto_preload_excluded_methods | [:__getobj__]
       end
 
       # Presenter class
@@ -97,6 +111,44 @@ class Serega
         extend SeregaHelpers::SerializerClassHelper
         extend Forwardable
         include InstanceMethods
+
+        # Tracks whether user code was added to the Presenter class.
+        #
+        # These singleton methods are defined after the base class body above,
+        # so the plugin's own includes do not mark the base class as modified.
+        # Lazy delegators defined by #method_missing do mark the class, but
+        # they can appear only on presenters that are already wrapping.
+        class << self
+          #
+          # Checks if this Presenter class (or an inherited one) was extended
+          # with custom user code and therefore objects must be wrapped
+          #
+          # @return [Boolean] whether custom presenter methods were defined
+          #
+          def modified?
+            return true if defined?(@modified)
+            return false if equal?(Presenter) # the plugin's base class — the walk stops here
+
+            superclass.modified?
+          end
+
+          def include(*modules)
+            @modified = true
+            super
+          end
+
+          def prepend(*modules)
+            @modified = true
+            super
+          end
+
+          private
+
+          def method_added(name)
+            @modified = true
+            super
+          end
+        end
       end
 
       #
@@ -105,6 +157,36 @@ class Serega
       # @see Serega
       #
       module ClassMethods
+        #
+        # Defines presenter methods — evaluates the block inside the
+        # serializer's own Presenter class. Multiple blocks accumulate.
+        #
+        #   presenter do
+        #     def name
+        #       [first_name, last_name].compact.join(" ")
+        #     end
+        #   end
+        #
+        # @return [void]
+        #
+        def presenter(&block)
+          raise SeregaError, "Provide a block with presenter methods: `presenter do ... end`" unless block
+
+          self::Presenter.class_exec(&block)
+          nil
+        end
+
+        #
+        # Checks if the serializer's Presenter class (or an inherited one) was
+        # extended with custom user code. When it was not, serialized objects
+        # are not wrapped in the Presenter at all.
+        #
+        # @return [Boolean] whether custom presenter methods were defined
+        #
+        def custom_presenter?
+          self::Presenter.modified?
+        end
+
         private
 
         def inherited(subclass)
@@ -122,14 +204,25 @@ class Serega
       # @see Serega::SeregaObjectSerializer
       #
       module SeregaObjectSerializerInstanceMethods
+        # The custom-presenter check is made once per object serializer here
+        # and its result is reused for every enqueued chunk of the level.
+        def initialize(**opts)
+          super
+          @wrap_in_presenter = self.class.serializer_class.custom_presenter?
+        end
+
         private
 
         #
         # Wraps each serialized object in Presenter.new(object, ctx) before it is
         # enqueued, so the whole level — value resolution and batch loaders alike —
-        # sees presenters.
+        # sees presenters. Objects are not wrapped when the Presenter class has
+        # no custom methods — such wrapping would only add overhead and break
+        # class checks (object.is_a?, Hash === object) without changing anything.
         #
         def enqueue(objects)
+          return super unless @wrap_in_presenter
+
           presenter = self.class.serializer_class::Presenter
           presenters = objects.map { |object| presenter.new(object, context) }
           super(presenters)

data/lib/serega/plugins/root/root.rb

@@ -244,7 +244,7 @@ class Serega
           return opts[:root] if opts.key?(:root)
 
           root = self.class.config.root
-          (opts.fetch(:many) { object.is_a?(Enumerable) }) ? root.many : root.one
+          (opts.fetch(:many) { SeregaUtils::CollectionDetector.call(object) }) ? root.many : root.one
         end
       end
 

data/lib/serega/utils/collection_detector.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaUtils
+    #
+    # Utility to check if an object should be serialized as a collection.
+    #
+    # Hashes and Structs are Enumerable, but enumerate their own member
+    # values, so they are treated as single objects.
+    #
+    class CollectionDetector
+      class << self
+        #
+        # Checks if provided object is a collection of objects
+        #
+        # @param object [Object] Serialized object
+        #
+        # @return [Boolean] whether object should be serialized as a collection
+        #
+        def call(object)
+          object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)
+        end
+      end
+    end
+  end
+end

data/lib/serega/validations/attribute/check_block.rb

@@ -10,25 +10,30 @@ class Serega
       # Attribute `block` parameter validator
       #
       class CheckBlock
+        # Explains the changed attribute block behavior. Shown when the block
+        # looks like an old-style value block — it accepts parameters or
+        # defines no attributes.
+        ERROR_MESSAGE =
+          "Attribute block now defines a nested serializer:" \
+          " it is executed in the context of a new serializer class and must define its attributes." \
+          " Defining the attribute value with a block is not supported anymore," \
+          " use the `value: <callable>` option instead."
+
         class << self
           #
           # Checks block parameter provided with attribute.
-          # Must have up to two arguments - object and context. Context can be
-          # also provided as keyword argument :ctx.
-          #
-          # @example without arguments
-          #   attribute(:email) { CONSTANT_EMAIL }
-          #
-          # @example with one argument
-          #   attribute(:email) { |obj| obj.confirmed_email }
           #
-          # @example with two arguments
-          #   attribute(:email) { |obj, context| context['is_current'] ? obj.email : nil }
+          # The block defines attributes of a nested anonymous serializer, so
+          # it is executed in the context of that serializer and must accept
+          # no parameters.
           #
-          # @example with one argument and keyword context
-          #   attribute(:email) { |obj, ctx:| obj.email if ctx[:show] }
+          # @example
+          #   attribute :statistics, method: :itself do
+          #     attribute :likes_count
+          #     attribute :comments_count
+          #   end
           #
-          # @param block [Proc] Block that returns serialized attribute value
+          # @param block [Proc] Block that defines nested serializer attributes
           #
           # @raise [SeregaError] SeregaError that block has invalid arguments
           #
@@ -37,48 +42,8 @@ class Serega
           def call(block)
             return unless block
 
-            check_block(block)
-          end
-
-          private
-
-          def check_block(block)
-            signature = SeregaUtils::MethodSignature.call(block, pos_limit: 2, keyword_args: [:ctx, :batches])
-
-            raise SeregaError, signature_error unless valid_signature?(signature)
-          end
-
-          def valid_signature?(signature)
-            case signature
-            when "0"             # no parameters
-              true
-            when "1"             # call(object)
-              true
-            when "1_ctx"         # call(object, ctx:)
-              true
-            when "1_batches"     # call(object, batches:)
-              true
-            when "1_batches_ctx" # call(object, batches:, ctx:)
-              true
-            when "2"             # call(object, context)
-              true
-            when "2_batches_ctx" # call(object, context, batches:, ctx:) (proc with no params)
-              true
-            else
-              false
-            end
-          end
-
-          def signature_error
-            <<~ERROR.strip
-              Invalid attribute block parameters, valid parameters signatures:
-              - ()                       # no parameters
-              - (object)                 # one positional parameter
-              - (object, ctx:)           # one positional parameter and :ctx keyword
-              - (object, batches:)       # one positional parameter and :batches keyword
-              - (object, ctx:, batches:) # one positional parameter, :ctx, and :batches keywords
-              - (object, context)        # two positional parameters
-            ERROR
+            signature = SeregaUtils::MethodSignature.call(block, pos_limit: 0)
+            raise SeregaError, ERROR_MESSAGE unless signature == "0"
           end
         end
       end

data/lib/serega/validations/attribute/check_opt_base_serializer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class Serega
+  module SeregaValidations
+    module Attribute
+      #
+      # Attribute `:base_serializer` option validator
+      #
+      class CheckOptBaseSerializer
+        class << self
+          #
+          # Checks attribute :base_serializer option. It specifies the parent
+          # class for the nested serializer defined with the attribute block,
+          # so it makes sense only when a block is provided.
+          #
+          # @param opts [Hash] Attribute options
+          # @param block [nil, Proc] Attribute block (defines a nested serializer)
+          #
+          # @raise [SeregaError] SeregaError that option has invalid value
+          #
+          # @return [void]
+          #
+          def call(opts, block = nil)
+            return unless opts.key?(:base_serializer)
+
+            raise SeregaError, "Option :base_serializer can be used only with a block" unless block
+
+            value = opts[:base_serializer]
+            return if value.is_a?(Class) && (value <= Serega)
+
+            raise SeregaError, "Invalid option :base_serializer => #{value.inspect}. Must be a Serega subclass"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/serega/validations/attribute/check_opt_batch.rb

@@ -17,11 +17,11 @@ class Serega
           #
           # @return [void]
           #
-          def call(serializer_class, opts, block)
+          def call(serializer_class, opts)
             return unless opts.key?(:batch)
 
             check_opt_batch(opts, serializer_class)
-            check_usage_with_other_params(opts, block)
+            check_usage_with_other_params(opts)
           end
 
           private
@@ -72,22 +72,22 @@ class Serega
             Utils::CheckAllowedKeys.call(batch_opts, %i[use id], :batch)
           end
 
-          def check_usage_with_other_params(opts, block)
+          def check_usage_with_other_params(opts)
             batch = opts[:batch]
             use_id = batch.is_a?(Hash) && batch.key?(:id)
             use_multiple = batch.is_a?(Hash) && (Array(batch[:use]).size > 1)
-            value_added = opts.key?(:value) || block
+            value_added = opts.key?(:value)
 
             if use_multiple && use_id
               raise SeregaError, "Option `batch.id` should not be used with multiple loaders provided in `batch.use`"
             end
 
             if use_multiple && !value_added
-              raise SeregaError, "Attribute :value option or block should be provided when selecting multiple batch loaders"
+              raise SeregaError, "Attribute :value option should be provided when selecting multiple batch loaders"
             end
 
             if use_id && value_added
-              raise SeregaError, "Option `batch.id` should not be used when :value or block provided directly"
+              raise SeregaError, "Option `batch.id` should not be used when :value option provided directly"
             end
 
             raise SeregaError, "Option :batch can not be used together with option :method" if opts.key?(:method)

data/lib/serega/validations/attribute/check_opt_const.rb

@@ -17,19 +17,18 @@ class Serega
           #
           # @return [void]
           #
-          def call(opts, block = nil)
+          def call(opts)
             return unless opts.key?(:const)
 
-            check_usage_with_other_params(opts, block)
+            check_usage_with_other_params(opts)
           end
 
           private
 
-          def check_usage_with_other_params(opts, block)
+          def check_usage_with_other_params(opts)
             raise SeregaError, "Option :const can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :const can not be used together with option :value" if opts.key?(:value)
             raise SeregaError, "Option :const can not be used together with option :batch" if opts.key?(:batch)
-            raise SeregaError, "Option :const can not be used together with block" if block
           end
         end
       end

data/lib/serega/validations/attribute/check_opt_delegate.rb

@@ -18,11 +18,11 @@ class Serega
           #
           # @return [void]
           #
-          def call(opts, block = nil)
+          def call(opts)
             return unless opts.key?(:delegate)
 
             check_opt_delegate(opts)
-            check_usage_with_other_params(opts, block)
+            check_usage_with_other_params(opts)
           end
 
           private
@@ -56,12 +56,11 @@ class Serega
             Utils::CheckAllowedKeys.call(delegate_opts, %i[to method allow_nil], :delegate)
           end
 
-          def check_usage_with_other_params(opts, block)
+          def check_usage_with_other_params(opts)
             raise SeregaError, "Option :delegate can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :delegate can not be used together with option :const" if opts.key?(:const)
             raise SeregaError, "Option :delegate can not be used together with option :value" if opts.key?(:value)
             raise SeregaError, "Option :delegate can not be used together with option :batch" if opts.key?(:batch)
-            raise SeregaError, "Option :delegate can not be used together with block" if block
           end
         end
       end

data/lib/serega/validations/attribute/check_opt_many.rb

@@ -12,28 +12,29 @@ class Serega
           # Checks attribute :many option
           #
           # @param opts [Hash] Attribute options
+          # @param block [nil, Proc] Attribute block
           #
           # @raise [SeregaError] SeregaError that option has invalid value
           #
           # @return [void]
           #
-          def call(opts)
+          def call(opts, block = nil)
             return unless opts.key?(:many)
 
-            check_many_option_makes_sence(opts)
+            check_many_option_makes_sence(opts, block)
             Utils::CheckOptIsBool.call(opts, :many)
           end
 
           private
 
-          def check_many_option_makes_sence(opts)
-            return if many_option_makes_sence?(opts)
+          def check_many_option_makes_sence(opts, block)
+            return if many_option_makes_sence?(opts, block)
 
-            raise SeregaError, "Option :many can be provided only together with :serializer or :batch option"
+            raise SeregaError, "Option :many can be provided only together with :serializer, :batch option or a block"
           end
 
-          def many_option_makes_sence?(opts)
-            opts[:serializer] || opts[:batch]
+          def many_option_makes_sence?(opts, block)
+            opts[:serializer] || opts[:batch] || block
           end
         end
       end

data/lib/serega/validations/attribute/check_opt_method.rb

@@ -17,20 +17,19 @@ class Serega
           #
           # @return [void]
           #
-          def call(opts, block = nil)
+          def call(opts)
             return unless opts.key?(:method)
 
-            check_usage_with_other_params(opts, block)
+            check_usage_with_other_params(opts)
             Utils::CheckOptIsStringOrSymbol.call(opts, :method)
           end
 
           private
 
-          def check_usage_with_other_params(opts, block)
+          def check_usage_with_other_params(opts)
             raise SeregaError, "Option :method can not be used together with option :const" if opts.key?(:const)
             raise SeregaError, "Option :method can not be used together with option :value" if opts.key?(:value)
             raise SeregaError, "Option :method can not be used together with option :batch" if opts.key?(:batch)
-            raise SeregaError, "Option :method can not be used together with block" if block
           end
         end
       end

data/lib/serega/validations/attribute/check_opt_serializer.rb

@@ -12,14 +12,17 @@ class Serega
           # Checks attribute :serializer option
           #
           # @param opts [Hash] Attribute options
+          # @param block [nil, Proc] Attribute block (defines a nested serializer)
           #
           # @raise [SeregaError] SeregaError that option has invalid value
           #
           # @return [void]
           #
-          def call(opts)
+          def call(opts, block = nil)
             return unless opts.key?(:serializer)
 
+            raise SeregaError, "Option :serializer can not be used together with block" if block
+
             value = opts[:serializer]
             return if valid_serializer?(value)
 

data/lib/serega/validations/attribute/check_opt_value.rb

@@ -17,20 +17,19 @@ class Serega
           #
           # @return [void]
           #
-          def call(opts, block = nil)
+          def call(opts)
             return unless opts.key?(:value)
 
-            check_usage_with_other_params(opts, block)
+            check_usage_with_other_params(opts)
 
             check_value(opts[:value])
           end
 
           private
 
-          def check_usage_with_other_params(opts, block)
+          def check_usage_with_other_params(opts)
             raise SeregaError, "Option :value can not be used together with option :method" if opts.key?(:method)
             raise SeregaError, "Option :value can not be used together with option :const" if opts.key?(:const)
-            raise SeregaError, "Option :value can not be used together with block" if block
           end
 
           def check_value(value)

data/lib/serega/validations/check_attribute_params.rb

@@ -59,15 +59,16 @@ class Serega
         def check_opts
           Utils::CheckAllowedKeys.call(opts, allowed_opts_keys, :attribute)
 
-          Attribute::CheckOptConst.call(opts, block)
-          Attribute::CheckOptDelegate.call(opts, block)
+          Attribute::CheckOptBaseSerializer.call(opts, block)
+          Attribute::CheckOptConst.call(opts)
+          Attribute::CheckOptDelegate.call(opts)
           Attribute::CheckOptHide.call(opts)
-          Attribute::CheckOptMethod.call(opts, block)
-          Attribute::CheckOptMany.call(opts)
+          Attribute::CheckOptMethod.call(opts)
+          Attribute::CheckOptMany.call(opts, block)
           Attribute::CheckOptPreload.call(opts)
-          Attribute::CheckOptSerializer.call(opts)
-          Attribute::CheckOptValue.call(opts, block)
-          Attribute::CheckOptBatch.call(self.class.serializer_class, opts, block)
+          Attribute::CheckOptSerializer.call(opts, block)
+          Attribute::CheckOptValue.call(opts)
+          Attribute::CheckOptBatch.call(self.class.serializer_class, opts)
         end
 
         def check_block

data/lib/serega.rb

@@ -19,6 +19,7 @@ end
 
 require_relative "serega/errors"
 require_relative "serega/helpers/serializer_class_helper"
+require_relative "serega/utils/collection_detector"
 require_relative "serega/utils/enum_deep_dup"
 require_relative "serega/utils/enum_deep_freeze"
 require_relative "serega/utils/method_signature"
@@ -40,6 +41,7 @@ require_relative "serega/validations/utils/check_opt_is_hash"
 require_relative "serega/validations/utils/check_opt_is_string_or_symbol"
 require_relative "serega/validations/attribute/check_block"
 require_relative "serega/validations/attribute/check_name"
+require_relative "serega/validations/attribute/check_opt_base_serializer"
 require_relative "serega/validations/attribute/check_opt_const"
 require_relative "serega/validations/attribute/check_opt_hide"
 require_relative "serega/validations/attribute/check_opt_delegate"
@@ -168,7 +170,19 @@ class Serega
     #
     # @param name [Symbol] Attribute name. Attribute value will be found by executing `object.<name>`
     # @param opts [Hash] Options to serialize attribute
-    # @param block [Proc] Custom block to find attribute value. Accepts object and context.
+    # @param block [Proc] Defines attributes of a nested anonymous serializer.
+    #   The block is executed in the context of that serializer, so everything
+    #   available in a serializer class body can be used inside. The attribute
+    #   value (found by name/:method/:value/:delegate/:const/:batch as usual)
+    #   is serialized with this nested serializer. The nested serializer
+    #   inherits from the `:base_serializer` attribute option or
+    #   `config.base_serializer` (one of them is required).
+    #
+    # @example
+    #   attribute :statistics, method: :itself do
+    #     attribute :likes_count
+    #     attribute :comments_count
+    #   end
     #
     # @return [Serega::SeregaAttribute] Added attribute
     #
@@ -254,7 +268,7 @@ class Serega
     # @option opts [Array, Hash, String, Symbol] :with Attributes (usually hidden) to serialize additionally
     # @option opts [Boolean] :validate Validates provided modifiers (Default is true)
     # @option opts [Hash] :context Serialization context
-    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
+    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
     #
     # @return [Hash] Serialization result
     #
@@ -275,7 +289,7 @@ class Serega
     # @option opts [Array, Hash, String, Symbol] :with Attributes (usually hidden) to serialize additionally
     # @option opts [Boolean] :validate Validates provided modifiers (Default is true)
     # @option opts [Hash] :context Serialization context
-    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
+    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
     #
     # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
     #
@@ -409,7 +423,7 @@ class Serega
     # @param object [Object] Serialized object
     # @param opts [Hash, nil] Serializing options
     # @option opts [Hash] :context Serialization context
-    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
+    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
     #
     # @return [Hash] Serialization result
     #
@@ -431,7 +445,7 @@ class Serega
     # @param object [Object] Serialized object
     # @param opts [Hash, nil] Serializing options
     # @option opts [Hash] :context Serialization context
-    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable)`)
+    # @option opts [Boolean] :many Set true if provided multiple objects (Default `object.is_a?(Enumerable) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
     #
     # @return [Data] Serialization result
     #
@@ -472,7 +486,7 @@ class Serega
 
       opts[:context] ||= {}
       opts[:level_queue] = SeregaEngine::LevelQueue.new
-      opts[:many] = object.is_a?(Enumerable) unless opts.key?(:many)
+      opts[:many] = SeregaUtils::CollectionDetector.call(object) unless opts.key?(:many)
       opts[:plan] = plan
       opts
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.38.0
+  version: 0.39.0
 platform: ruby
 authors:
 - Andrey Glushkov
@@ -70,6 +70,7 @@ files:
 - lib/serega/plugins/root/root.rb
 - lib/serega/plugins/string_modifiers/parse_string_modifiers.rb
 - lib/serega/plugins/string_modifiers/string_modifiers.rb
+- lib/serega/utils/collection_detector.rb
 - lib/serega/utils/enum_deep_dup.rb
 - lib/serega/utils/enum_deep_freeze.rb
 - lib/serega/utils/method_signature.rb
@@ -78,6 +79,7 @@ files:
 - lib/serega/utils/to_hash.rb
 - lib/serega/validations/attribute/check_block.rb
 - lib/serega/validations/attribute/check_name.rb
+- lib/serega/validations/attribute/check_opt_base_serializer.rb
 - lib/serega/validations/attribute/check_opt_batch.rb
 - lib/serega/validations/attribute/check_opt_const.rb
 - lib/serega/validations/attribute/check_opt_delegate.rb