serega 0.42.0 → 0.50.0

data/lib/serega.rb

@@ -1,53 +1,81 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "serega/version"
 
-# Parent class for your serializers
+# Parent class of serializers. A serializer lists attributes and serializes
+# objects to Hashes, JSON, Data or Struct objects:
+#
+# ```ruby
+# class UserSerializer < Serega
+#   attribute :first_name
+#   attribute :email, hide: true
+# end
+#
+# UserSerializer.to_h(user)                # => {first_name: "Bruce"}
+# UserSerializer.to_h(user, with: :email)  # => {first_name: "Bruce", email: "bruce@wayne.com"}
+# ```
+#
+# See the [guides](https://github.com/andreyruby/serega/blob/master/docs/README.md).
 class Serega
   # Frozen hash
-  # @return [Hash] frozen hash
-  # @private
-  FROZEN_EMPTY_HASH = {}.freeze
+  FROZEN_EMPTY_HASH = {}.freeze # :nodoc:
 
   # Frozen array
-  # @return [Array] frozen array
-  # @private
-  FROZEN_EMPTY_ARRAY = [].freeze
+  FROZEN_EMPTY_ARRAY = [].freeze # :nodoc:
 
-  # Empty modifiers/serialization options (used when serializing with no opts provided)
-  FROZEN_EMPTY_OPTS = [FROZEN_EMPTY_HASH, nil].freeze
-  private_constant :FROZEN_EMPTY_OPTS
+  # Locks serializers one at a time
+  LOCK_MUTEX = Mutex.new # :nodoc:
+
+  # Errors raised when another Ractor reads a value that is not shareable,
+  # empty on a Ruby without Ractors
+  # :nocov:
+  RACTOR_ISOLATION_ERRORS = (defined?(Ractor) ? [Ractor::IsolationError] : []).freeze # :nodoc:
+  # :nocov:
+
+  # Path prefix of the Serega source files
+  LIB_PATH = File.expand_path("serega", __dir__).freeze # :nodoc:
 end
 
 require_relative "serega/errors"
-require_relative "serega/helpers/serializer_class_helper"
 require_relative "serega/utils/collection_detector"
+require_relative "serega/utils/deep_merge"
 require_relative "serega/utils/enum_deep_dup"
 require_relative "serega/utils/enum_deep_freeze"
 require_relative "serega/utils/method_signature"
+require_relative "serega/utils/parse_string_modifiers"
+require_relative "serega/utils/ractor_local"
 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"
 require_relative "serega/attribute_value_resolvers/const"
 require_relative "serega/attribute_value_resolvers/delegate"
 require_relative "serega/attribute_value_resolvers/hash_access"
 require_relative "serega/attribute_value_resolvers/keyword"
+require_relative "serega/attribute_values"
+require_relative "serega/conditions"
+require_relative "serega/formatter"
 require_relative "serega/attribute"
+require_relative "serega/attribute_normalizers/batch"
+require_relative "serega/attribute_normalizers/block"
+require_relative "serega/attribute_normalizers/delegate"
+require_relative "serega/attribute_normalizers/hash_access"
+require_relative "serega/attribute_normalizers/preloads"
 require_relative "serega/attribute_normalizer"
-require_relative "serega/engine/level_queue"
-require_relative "serega/engine/level"
-require_relative "serega/engine/loader"
+require_relative "serega/engine/run"
+require_relative "serega/engine/pulls"
 require_relative "serega/validations/utils/check_allowed_keys"
+require_relative "serega/validations/utils/check_hash_access_value"
 require_relative "serega/validations/utils/check_opt_is_bool"
 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_condition"
 require_relative "serega/validations/attribute/check_opt_hide"
 require_relative "serega/validations/attribute/check_opt_delegate"
+require_relative "serega/validations/attribute/check_opt_format"
 require_relative "serega/validations/attribute/check_opt_batch"
 require_relative "serega/validations/attribute/check_opt_hash_access"
 require_relative "serega/validations/attribute/check_opt_many"
@@ -57,209 +85,227 @@ require_relative "serega/validations/attribute/check_opt_serializer"
 require_relative "serega/validations/attribute/check_opt_value"
 require_relative "serega/validations/initiate/check_modifiers"
 require_relative "serega/validations/check_attribute_params"
-require_relative "serega/validations/check_initiate_params"
 require_relative "serega/validations/check_batch_loader_params"
-require_relative "serega/validations/check_serialize_params"
+require_relative "serega/validations/check_formatter"
+require_relative "serega/validations/check_serialize_keywords"
 
+require_relative "serega/batch_loader"
 require_relative "serega/config"
 require_relative "serega/presenter"
-require_relative "serega/object_serializer"
+require_relative "serega/source_group"
 require_relative "serega/plan_point"
 require_relative "serega/plan"
-require_relative "serega/data_builder"
+require_relative "serega/result_code"
+require_relative "serega/result_builder"
+require_relative "serega/plan/cache"
 require_relative "serega/plugins"
 
 class Serega
