serega 0.40.1 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edecae0c35540be687e394092e3b0a158fa1c2aeff4710ff5ce8e17effba1eb2
-  data.tar.gz: 7e63d238aad501f31be388824bb6b594e9f7988e17c49e4fc478d9353993c63b
+  metadata.gz: 4ec97ed9e6fc97612c5094991de19b1c5d43a44168e5a29593bdf75f77e5f200
+  data.tar.gz: 54d42defad67c2ea46bac516870caacb36ce38643826137900b46a8661001cc3
 SHA512:
-  metadata.gz: 506607362308145ffcc0a34474d76d8b0a0edb7fbb570deb1fb973c71c396aab65a1b7b408069d31c8a5e15f8c8146316f835194c53e4a68315fe62eb4992421
-  data.tar.gz: 6d5b5ebe921a36b197b4829721af89eb92f5e47522101d126cffc8c72e30ad2679a6f9084df2685cf2250d772c5b0974b76861260b2eb19c6f53660fba16f5d4
+  metadata.gz: 5c9f5c91fc97ae0b08578b6fb7c98c3718194094af81fb6175cd3854f602b8daa450204cd75b054cd9ee62586aed08f120b32d209a4817fb5bfdb74c6b83bd55
+  data.tar.gz: bd05febbd13a095a4e00f0336514c540c0781eac2707e29e8d9c64e6b4bc0152a7b717e05b93bfdca969e01b1fed4eeeeb52a330b3e9c7a820986b0b30e5b9e0

data/README.md

@@ -19,7 +19,8 @@ It has some great features:
 - Secure from malicious queries with [depth_limit][depth_limit] plugin
 - Solutions for N+1 problem (via built-in [batch loading](#batch-loading), [preloads][preloads] or
   [activerecord_preloads][activerecord_preloads] plugin)
-- Built-in object presenter ([presenter][presenter] plugin)
+- Load serialized objects by ids ([prepare_initial_objects](#prepare-initial-objects))
+- Built-in object presenter ([presenter][presenter])
 - Adding custom metadata (via [metadata][metadata] or
   [context_metadata][context_metadata] plugins)
 - Value formatters ([formatters][formatters] plugin) helps to transform
@@ -29,10 +30,51 @@ It has some great features:
 - Auto camelCase keys - [camel_case][camel_case] plugin
 - Serializing Hash records - [hash_access][hash_access] attribute option
 
+## Table of Contents
+
+<!-- toc -->
+
+- [Installation](#installation)
+- [Usage](#usage)
+   - [Define serializers](#define-serializers)
+   - [Adding attributes](#adding-attributes)
+   - [Defining a nested serializer with a block](#defining-a-nested-serializer-with-a-block)
+   - [Serializing](#serializing)
+   - [Selecting Fields](#selecting-fields)
+   - [Using Context](#using-context)
+   - [Batch Loading](#batch-loading)
+   - [Prepare Initial Objects](#prepare-initial-objects)
+- [Configuration](#configuration)
+- [Preloads](#preloads)
+   - [Serializing the same object in association](#serializing-the-same-object-in-association)
+   - [Custom preloading](#custom-preloading)
+- [Serializing Hash records](#serializing-hash-records)
+- [Presenter](#presenter)
+- [Plugins](#plugins)
+   - [Plugin :activerecord_preloads](#plugin-activerecord_preloads)
+   - [Plugin :root](#plugin-root)
+   - [Plugin :metadata](#plugin-metadata)
+   - [Plugin :context_metadata](#plugin-context_metadata)
+   - [Plugin :formatters](#plugin-formatters)
+   - [Plugin :string_modifiers](#plugin-string_modifiers)
+   - [Plugin :if](#plugin-if)
+   - [Plugin :camel_case](#plugin-camel_case)
+   - [Plugin :depth_limit](#plugin-depth_limit)
+   - [Plugin :explicit_many_option](#plugin-explicit_many_option)
+- [Errors](#errors)
+- [Release](#release)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+<!-- tocstop -->
+
 ## Installation
 
 `bundle add serega`
 
+## Usage
+
 ### Define serializers
 
 Most apps should define **base serializer** with common plugins and settings to
@@ -86,8 +128,8 @@ class UserSerializer < Serega
   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
+  # attributes. Note: with a custom presenter 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
@@ -463,6 +505,77 @@ class UserSerializer < Serega
 end
 ```
 
+### Prepare Initial Objects
+
+`prepare_initial_objects` replaces the serialized objects before serialization
+starts, so a serializer can accept ids or other references and load the records
+itself.
+
+```ruby
+class UserSerializer < Serega
+  # OccamsRecord returns read-only records — faster and with a much lower
+  # memory footprint than ActiveRecord models
+  prepare_initial_objects { |user_ids| OccamsRecord.query(User.where(id: user_ids)).run }
+
+  attribute :first_name
+end
+
+UserSerializer.to_h(["17", "42"]) # => [{first_name: "Ann"}, {first_name: "Bob"}]
+```
+
+The handler accepts the serialization context as a second positional or a
+`:ctx` keyword argument, and can be provided as a callable value:
+
+```ruby
+class UserSerializer < Serega
+  prepare_initial_objects { |ids, ctx| OccamsRecord.query(User.where(id: ids, account: ctx[:account])).run }
+  # or
+  prepare_initial_objects { |ids, ctx:| OccamsRecord.query(User.where(id: ids, account: ctx[:account])).run }
+  # or
+  prepare_initial_objects UsersLoader
+end
+```
+
+The handler runs once per serialization, before the `:many` option is detected,
+so it can turn a single object into a collection and back:
+
+```ruby
+class UserSerializer < Serega
+  prepare_initial_objects { |user_id| OccamsRecord.query(User.where(id: user_id)).run }
+
+  attribute :first_name
+end
+
+UserSerializer.to_h("17") # => [{first_name: "Ann"}] - an array, as the handler returned a collection
+```
+
+A provided `:many` option is used as is. A handler returning `nil` serializes
+`nil`, and errors raised inside the handler are not wrapped.
+
+Declared preloads are applied to the prepared objects, so the handler pairs
+with [preloads][preloads] and the
+[activerecord_preloads][activerecord_preloads] plugin:
+
+```ruby
+class UserSerializer < Serega
+  plugin :activerecord_preloads
+
+  prepare_initial_objects { |user_ids| User.where(id: user_ids) }
+
+  attribute :albums_count, preload: :albums, value: proc { |user| user.albums.size }
+end
+```
+
+⚠️ The `:preload` option needs ActiveRecord objects. When the handler returns
+anything else — OccamsRecord read-only records, Structs, Hashes, plain objects
+— preloading raises `Serega::SeregaError` (`Can't preload ... to ...`) during
+serialization. Load that data with [batch loading](#batch-loading) instead,
+which works with any objects.
+
+The handler runs for the serialized objects only, and not for objects of nested
+serializers. It is inherited by subclasses, so declare it on concrete
+serializers rather than on a base serializer shared by all of them.
+
 ## Configuration
 
 Here are the default options. Other options can be added with plugins.
@@ -592,7 +705,7 @@ end
 
 ---
 
-### SPECIFIC CASE: Serializing the same object in association
+### Serializing the same object in association
 
 For example, you show your current user as "user" and use the same user object
 to serialize "user_stats". `UserStatSerializer` relies on user fields and any
@@ -736,6 +849,62 @@ attribute :city,
   }
 ```
 
+## Presenter
+
+Moves computed attribute logic out of `:value` blocks and into a
+`presenter do ... end` block, keeping serializers readable as schemas rather
+than bags of lambdas.
+
+Computed attributes can be written as inline blocks:
+
+```ruby
+class UserSerializer < Serega
+  attribute :name, value: proc { |user| [user.first_name, user.last_name].compact.join(' ') }
+  attribute :role, value: proc { |user, ctx| user.id == ctx[:current_user_id] ? :self : :other }
+end
+```
+
+They can also be written as methods in a `presenter do ... end` block:
+
+```ruby
+class UserSerializer < Serega
+  attribute :name
+  attribute :role
+
+  presenter do
+    def name
+      [first_name, last_name].compact.join(' ')
+    end
+
+    def role
+      id == __ctx__[:current_user_id] ? :self : :other
+    end
+  end
+end
+
+user = OpenStruct.new(id: 1, first_name: 'Bruce', last_name: 'Wayne')
+UserSerializer.to_h(user, context: {current_user_id: 1})
+# => {name: "Bruce Wayne", role: :self}
+```
+
+Multiple `presenter` blocks accumulate. A child serializer runs its parent's
+blocks followed by its own, so it gets the parent's presenter methods while its
+own stay out of the parent. The parent's blocks are copied when the child class
+is created, so a `presenter` block added to a parent afterwards does not reach it.
+
+Presenter methods run on a `SimpleDelegator` wrapping the serialized object, so
+every method of that object is available directly. Any method not defined in a
+`presenter` block is delegated to the object on the first call, and a real
+delegator method is defined for it — so all subsequent serializations call it
+directly.
+
+The wrapped object is accessible via `__getobj__` when you need an unambiguous
+reference to it. The serialization context is accessible via `__ctx__`.
+
+Objects are wrapped only when the serializer has presenter methods. A serializer
+without them costs nothing — its attribute values, batch loaders and value
+callables receive the raw objects.
+
 ## Plugins
 
 ### Plugin :activerecord_preloads
@@ -936,61 +1105,6 @@ class UserSerializer < Serega
 end
 ```
 
-### Plugin :presenter
-
-Moves computed attribute logic out of blocks and into a dedicated `Presenter` class,
-keeping serializers readable as schemas rather than bags of lambdas.
-
-Without the plugin, computed attributes live as inline blocks:
-
-```ruby
-class UserSerializer < Serega
-  attribute :name, value: proc { |u| [u.first_name, u.last_name].compact.join(' ') }
-  attribute :role, value: proc { |u, ctx| u == ctx[:current_user] ? :self : :other }
-end
-```
-
-With the plugin, they move into a `presenter do ... end` block:
-
-```ruby
-class UserSerializer < Serega
-  plugin :presenter
-
-  attribute :name
-  attribute :role
-
-  presenter do
-    def name
-      [first_name, last_name].compact.join(' ')
-    end
-
-    def role
-      id == __ctx__[:current_user_id] ? :self : :other
-    end
-  end
-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
-also defines a real delegator method — so all subsequent serializations call it
-directly, without going through `method_missing` again.
-
-The original wrapped object is accessible via `__getobj__` (standard
-`SimpleDelegator` API) when you need an unambiguous reference to it.
-
-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 `:only`, `:except` and `:with` to be given as a single comma-separated
@@ -1185,7 +1299,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 [hash_access]: #serializing-hash-records
 [metadata]: #plugin-metadata
 [preloads]: #preloads
-[presenter]: #plugin-presenter
+[presenter]: #presenter
 [root]: #plugin-root
 [string_modifiers]: #plugin-string_modifiers
 [if]: #plugin-if

data/VERSION

@@ -1 +1 @@
-0.40.1
+0.42.0

data/lib/serega/config.rb

@@ -33,7 +33,7 @@ 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,
+      auto_preload_excluded_methods: %i[itself __getobj__].freeze,
       hide_by_default: false,
       batch_id_option: :id,
       base_serializer: nil,

data/lib/serega/object_serializer.rb

@@ -16,7 +16,7 @@ class Serega
     #
     # @private
     module InstanceMethods
-      attr_reader :context, :plan, :many, :opts, :level_queue
+      attr_reader :context, :plan, :many, :opts, :level_queue, :presenter
 
       # @param plan [SeregaPlan] Serialization plan
       # @param context [Hash] Serialization context
@@ -30,6 +30,8 @@ class Serega
         @many = many
         @opts = opts
         @level_queue = opts[:level_queue]
+        # Looked up once here and reused for every enqueued chunk of the level.
+        @presenter = self.class.serializer_class.presenter
       end
 
       # Enqueues this level and returns its result container(s). The containers are
@@ -78,9 +80,14 @@ class Serega
       # containers. This is where objects enter their level, so every object a
       # point resolves against and a batch loader receives has the same shape.
       #
-      # Patched in:
-      # - plugin :presenter (wraps each object in a Presenter before enqueueing)
+      # Each object is wrapped in the serializer's presenter before it is enqueued,
+      # so the whole level — value resolution and batch loaders alike — sees
+      # presenters. Serializers without a presenter enqueue the objects as they
+      # are — wrapping would only add overhead and break class checks
+      # (object.is_a?, Hash === object) without changing anything.
       def enqueue(objects)
+        objects = objects.map { |object| presenter.new(object, context) } if presenter
+
         level_queue.enqueue(self, objects)
       end
 

data/lib/serega/plan_point.rb

@@ -85,12 +85,18 @@ class Serega
       # Runs this point's declared preloads over the given objects using the
       # serializer's registered preload handler.
       #
+      # Presenters are unwrapped first, as preload handlers work with the
+      # serialized objects themselves.
+      #
       # @param objects [Array] objects serialized at this point's level
       # @return [void]
       def run_preloads(objects)
         return unless preloads
 
-        handler = self.class.serializer_class.preload_with
+        serializer_class = self.class.serializer_class
+        objects = objects.map(&:__getobj__) if serializer_class.presenter
+
+        handler = serializer_class.preload_with
         unless handler
           raise SeregaError, "The :preload option requires a preload handler. Register one with `preload_with` (the :activerecord_preloads plugin does this for you)."
         end

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

@@ -88,28 +88,9 @@ class Serega
       # @private
       def self.after_load_plugin(serializer_class, **_opts)
         serializer_class.preload_with do |objects, preloads|
-          Preloader.preload(ActiverecordPreloads.records(serializer_class, objects), preloads)
+          Preloader.preload(objects, preloads)
         end
       end
-
-      #
-      # 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
-      #
-      # @return [Array] the underlying records
-      #
-      # @private
-      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
     end
 
     register_plugin(ActiverecordPreloads.plugin_name, ActiverecordPreloads)

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

@@ -229,6 +229,8 @@ class Serega
         # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
         #
         def to_data(object, opts = nil)
+          opts = normalize_serialization_opts(opts)
+          object = prepare_objects(object, opts[:context])
           opts = prepare_initial_serialization_opts(object, opts)
           serialized_data = serialize(object, opts)
           self.class::SeregaDataBuilder.call(self, serialized_data, opts)

data/lib/serega/plugins.rb

@@ -30,10 +30,10 @@ class Serega
       # @raise [SeregaError] Raises SeregaError when plugin was not found
       #
       # @example Find plugin when providing name
-      #   SeregaPlugins.find_plugin(:presenter) # => SeregaPlugins::Presenter
+      #   SeregaPlugins.find_plugin(:root) # => SeregaPlugins::Root
       #
       # @example Find plugin when providing plugin itself
-      #   SeregaPlugins.find_plugin(Presenter) # => Presenter
+      #   SeregaPlugins.find_plugin(Root) # => Root
       #
       # @return [Class<Module>] Plugin core module
       #

data/lib/serega/presenter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "delegate"
+require "forwardable"
+
+class Serega
+  #
+  # Wraps the serialized object, so computed attribute values can be defined as
+  # methods instead of `:value` callables.
+  #
+  # SeregaPresenter inherits from SimpleDelegator:
+  # - All methods of the serialized object are available directly inside presenter methods.
+  # - Methods not defined on SeregaPresenter are resolved via method_missing on the first call
+  #   and then defined as real delegators, so subsequent calls skip method_missing entirely.
+  # - The original object is accessible via __getobj__ (standard SimpleDelegator API).
+  # - The serialization context is accessible via the private method __ctx__.
+  #
+  # The `presenter do ... end` block is evaluated inside the serializer's own
+  # SeregaPresenter class, so multiple blocks accumulate.
+  #
+  # @example
+  #   class UserSerializer < Serega
+  #     attribute :name
+  #     attribute :role
+  #
+  #     presenter do
+  #       def name
+  #         [first_name, last_name].compact.join(' ') # first_name/last_name delegated to object
+  #       end
+  #
+  #       def role
+  #         id == __ctx__[:current_user_id] ? :self : :other
+  #       end
+  #     end
+  #   end
+  #
+  # @private
+  class SeregaPresenter < SimpleDelegator
+    #
+    # @param object [Object] Serialized object to wrap
+    # @param ctx [Hash, nil] Serialization context
+    #
+    def initialize(object, ctx = nil)
+      super(object)
+      @__ctx__ = ctx
+    end
+
+    private
+
+    attr_reader :__ctx__
+
+    #
+    # Delegates all missing methods to serialized object.
+    #
+    # Creates delegator method after first #method_missing hit to improve
+    # performance of following serializations.
+    #
+    def method_missing(name, *_args, &_block) # rubocop:disable Style/MissingRespondToMissing -- base SimpleDelegator class has this method
+      super.tap do
+        self.class.def_delegator :__getobj__, name
+      end
+    end
+
+    extend Forwardable
+  end
+end

data/lib/serega.rb

@@ -62,6 +62,7 @@ require_relative "serega/validations/check_batch_loader_params"
 require_relative "serega/validations/check_serialize_params"
 
 require_relative "serega/config"
+require_relative "serega/presenter"
 require_relative "serega/object_serializer"
 require_relative "serega/plan_point"
 require_relative "serega/plan"
@@ -70,6 +71,7 @@ require_relative "serega/plugins"
 
 class Serega
   @config = SeregaConfig.new
+  @presenter_class = nil
 
   # Validates `Serializer.attribute` params
   check_attribute_params_class = Class.new(SeregaValidations::CheckAttributeParams)
@@ -170,10 +172,17 @@ class Serega
     end
 
     #
-    # Adds attribute
+    # Lists blocks given to `presenter`, in definition order
     #
-    # Patched in:
-    # - plugin :presenter (additionally adds method in Presenter class)
+    # @return [Array<Proc>] presenter blocks list
+    #
+    # @private
+    def presenter_blocks
+      @presenter_blocks ||= []
+    end
+
+    #
+    # Adds attribute
     #
     # @param name [Symbol] Attribute name. Attribute value will be found by executing `object.<name>`
     # @param opts [Hash] Options to serialize attribute
@@ -233,6 +242,30 @@ class Serega
       batch_loaders[batch_loader.name] = batch_loader
     end
 
+    #
+    # 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
+    #
+    # @param block [Proc] Presenter methods
+    #
+    # @return [Class<SeregaPresenter>, nil] the serializer presenter class,
+    #   nil when the serializer has none
+    #
+    def presenter(&block)
+      return @presenter_class unless block
+
+      @presenter_class ||= Class.new(SeregaPresenter)
+      @presenter_class.class_exec(&block)
+      presenter_blocks << block
+      @presenter_class
+    end
+
     #
     # Registers (or returns) the handler used to preload an attribute's
     # associations onto the records gathered during serialization.
@@ -265,6 +298,63 @@ class Serega
       @preload_with = handler
     end
 
+    #
+    # Registers (or returns) the handler that replaces the serialized objects
+    # before serialization starts.
+    #
+    # The handler is called once per serialization with the objects provided to
+    # `.call`/`.to_h`/`.to_data` and the serialization context. Its result is
+    # serialized instead of the provided objects, which allows to accept ids or
+    # other references and load the records in one place.
+    #
+    # The handler runs before the `:many` option is detected, so it may turn a
+    # single object into a collection and back. A provided `:many` serialization
+    # option is still used as is.
+    #
+    # The handler runs only for the serialized objects, and not for objects of
+    # nested serializers.
+    #
+    # @example with a block
+    #   prepare_initial_objects { |user_ids| User.where(id: user_ids) }
+    #
+    # @example with a context
+    #   prepare_initial_objects { |user_ids, ctx| User.where(id: user_ids, account: ctx[:account]) }
+    #
+    # @example with a keyword context
+    #   prepare_initial_objects { |user_ids, ctx:| User.where(id: user_ids, account: ctx[:account]) }
+    #
+    # @example with a callable value
+    #   prepare_initial_objects UsersLoader
+    #
+    # @param value [#call, nil] Handler accepting (objects), (objects, context) or (objects, ctx:)
+    # @param block [Proc] Handler accepting (objects), (objects, context) or (objects, ctx:)
+    #
+    # @return [#call, nil] The registered handler
+    #
+    def prepare_initial_objects(value = nil, &block)
+      return @prepare_initial_objects if value.nil? && block.nil?
+      raise SeregaError, "prepare_initial_objects accepts a single callable or a block, not both" if value && block
+
+      handler = value || block
+      raise SeregaError, "prepare_initial_objects value must be a Proc or respond to #call" if !handler.is_a?(Proc) && !handler.respond_to?(:call)
+
+      signature = SeregaUtils::MethodSignature.call(handler, pos_limit: 2, keyword_args: [:ctx])
+      raise SeregaError, prepare_initial_objects_signature_error unless %w[1 2 1_ctx].include?(signature)
+
+      @prepare_initial_objects_signature = signature
+      @prepare_initial_objects = handler
+    end
+
+    #
+    # Signature of the registered prepare_initial_objects handler
+    #
+    # @return [String, nil] Handler signature
+    #
+    # @private
+    def prepare_initial_objects_signature
+      @prepare_initial_objects_signature
+    end
+
     #
     # Serializes provided object to Hash
     #
@@ -321,7 +411,6 @@ class Serega
 
     # Patched in:
     # - plugin :metadata (defines MetaAttribute and copies meta_attributes to subclasses)
-    # - plugin :presenter (defines Presenter)
     def inherited(subclass)
       config_class = Class.new(self::SeregaConfig)
       config_class.serializer_class = subclass
@@ -386,8 +475,25 @@ class Serega
       # Assign same preload handler
       subclass.preload_with(preload_with) if preload_with
 
+      # Assign same initial objects handler
+      subclass.prepare_initial_objects(prepare_initial_objects) if prepare_initial_objects
+
+      # Assign same presenter blocks
+      presenter_blocks.each do |presenter_block|
+        subclass.presenter(&presenter_block)
+      end
+
       super
     end
+
+    def prepare_initial_objects_signature_error
+      <<~ERR.strip
+        prepare_initial_objects handler arguments should have one of this signatures:
+        - (objects)        # one argument
+        - (objects, ctx)   # two arguments
+        - (objects, ctx:)  # one argument and one :ctx keyword argument
+      ERR
+    end
   end
 
   #
@@ -436,6 +542,8 @@ class Serega
     # @return [Hash] Serialization result
     #
     def call(object, opts = nil)
+      opts = normalize_serialization_opts(opts)
+      object = prepare_objects(object, opts[:context])
       opts = prepare_initial_serialization_opts(object, opts)
       serialize(object, opts)
     end
@@ -458,6 +566,8 @@ class Serega
     # @return [Data] Serialization result
     #
     def to_data(object, opts = nil)
+      opts = normalize_serialization_opts(opts)
+      object = prepare_objects(object, opts[:context])
       opts = prepare_initial_serialization_opts(object, opts)
       serialized_data = serialize(object, opts)
       self.class::SeregaDataBuilder.call(self, serialized_data)
@@ -488,11 +598,26 @@ class Serega
       SeregaUtils::ToHash.call(value)
     end
 
-    def prepare_initial_serialization_opts(object, opts)
+    def normalize_serialization_opts(opts)
       opts = opts ? opts.transform_keys(&:to_sym) : {}
       self.class::CheckSerializeParams.new(opts).validate unless opts.empty?
 
       opts[:context] ||= {}
+      opts
+    end
+
+    def prepare_objects(objects, context)
+      handler = self.class.prepare_initial_objects
+      return objects unless handler
+
+      case self.class.prepare_initial_objects_signature
+      when "1" then handler.call(objects)
+      when "2" then handler.call(objects, context)
+      else handler.call(objects, ctx: context) # "1_ctx"
+      end
+    end
+
+    def prepare_initial_serialization_opts(object, opts)
       opts[:level_queue] = SeregaEngine::LevelQueue.new
       opts[:many] = SeregaUtils::CollectionDetector.call(object) unless opts.key?(:many)
       opts[:plan] = plan

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: serega
 version: !ruby/object:Gem::Version
-  version: 0.40.1
+  version: 0.42.0
 platform: ruby
 authors:
 - Andrey
@@ -64,10 +64,10 @@ files:
 - lib/serega/plugins/metadata/validations/check_opt_value.rb
 - lib/serega/plugins/metadata/validations/check_opts.rb
 - lib/serega/plugins/metadata/validations/check_path.rb
-- lib/serega/plugins/presenter/presenter.rb
 - 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/presenter.rb
 - lib/serega/utils/collection_detector.rb
 - lib/serega/utils/enum_deep_dup.rb
 - lib/serega/utils/enum_deep_freeze.rb

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

@@ -1,242 +0,0 @@
-# frozen_string_literal: true
-
-require "delegate"
-require "forwardable"
-
-class Serega
-  module SeregaPlugins
-    #
-    # Plugin :presenter — moves computed attribute logic into a dedicated Presenter class.
-    #
-    # Presenter inherits from SimpleDelegator:
-    # - All methods of the serialized object are available directly inside presenter methods.
-    # - Methods not defined on Presenter are resolved via method_missing on the first call
-    #   and then defined as real delegators, so subsequent calls skip method_missing entirely.
-    # - The original object is accessible via __getobj__ (standard SimpleDelegator API).
-    # - The serialization context is accessible via the private method __ctx__.
-    #
-    # The `presenter do ... end` block is evaluated inside the serializer's own
-    # Presenter class, so multiple blocks accumulate.
-    #
-    # @example
-    #   class UserSerializer < Serega
-    #     plugin :presenter
-    #
-    #     attribute :name
-    #     attribute :role
-    #
-    #     presenter do
-    #       def name
-    #         [first_name, last_name].compact.join(' ') # first_name/last_name delegated to object
-    #       end
-    #
-    #       def role
-    #         id == __ctx__[:current_user_id] ? :self : :other
-    #       end
-    #     end
-    #   end
-    #
-    module Presenter
-      # @return [Symbol] Plugin name
-      # @private
-      def self.plugin_name
-        :presenter
-      end
-
-      #
-      # Applies plugin code to specific serializer
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param _opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.load_plugin(serializer_class, **_opts)
-        serializer_class.extend(ClassMethods)
-        serializer_class::SeregaObjectSerializer.include(SeregaObjectSerializerInstanceMethods)
-      end
-
-      #
-      # Runs callbacks after plugin was attached
-      #
-      # @param serializer_class [Class<Serega>] Current serializer class
-      # @param _opts [Hash] Plugin options
-      #
-      # @return [void]
-      #
-      # @private
-      def self.after_load_plugin(serializer_class, **_opts)
-        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
-      # @private
-      class Presenter < SimpleDelegator
-        # Presenter instance methods
-        # @private
-        module InstanceMethods
-          #
-          # @param object [Object] Serialized object to wrap
-          # @param ctx [Hash, nil] Serialization context
-          #
-          def initialize(object, ctx = nil)
-            super(object)
-            @__ctx__ = ctx
-          end
-
-          private
-
-          attr_reader :__ctx__
-
-          #
-          # Delegates all missing methods to serialized object.
-          #
-          # Creates delegator method after first #method_missing hit to improve
-          # performance of following serializations.
-          #
-          def method_missing(name, *_args, &_block) # rubocop:disable Style/MissingRespondToMissing -- base SimpleDelegator class has this method
-            super.tap do
-              self.class.def_delegator :__getobj__, name
-            end
-          end
-        end
-
-        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
-
-          # Marks the class as modified, then includes the module
-          # @return [void]
-          def include(*modules)
-            @modified = true
-            super
-          end
-
-          # Marks the class as modified, then prepends the module
-          # @return [void]
-          def prepend(*modules)
-            @modified = true
-            super
-          end
-
-          private
-
-          def method_added(name)
-            @modified = true
-            super
-          end
-        end
-      end
-
-      #
-      # Serega additional/patched class methods
-      #
-      # @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
-        #
-        # @private
-        def custom_presenter?
-          self::Presenter.modified?
-        end
-
-        private
-
-        def inherited(subclass)
-          super
-
-          presenter_class = Class.new(self::Presenter)
-          presenter_class.serializer_class = subclass
-          subclass.const_set(:Presenter, presenter_class)
-        end
-      end
-
-      #
-      # SeregaObjectSerializer additional/patched class methods
-      #
-      # @see Serega::SeregaObjectSerializer
-      #
-      # @private
-      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. 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)
-        end
-      end
-    end
-
-    register_plugin(Presenter.plugin_name, Presenter)
-  end
-end