-  @config = SeregaConfig.new
-  @presenter_class = nil
-
-  # Validates `Serializer.attribute` params
-  check_attribute_params_class = Class.new(SeregaValidations::CheckAttributeParams)
-  check_attribute_params_class.serializer_class = self
-  const_set(:CheckAttributeParams, check_attribute_params_class)
-
-  # Validates `Serializer#new` params
-  check_initiate_params_class = Class.new(SeregaValidations::CheckInitiateParams)
-  check_initiate_params_class.serializer_class = self
-  const_set(:CheckInitiateParams, check_initiate_params_class)
-
-  # Validates `serializer#call(obj, PARAMS)` params
-  check_serialize_params_class = Class.new(SeregaValidations::CheckSerializeParams)
-  check_serialize_params_class.serializer_class = self
-  const_set(:CheckSerializeParams, check_serialize_params_class)
-
-  # Validates `Serializer.batch` params
-  check_batch_loader_params_class = Class.new(SeregaValidations::CheckBatchLoaderParams)
-  check_batch_loader_params_class.serializer_class = self
-  const_set(:CheckBatchLoaderParams, check_batch_loader_params_class)
-
-  # Assigns `SeregaEngineLoader` constant to current class
-  engine_loader_class = Class.new(SeregaEngine::Loader)
-  engine_loader_class.serializer_class = self
-  const_set(:SeregaEngineLoader, engine_loader_class)
-
   #
-  # Serializers class methods
+  # Class methods of serializers: they define attributes and serialize
   #
   module ClassMethods
-    # Returns current config
-    # @return [SeregaConfig] current serializer config
+    # Config of the serializer. Subclasses copy it.
+    #
+    # ```ruby
+    # config.hide_by_default = true
+    # ```
+    #
+    # See [Configuration](https://github.com/andreyruby/serega/blob/master/docs/configuration.md).
     attr_reader :config
+
     #
-    # Enables plugin for current serializer
+    # Turns on a built-in feature by name, with its options. Subclasses get it
+    # too.
     #
-    # @param name [Symbol, Class<Module>] Plugin name or plugin module itself
-    # @param opts [Hash>] Plugin options
+    # ```ruby
+    # plugin :root, root_one: :user, root_many: :users
+    # ```
     #
-    # @return [class<Module>] Loaded plugin module
+    # See [Root Key and Metadata](https://github.com/andreyruby/serega/blob/master/docs/root-and-metadata.md).
     #
     def plugin(name, **opts)
+      check_unlocked
       raise SeregaError, "This plugin is already loaded" if plugin_used?(name)
 
-      plugin = SeregaPlugins.find_plugin(name)
-
-      # We split loading of plugin to three parts - before_load, load, after_load:
-      #
-      # - **before_load_plugin** usually used to check requirements and to load additional plugins
-      # - **load_plugin** usually used to include plugin modules
-      # - **after_load_plugin** usually used to add config options
-      plugin.before_load_plugin(self, **opts) if plugin.respond_to?(:before_load_plugin)
-      plugin.load_plugin(self, **opts) if plugin.respond_to?(:load_plugin)
-      plugin.after_load_plugin(self, **opts) if plugin.respond_to?(:after_load_plugin)
-
-      # Store attached plugins, so we can check it is loaded later
-      config.plugins << (plugin.respond_to?(:plugin_name) ? plugin.plugin_name : plugin)
+      plugin = SeregaPlugins.find(name)
+      plugin.apply(self, **opts)
+      config.plugins << name
 
       plugin
     end
 
-    #
     # Checks plugin is used
-    #
-    # @param name [Symbol, Class<Module>] Plugin name or plugin module itself
-    #
-    # @return [Boolean] Is plugin used
-    #
-    # @private
-    def plugin_used?(name)
-      plugin_name =
-        case name
-        when Module then name.respond_to?(:plugin_name) ? name.plugin_name : name
-        else name
-        end
-
-      config.plugins.include?(plugin_name)
+    def plugin_used?(name) # :nodoc:
+      config.plugins.include?(name)
     end
 
     #
-    # Lists attributes
+    # Attributes by name, hidden and inherited ones too
     #
-    # @return [Hash] attributes list
+    # ```ruby
+    # UserSerializer.attributes.keys # => [:first_name, :email]
+    # ```
     #
-    # @private
     def attributes
-      @attributes ||= {}
+      @attributes
     end
 
-    #
     # Lists defined batch loaders
-    #
-    # @return [Hash] batch loaders list
-    #
-    # @private
-    def batch_loaders
-      @batch_loaders ||= {}
+    def batch_loaders # :nodoc:
+      @batch_loaders
+    end
+
+    # Lists defined formatters
+    def formatters # :nodoc:
+      @formatters
+    end
+
+    # Cached serialization plans
+    def plan_cache # :nodoc:
+      @plan_cache
+    # :nocov:
+    rescue *RACTOR_ISOLATION_ERRORS
+      raise SeregaError, @unshareable_reason if @unshareable_reason
+
+      raise SeregaError, "#{self} can not serialize in other Ractors. Call `make_shareable!` at the end of its definition"
+      # :nocov:
+    end
+
+    # Returns the presenter class that wraps objects in the current Ractor,
+    # `nil` without presenter methods. A shareable serializer gives each
+    # Ractor its own subclass of the presenter, which defines delegators
+    # in its own `Delegators` module.
+    def local_presenter # :nodoc:
+      key = @presenter_key
+      return @presenter_class unless key
+
+      SeregaUtils::RactorLocal.fetch(key) { Class.new(@presenter_class) }
     end
 
-    #
     # Lists blocks given to `presenter`, in definition order
-    #
-    # @return [Array<Proc>] presenter blocks list
-    #
-    # @private
-    def presenter_blocks
-      @presenter_blocks ||= []
+    def presenter_blocks # :nodoc:
+      @presenter_blocks
+    end
+
+    # Returns (and caches) the Data class of the serialized objects with the
+    # given members
+    def data_class_for(point_names) # :nodoc:
+      classes = @data_classes
+      classes = SeregaUtils::RactorLocal.fetch(SeregaUtils::RactorLocal.key(self, :data_classes)) { {} } if classes.frozen?
+      classes[point_names] ||= Data.define(*point_names)
+    end
+
+    # Returns (and caches) the Struct class of the serialized objects with
+    # the given members
+    def struct_class_for(point_names) # :nodoc:
+      classes = @struct_classes
+      classes = SeregaUtils::RactorLocal.fetch(SeregaUtils::RactorLocal.key(self, :struct_classes)) { {} } if classes.frozen?
+      classes[point_names] ||= Struct.new(*point_names)
     end
 
     #
-    # Adds attribute
+    # Adds an attribute. By default its value is `object.<name>`, and the
+    # options change that:
     #
-    # @param name [Symbol] Attribute name. Attribute value will be found by executing `object.<name>`
-    # @param opts [Hash] Options to serialize attribute
-    # @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).
+    # ```ruby
+    # attribute :first_name
+    # attribute :name, method: :full_name
+    # attribute :email, hide: true
+    # attribute :posts, serializer: PostSerializer
+    # ```
     #
-    # @example
-    #   attribute :statistics, method: :itself do
-    #     attribute :likes_count
-    #     attribute :comments_count
-    #   end
+    # A block defines the attributes of a nested serializer. It inherits from
+    # the `:base_serializer` option or `config.base_serializer`:
+    #
+    # ```ruby
+    # attribute :statistics, method: :itself do
+    #   attribute :likes_count
+    #   attribute :comments_count
+    # end
+    # ```
     #
-    # @return [Serega::SeregaAttribute] Added attribute
+    # See [Attributes](https://github.com/andreyruby/serega/blob/master/docs/attributes.md#all-options)
+    # for all options.
     #
     def attribute(name, **opts, &block)
-      attribute = self::SeregaAttribute.new(name: name, opts: opts, block: block)
+      check_unlocked
+      location = caller_locations.find { |caller_location| !caller_location.path.start_with?(LIB_PATH) }
+      attribute = SeregaAttribute.new(self, name: name, opts: opts, block: block, location: location && "#{location.path}:#{location.lineno}")
       attributes[attribute.name] = attribute
     end
 
     #
-    # Defines a batch loader
+    # Defines a named batch loader: a callable or a block that receives the
+    # objects, and the context as a second parameter or as the `:ctx`
+    # keyword. It returns the values by object id. Subclasses inherit it.
     #
-    # @example
-    #   batch :tags, PostTagsLoader
+    # ```ruby
+    # batch :likes_count, ->(users) { Like.where(user: users).group(:user_id).count }
+    # batch(:rank) { |users, ctx:| Rank.for(users, ctx[:season]) }
     #
-    # @example with block
-    #   batch_loader(:tags) do |posts|
-    #     Tags.where(post: posts).group(:post_id).pluck(:post_id, Arel.sql('ARRAY_AGG(tags.tag ORDER BY tag)')).to_h
-    #   end
+    # attribute :likes_count, batch: true
+    # ```
     #
-    #   attribute :tags, batch: :tags, value: { |post, batch:| batch[:tags][post.id] }
+    # See [Batch loading](https://github.com/andreyruby/serega/blob/master/docs/batch-loading.md).
     #
-    # @example with context
-    #   batch_loader(:tags) do |posts, ctx:|
-    #     next {} if ctx[:bot]
+    def batch(name, value = nil, &block)
+      check_unlocked
+      raise SeregaError, "Batch loader must be defined with a callable value or block" if !value == !block
+
+      batch_loader = SeregaBatchLoader.new(name: name, block: value || block)
+      batch_loaders[batch_loader.name] = batch_loader
+    end
+
     #
-    #     Tags.where(post: posts).group(:post_id).pluck(:post_id, Arel.sql('ARRAY_AGG(tags.tag ORDER BY tag)')).to_h
-    #   end
+    # Defines a named formatter for the `:format` attribute option. A formatter
+    # is a method name called on the value, an Array of a method name and its
+    # arguments, or a callable or a block that receives the value, and the
+    # context as a second parameter or as the `:ctx` keyword. With
+    # `allow_nil: true` a `nil` value stays `nil`. Subclasses inherit it.
     #
-    #   attribute :tags, batch: :tags, value: { |post, batch:| batch[:tags][post.id] }
+    # ```ruby
+    # formatter :string, :to_s
+    # formatter :iso8601, [:iso8601, 3]
+    # formatter(:money) { |cents, ctx| "#{cents / 100.0} #{ctx[:currency]}" }
     #
-    # @param name [Symbol] A batch loader name
-    # @param value [#call] Batch loader
-    # @param block [Proc] Batch loader
+    # attribute :created_at, format: :iso8601
+    # ```
     #
-    # @return [#call] Batch loader
+    # See [Formatters](https://github.com/andreyruby/serega/blob/master/docs/formatters.md).
     #
-    def batch(name, value = nil, &block)
-      raise SeregaError, "Batch loader must be defined with a callable value or block" if (value && block) || (!value && !block)
+    def formatter(name, value = nil, allow_nil: false, &block)
+      check_unlocked
+      raise SeregaError, "Formatter name must be a Symbol" unless name.is_a?(Symbol)
+      raise SeregaError, "Formatter must be defined with a value or a block" if !value == !block
+      raise SeregaError, "Invalid option :allow_nil => #{allow_nil.inspect}. Must have a boolean value" unless allow_nil == true || allow_nil == false
 
-      batch_loader = self::SeregaEngineLoader.new(name: name, block: value || block)
-      batch_loaders[batch_loader.name] = batch_loader
+      value ||= block
+      SeregaValidations::CheckFormatter.call(name, value)
+      formatters[name] = SeregaFormatter.new({use: value, allow_nil: allow_nil})
     end
 
     #
-    # Defines presenter methods — evaluates the block inside the serializer's own
-    # presenter class. Multiple blocks accumulate.
+    # Defines presenter methods: attributes read their values from them. The
+    # block runs in the presenter class of the serializer, and each call adds
+    # methods. Returns the presenter class, `nil` without one.
     #
-    #   presenter do
-    #     def name
-    #       [first_name, last_name].compact.join(" ")
-    #     end
-    #   end
+    # ```ruby
+    # attribute :name
     #
-    # @param block [Proc] Presenter methods
+    # presenter do
+    #   def name
+    #     [first_name, last_name].compact.join(" ")
+    #   end
+    # end
+    # ```
     #
-    # @return [Class<SeregaPresenter>, nil] the serializer presenter class,
-    #   nil when the serializer has none
+    # See [Presenter](https://github.com/andreyruby/serega/blob/master/docs/presenter.md).
     #
     def presenter(&block)
       return @presenter_class unless block
 
+      check_unlocked
       @presenter_class ||= Class.new(SeregaPresenter)
       @presenter_class.class_exec(&block)
       presenter_blocks << block
@@ -267,31 +313,23 @@ class Serega
     end
 
     #
-    # Registers (or returns) the handler used to preload an attribute's
-    # associations onto the records gathered during serialization.
-    #
-    # The handler is called once per preloaded attribute with the gathered
-    # objects and that attribute's preloads. ORM plugins register a handler
-    # that performs the actual eager loading.
-    #
-    # @example with a block
-    #   preload_with { |objects, preloads| MyORM.eager_load(objects, preloads) }
-    #
-    # @example with a callable value
-    #   preload_with MyPreloader
+    # Sets the handler that preloads the `:preload` value of an attribute. It
+    # runs once per attribute with a preload, with the objects to serialize
+    # and the preloads. Without arguments, returns the handler. Subclasses
+    # inherit it.
     #
-    # @param value [#call, nil] Preload handler accepting two positional arguments
-    # @param block [Proc] Preload handler accepting two positional arguments
+    # ```ruby
+    # preload_with { |objects, preloads| RecordPreloader.call(objects, preloads) }
+    # preload_with AppPreloader
+    # ```
     #
-    # @return [#call, nil] The registered preload handler
+    # See [Preloads](https://github.com/andreyruby/serega/blob/master/docs/preloads.md).
     #
     def preload_with(value = nil, &block)
       return @preload_with if value.nil? && block.nil?
-      raise SeregaError, "preload_with accepts a single callable or a block, not both" if value && block
-
-      handler = value || block
-      raise SeregaError, "preload_with value must be a Proc or respond to #call" if !handler.is_a?(Proc) && !handler.respond_to?(:call)
 
+      check_unlocked
+      handler = checked_handler(:preload_with, value, block)
       signature = SeregaUtils::MethodSignature.call(handler, pos_limit: 2)
       raise SeregaError, "preload_with handler must accept two positional arguments: (objects, preloads)" unless signature == "2"
 
@@ -299,45 +337,25 @@ class Serega
     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
+    # Sets the handler that replaces the objects given to the serializer, for
+    # example ids with records. It runs once per serialization, before Serega
+    # detects a list, and receives the objects, and the context as a second
+    # parameter or as the `:ctx` keyword. Objects of relations skip it.
+    # Without arguments, returns the handler.
     #
-    # @param value [#call, nil] Handler accepting (objects), (objects, context) or (objects, ctx:)
-    # @param block [Proc] Handler accepting (objects), (objects, context) or (objects, ctx:)
+    # ```ruby
+    # prepare_initial_objects { |user_ids| User.where(id: user_ids) }
+    # prepare_initial_objects { |ids, ctx:| User.where(id: ids, account: ctx[:account]) }
+    # prepare_initial_objects UsersLoader
+    # ```
     #
-    # @return [#call, nil] The registered handler
+    # See [Prepare initial objects](https://github.com/andreyruby/serega/blob/master/docs/prepare-initial-objects.md).
     #
     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)
 
+      check_unlocked
+      handler = checked_handler(:prepare_initial_objects, value, block)
       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)
 
@@ -345,133 +363,176 @@ class Serega
       @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
+    attr_reader :prepare_initial_objects_signature # :nodoc:
+
+    # Patched in:
+    # - plugin :root (takes the options of plugins)
 
     #
-    # Serializes provided object to Hash
+    # Serializes an object or a list to a Hash or an Array of Hashes. `nil`
+    # serializes to `nil`.
+    #
+    # - `only`, `except`, `with`: fields to serialize, to skip and to add,
+    #   see [Selecting fields](https://github.com/andreyruby/serega/blob/master/docs/selecting-fields.md);
+    # - `check_initiate_params`: `false` skips unknown fields, by default
+    #   `config.check_initiate_params`;
+    # - `context`: data for attribute values and conditions;
+    # - `many`: `true` serializes a list, `false` one object. By default an
+    #   `Enumerable` that is not a `Hash` or `Struct` is a list.
     #
-    # @param object [Object] Serialized object
-    # @param opts [Hash, nil] Serializer modifiers and other instantiating options
-    # @option opts [Array, Hash, String, Symbol] :only The only attributes to serialize
-    # @option opts [Array, Hash, String, Symbol] :except Attributes to hide
-    # @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) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
+    # ```ruby
+    # UserSerializer.to_h(user)                     # => {first_name: "Bruce"}
+    # UserSerializer.to_h([user], with: :email)     # => [{first_name: "Bruce", email: "bruce@wayne.com"}]
+    # UserSerializer.to_h(user, context: {admin: true})
+    # ```
     #
-    # @return [Hash] Serialization result
+    # See [Serializing](https://github.com/andreyruby/serega/blob/master/docs/serializing.md).
     #
-    def call(object, opts = nil)
-      opts = opts&.transform_keys(&:to_sym)
-      modifiers_opts = init_modifier_opts(opts)
-      serialize_opts = init_serialize_opts(opts)
-      new(modifiers_opts).to_h(object, serialize_opts)
+    def call(object, only: nil, with: nil, except: nil, check_initiate_params: nil, context: nil, many: nil)
+      new(only: only, with: with, except: except, check_initiate_params: check_initiate_params)
+        .to_h(object, context: context, many: many)
     end
 
+    # Patched in:
+    # - plugin :root (takes the options of plugins)
+
     #
-    # Serializes provided object to a tree of Ruby Data objects
-    #
-    # @param object [Object] Serialized object
-    # @param opts [Hash, nil] Serializer modifiers and other instantiating options
-    # @option opts [Array, Hash, String, Symbol] :only The only attributes to serialize
-    # @option opts [Array, Hash, String, Symbol] :except Attributes to hide
-    # @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) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
+    # Serializes like #to_h, to `Data` objects
     #
-    # @return [Data, Array<Data>, nil] Serialization result as Data object(s)
+    # ```ruby
+    # UserSerializer.to_data(user) # => #<data first_name="Bruce">
+    # ```
     #
-    def to_data(object, opts = nil)
-      opts = opts&.transform_keys(&:to_sym)
-      modifiers_opts = init_modifier_opts(opts)
-      serialize_opts = init_serialize_opts(opts)
-      new(modifiers_opts).to_data(object, serialize_opts)
+    def to_data(object, only: nil, with: nil, except: nil, check_initiate_params: nil, context: nil, many: nil)
+      new(only: only, with: with, except: except, check_initiate_params: check_initiate_params)
+        .to_data(object, context: context, many: many)
     end
 
-    alias_method :to_h, :call
-
-    private
-
-    def init_modifier_opts(opts)
-      (!opts || opts.empty?) ? FROZEN_EMPTY_HASH : opts.slice(*config.initiate_keys)
-    end
+    # Patched in:
+    # - plugin :root (takes the options of plugins)
 
-    def init_serialize_opts(opts)
-      (!opts || opts.empty?) ? nil : opts.except(*config.initiate_keys)
+    #
+    # Serializes like #to_h, to `Struct` objects
+    #
+    # ```ruby
+    # UserSerializer.to_struct(user) # => #<struct first_name="Bruce">
+    # ```
+    #
+    def to_struct(object, only: nil, with: nil, except: nil, check_initiate_params: nil, context: nil, many: nil)
+      new(only: only, with: with, except: except, check_initiate_params: check_initiate_params)
+        .to_struct(object, context: context, many: many)
     end
 
     # Patched in:
-    # - plugin :metadata (defines MetaAttribute and copies meta_attributes to subclasses)
-    def inherited(subclass)
-      config_class = Class.new(self::SeregaConfig)
-      config_class.serializer_class = subclass
-      subclass.const_set(:SeregaConfig, config_class)
-      subclass.instance_variable_set(:@config, subclass::SeregaConfig.new(config.opts))
-
-      attribute_class = Class.new(self::SeregaAttribute)
-      attribute_class.serializer_class = subclass
-      subclass.const_set(:SeregaAttribute, attribute_class)
+    # - plugin :root (takes the options of plugins)
 
-      attribute_normalizer_class = Class.new(self::SeregaAttributeNormalizer)
-      attribute_normalizer_class.serializer_class = subclass
-      subclass.const_set(:SeregaAttributeNormalizer, attribute_normalizer_class)
+    #
+    # Serializes like #to_h, to a JSON String: `JSON.generate` of the #to_h
+    # result
+    #
+    # ```ruby
+    # UserSerializer.to_json(user) # => "{\"first_name\":\"Bruce\"}"
+    # ```
+    #
+    def to_json(object, only: nil, with: nil, except: nil, check_initiate_params: nil, context: nil, many: nil)
+      new(only: only, with: with, except: except, check_initiate_params: check_initiate_params)
+        .to_json(object, context: context, many: many)
+    end
 
-      data_builder_class = Class.new(self::SeregaDataBuilder)
-      data_builder_class.serializer_class = subclass
-      subclass.const_set(:SeregaDataBuilder, data_builder_class)
+    alias_method :to_h, :call
 
-      plan_class = Class.new(self::SeregaPlan)
-      plan_class.serializer_class = subclass
-      subclass.const_set(:SeregaPlan, plan_class)
+    # Locks serializer definitions and config from changes.
+    # Called when a serialization plan is built for the serializer.
+    def lock # :nodoc:
+      return if @locked
 
-      plan_point_class = Class.new(self::SeregaPlanPoint)
-      plan_point_class.serializer_class = subclass
-      subclass.const_set(:SeregaPlanPoint, plan_point_class)
+      LOCK_MUTEX.synchronize do
+        next if @locked
 
-      engine_loader_class = Class.new(self::SeregaEngineLoader)
-      engine_loader_class.serializer_class = subclass
-      subclass.const_set(:SeregaEngineLoader, engine_loader_class)
+        SeregaUtils::EnumDeepFreeze.call(config.opts)
+        define_presenter_delegators if @presenter_class
+        @locked = true
+      end
+    end
 
-      object_serializer_class = Class.new(self::SeregaObjectSerializer)
-      object_serializer_class.serializer_class = subclass
-      subclass.const_set(:SeregaObjectSerializer, object_serializer_class)
+    #
+    # Makes the serializer shareable between Ractors. Call it at the end of a
+    # definition to serialize in other Ractors. It locks the serializer and
+    # its nested serializers defined with blocks. A serializer with a
+    # definition that can not be shared serializes in the main Ractor only.
+    #
+    # ```ruby
+    # class UserSerializer < Serega
+    #   attribute :first_name
+    #
+    #   make_shareable!
+    # end
+    # ```
+    #
+    # See [Ractors](https://github.com/andreyruby/serega/blob/master/docs/ractors.md).
+    #
+    def make_shareable!
+      return self if @shareable
+
+      lock
+      attributes.each_value { |attribute| attribute.serializer.make_shareable! if attribute.initials[:block] }
+      @shareable = true
+      # :nocov:
+      if defined?(Ractor)
+        require_relative "serega/shareable"
+        require_relative "serega/plan/per_ractor_cache"
+        # Other Ractors can not define methods in the presenter, thus each
+        # Ractor wraps objects in its own subclass of it
+        if @presenter_class
+          @presenter_class::Delegators.freeze
+          @presenter_key = SeregaUtils::RactorLocal.key(self, :presenter)
+        end
+        @unshareable_reason = SeregaShareable.call(self)
+        @plan_cache = SeregaPlan::PerRactorCache.new(self) unless @unshareable_reason
+      end
+      # :nocov:
+      self
+    end
 
-      check_attribute_params_class = Class.new(self::CheckAttributeParams)
-      check_attribute_params_class.serializer_class = subclass
-      subclass.const_set(:CheckAttributeParams, check_attribute_params_class)
+    # Shows whether `make_shareable!` was called
+    def shareable? # :nodoc:
+      @shareable
+    end
 
-      check_initiate_params_class = Class.new(self::CheckInitiateParams)
-      check_initiate_params_class.serializer_class = subclass
-      subclass.const_set(:CheckInitiateParams, check_initiate_params_class)
+    private
 
-      check_serialize_params_class = Class.new(self::CheckSerializeParams)
-      check_serialize_params_class.serializer_class = subclass
-      subclass.const_set(:CheckSerializeParams, check_serialize_params_class)
+    # Defines the presenter delegators of the attributes that read a method of
+    # the object. Later reads skip method_missing, also in other Ractors,
+    # which can not define methods in classes of the main Ractor.
+    def define_presenter_delegators
+      object_methods = attributes.each_value.filter_map(&:object_method)
+      @presenter_class.define_delegators(object_methods)
+    end
 
-      check_batch_loader_params_class = Class.new(self::CheckBatchLoaderParams)
-      check_batch_loader_params_class.serializer_class = self
-      subclass.const_set(:CheckBatchLoaderParams, check_batch_loader_params_class)
+    def check_unlocked
+      raise SeregaError, "#{self} can not be changed after it was made shareable" if @shareable
+      raise SeregaError, "#{self} can not be changed after it was used for serialization" if @locked
+    end
 
-      # Assign same attributes
-      attributes.each_value do |attr|
-        params = attr.initials
-        subclass.attribute(params[:name], **params[:opts], &params[:block])
-      end
+    # Patched in:
+    # - plugin :metadata (copies meta_attributes to subclasses)
+    def inherited(subclass)
+      subclass.const_set(:SeregaConfig, Class.new(self::SeregaConfig))
+      subclass.const_set(:SeregaAttributeValues, Class.new(self::SeregaAttributeValues))
+      subclass.send(:initialize_definition, subclass::SeregaConfig.new(config.opts), formatters.dup)
 
-      # Assign same batch loaders
+      # Assign same batch loaders before the attributes that use them
       batch_loaders.each_value do |loader|
         subclass.batch(loader.name, loader.block)
       end
 
+      # Assign same attributes
+      attributes.each_value do |attr|
+        subclass_attribute = SeregaAttribute.new(subclass, **attr.initials)
+        subclass.attributes[subclass_attribute.name] = subclass_attribute
+      end
+
       # Assign same preload handler
       subclass.preload_with(preload_with) if preload_with
 
@@ -486,6 +547,38 @@ class Serega
       super
     end
 
+    # Starts the definition of a serializer class with its config and the
+    # formatters it inherits. Serega and each subclass set the same instance
+    # variables in the same order.
+    def initialize_definition(config, formatters)
+      @config = config
+      @attributes = {}
+      @batch_loaders = {}
+      @formatters = formatters
+      @presenter_class = nil
+      @presenter_blocks = []
+      @presenter_key = nil
+      @data_classes = {}
+      @struct_classes = {}
+      @preload_with = nil
+      @prepare_initial_objects = nil
+      @prepare_initial_objects_signature = nil
+      @locked = false
+      @shareable = false
+      @unshareable_reason = nil
+      @plan_cache = SeregaPlan::Cache.new(self)
+    end
+
+    # The handler given to `method_name` as a value or a block
+    def checked_handler(method_name, value, block)
+      raise SeregaError, "#{method_name} accepts a single callable or a block, not both" if value && block
+
+      handler = value || block
+      raise SeregaError, "#{method_name} value must be a Proc or respond to #call" unless handler.respond_to?(:call)
+
+      handler
+    end
+
     def prepare_initial_objects_signature_error
       <<~ERR.strip
         prepare_initial_objects handler arguments should have one of this signatures:
@@ -497,118 +590,103 @@ class Serega
   end
 
   #
-  # Serializers instance methods
+  # Instance methods of serializers. An instance keeps its field selection
+  # and serializes many times.
   #
   module InstanceMethods
     #
-    # Instantiates new Serega class
-    #
-    # @param opts [Hash, nil] Serializer modifiers and other instantiating options
-    # @option opts [Array, Hash, String, Symbol] :only The only attributes to serialize
-    # @option opts [Array, Hash, String, Symbol] :except Attributes to hide
-    # @option opts [Array, Hash, String, Symbol] :with Attributes (usually hidden) to serialize additionally
-    # @option opts [Boolean] :validate Validates provided modifiers (Default is true)
-    #
-    def initialize(opts = nil)
-      @opts =
-        if opts.nil? || opts.empty?
-          FROZEN_EMPTY_HASH
-        else
-          opts.transform_keys!(&:to_sym)
-          parse_modifiers(opts)
-        end
-
-      self.class::CheckInitiateParams.new(@opts).validate if opts&.fetch(:check_initiate_params) { config.check_initiate_params }
-
-      @plan = self.class::SeregaPlan.call(@opts)
+    # Prepares a serializer with a field selection. The options are the field
+    # options of Serega::ClassMethods#to_h.
+    #
+    # ```ruby
+    # serializer = UserSerializer.new(only: [:first_name])
+    # serializer.to_h(user)  # => {first_name: "Bruce"}
+    # serializer.to_h(users) # => [{first_name: "Bruce"}, {first_name: "Alfred"}]
+    # ```
+    #
+    def initialize(only: nil, with: nil, except: nil, check_initiate_params: nil)
+      modifiers = !(only.nil? && with.nil? && except.nil?)
+      check_initiate_params = config.check_initiate_params if modifiers && check_initiate_params.nil?
+      @plan = self.class.plan_cache.fetch(only, with, except, check_initiate_params: modifiers && check_initiate_params)
+      @direct_hash_builder = @plan.direct_hash_builder
     end
 
-    #
     # Plan for serialization.
     # This plan can be traversed to find serialized attributes and nested attributes.
-    #
-    # @return [Serega::SeregaPlan] Serialization plan
-    # @private
-    attr_reader :plan
+    attr_reader :plan # :nodoc:
+
+    # Patched in:
+    # - plugin :root (takes the options of plugins)
 
     #
-    # Serializes provided object to Hash
-    #
-    # @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) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
+    # Serializes an object or a list to a Hash or an Array of Hashes, with the
+    # serialization options of Serega::ClassMethods#to_h
     #
-    # @return [Hash] Serialization result
+    # ```ruby
+    # UserSerializer.new.to_h(user, context: {admin: true})
+    # ```
     #
-    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
+    def call(object, context: nil, many: nil)
+      builder = @direct_hash_builder
+      if builder && object && !many && (context.nil? || context.is_a?(Hash))
+        many = SeregaUtils::CollectionDetector.call(object, @plan.collection_classes) if many.nil?
+        return builder.call_one(object, context.nil? ? FROZEN_EMPTY_HASH : context) unless many
+      end
 
-    # @see #call
-    def to_h(object, opts = nil)
-      call(object, opts)
+      serialize_to(:hash, object, context, many, FROZEN_EMPTY_HASH)
     end
 
-    #
-    # Serializes provided object to Data objects
+    alias_method :to_h, :call
+
     # Patched in:
-    # - plugin :root (adds a data-object for a root level keys)
-    #
-    # @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) && !object.is_a?(Hash) && !object.is_a?(Struct)`)
+    # - plugin :root (takes the options of plugins)
+
     #
-    # @return [Data] Serialization result
+    # Serializes like #to_h, to `Data` objects
     #
-    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)
+    def to_data(object, context: nil, many: nil)
+      serialize_to(:data, object, context, many, FROZEN_EMPTY_HASH)
     end
 
-    private
-
-    attr_reader :opts
+    # Patched in:
+    # - plugin :root (takes the options of plugins)
 
-    def config
-      self.class.config
+    #
+    # Serializes like #to_h, to `Struct` objects
+    #
+    def to_struct(object, context: nil, many: nil)
+      serialize_to(:struct, object, context, many, FROZEN_EMPTY_HASH)
     end
 
-    def parse_modifiers(opts)
-      result = {}
-
-      opts.each do |key, value|
-        value = parse_modifier(value) if (key == :only) || (key == :except) || (key == :with)
-        result[key] = value
-      end
+    # Patched in:
+    # - plugin :root (takes the options of plugins)
 
-      result
+    #
+    # Serializes like #to_h, to a JSON String: `JSON.generate` of the #to_h
+    # result
+    #
+    def to_json(object, context: nil, many: nil)
+      JSON.generate(call(object, context: context, many: many))
     end
 
-    # Patched in:
-    # - plugin :string_modifiers (parses string modifiers differently)
-    def parse_modifier(value)
-      SeregaUtils::ToHash.call(value)
-    end
+    private
 
-    def normalize_serialization_opts(opts)
-      opts = opts ? opts.transform_keys(&:to_sym) : {}
-      self.class::CheckSerializeParams.new(opts).validate unless opts.empty?
+    def config
+      self.class.config
+    end
 
-      opts[:context] ||= {}
-      opts
+    # Serializes the object with the serialization options. `opts` holds the
+    # options other than :context and :many.
+    def serialize_to(mode, object, context, many, opts)
+      SeregaValidations::CheckSerializeKeywords.call(context, many)
+      context ||= FROZEN_EMPTY_HASH
+      object = prepare_objects(object, context) if self.class.prepare_initial_objects_signature
+      many = SeregaUtils::CollectionDetector.call(object, @plan.collection_classes) if many.nil?
+      serialize(object, opts, context, many, mode)
     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)
@@ -617,24 +695,17 @@ class Serega
       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
-      opts
-    end
-
     # Patched in:
     # - plugin :root (wraps result `{ root => result }`)
     # - plugin :context_metadata (adds context metadata to final result)
     # - plugin :metadata (adds metadata to final result)
-    def serialize(object, opts)
-      result = self.class::SeregaObjectSerializer.new(**opts).serialize(object)
-      opts[:level_queue].run
-      result
+    def serialize(object, _opts, context, many, mode)
+      SeregaEngine::Run.call(@plan, object, many, mode, context)
     end
   end
 
   extend ClassMethods
   include InstanceMethods
+
+  initialize_definition(SeregaConfig.new, {})
 end