serega 0.40.0 → 0.41.0

data/lib/serega/data_builder.rb

@@ -5,8 +5,10 @@ class Serega
   # Builds Data objects from serialized hashes.
   # Used by `#to_data` / `.to_data`.
   #
+  # @private
   class SeregaDataBuilder
     # SeregaDataBuilder class methods
+    # @private
     module SeregaDataBuilderClassMethods
       #
       # Converts serialized Hash/Array result into a tree of Ruby Data objects

data/lib/serega/engine/level.rb

@@ -4,6 +4,7 @@ class Serega
   #
   # Batch feature main module
   #
+  # @private
   module SeregaEngine
     #
     # One serialization level: all objects serialized under a single plan and the
@@ -12,6 +13,7 @@ class Serega
     # or preload runs once over the whole set. A deeper level (its own plan) loads
     # separately.
     #
+    # @private
     class Level
       # @param serializer [SeregaObjectSerializer] serializer that resolves this level
       def initialize(serializer)

data/lib/serega/engine/level_queue.rb

@@ -4,6 +4,7 @@ class Serega
   #
   # Batch feature main module
   #
+  # @private
   module SeregaEngine
     #
     # Level-order queue of serialization levels for one serialization run.
@@ -15,6 +16,7 @@ class Serega
     # Processing level-by-level lets a named batch loader and preloads run once per
     # level over all of its objects.
     #
+    # @private
     class LevelQueue
       def initialize
         @levels = []

data/lib/serega/engine/loader.rb

@@ -4,14 +4,17 @@ class Serega
   #
   # Batch feature main module
   #
+  # @private
   module SeregaEngine
     #
     #  Batch loader
     #
+    # @private
     class Loader
       #
       # BatchLoader instance methods
       #
+      # @private
       module InstanceMethods
         # BatchLoader initial params
         # @return [Hash] BatchLoader initial params

data/lib/serega/helpers/serializer_class_helper.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Helpers
   #
+  # @private
   module SeregaHelpers
     #
     # Stores link to current serializer class
     #
+    # @private
     module SerializerClassHelper
       # Shows serializer class current class is namespaced under
       # @return [Class<Serega>] Serializer class that current class is namespaced under.

data/lib/serega/object_serializer.rb

@@ -9,10 +9,12 @@ class Serega
   # which resolves every attribute for every object and enqueues child levels for
   # relations.
   #
+  # @private
   class SeregaObjectSerializer
     #
     # SeregaObjectSerializer instance methods
     #
+    # @private
     module InstanceMethods
       attr_reader :context, :plan, :many, :opts, :level_queue
 

data/lib/serega/plan.rb

@@ -5,10 +5,12 @@ class Serega
   # Constructs plan - list of serialized attributes.
   # We will traverse this plan to construct serialized response.
   #
+  # @private
   class SeregaPlan
     #
     # SeregaPlan class methods
     #
+    # @private
     module ClassMethods
       #
       # Constructs plan of attributes that should be serialized.
@@ -68,6 +70,7 @@ class Serega
     #
     # SeregaPlan instance methods
     #
+    # @private
     module InstanceMethods
       # Parent plan point
       # @return [SeregaPlanPoint, nil]

data/lib/serega/plan_point.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Combines attribute and nested attributes
   #
+  # @private
   class SeregaPlanPoint
     #
     # SeregaPlanPoint instance methods
     #
+    # @private
     module InstanceMethods
       # Link to current plan this point belongs to
       # @return [SeregaAttribute] Current plan

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

@@ -12,38 +12,40 @@ class Serega
     #
     # @example
     #   class AppSerializer < Serega
-    #     config.auto_preload_attributes_with_delegate = true
-    #     config.auto_preload_attributes_with_serializer = true
-    #     config.hide_by_default = [:preload]
-    #
+    #     config.auto_preload = true
     #     plugin :activerecord_preloads
     #   end
     #
-    #   class UserSerializer < AppSerializer
+    #   class AlbumSerializer < AppSerializer
     #     # no preloads
-    #     attribute :username
-    #
-    #     # preloads `:user_stats` as auto_preload_attributes_with_delegate option is true
-    #     attribute :comments_count, delegate: { to: :user_stats }
+    #     attribute :title
     #
-    #     # preloads `:albums` as auto_preload_attributes_with_serializer option is true
-    #     attribute :albums, serializer: AlbumSerializer, hide: false
+    #     # preloads :downloads, as manually specified
+    #     attribute :downloads_count, preload: :downloads, value: proc { |album| album.downloads.count }
     #   end
     #
-    #   class AlbumSerializer < AppSerializer
+    #   class UserSerializer < AppSerializer
     #     # no preloads
-    #     attribute :title
+    #     attribute :username
     #
-    #     # preloads :downloads_count as manually specified
-    #     attribute :downloads_count, preload: :downloads, value: proc { |album| album.downloads.count }
+    #     # preloads :user_stats, as auto_preload is enabled for :delegate attributes
+    #     attribute :comments_count, delegate: { to: :user_stats }
+    #
+    #     # preloads :albums, as auto_preload is enabled for :serializer attributes
+    #     attribute :albums, serializer: AlbumSerializer
     #   end
     #
-    #   UserSerializer.to_h(user)
+    #   UserSerializer.to_h(users)
+    #   # 1 query to load :user_stats for all users
+    #   # + 1 query to load :albums for all users
+    #   # + 1 query to load :downloads for all albums
+    #   # = 3 queries total, regardless of how many users/albums are serialized
     #
     module ActiverecordPreloads
       #
       # @return [Symbol] Plugin name
       #
+      # @private
       def self.plugin_name
         :activerecord_preloads
       end
@@ -55,6 +57,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.before_load_plugin(serializer_class, **opts)
         opts.each_key do |key|
           raise SeregaError, "Plugin #{plugin_name.inspect} does not accept the #{key.inspect} option. No options are allowed"
@@ -69,6 +72,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         require_relative "lib/preloader"
       end
@@ -81,6 +85,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.after_load_plugin(serializer_class, **_opts)
         serializer_class.preload_with do |objects, preloads|
           Preloader.preload(ActiverecordPreloads.records(serializer_class, objects), preloads)
@@ -98,6 +103,7 @@ class Serega
       #
       # @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?

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

@@ -4,6 +4,7 @@ class Serega
   module SeregaPlugins
     module ActiverecordPreloads
       # Handles preloads for different types of initial records
+      # @private
       class Preloader
         class << self
           # Preloads associations to records
@@ -37,6 +38,7 @@ class Serega
       end
 
       # Associations loader for prepared records
+      # @private
       class Loader
         # :nocov: We can check only one version of activerecord
 
@@ -58,6 +60,7 @@ class Serega
       end
 
       # Preloader adapter for ActiveRecord object
+      # @private
       class ActiverecordObject
         class << self
           #
@@ -84,6 +87,7 @@ class Serega
       end
 
       # Preloader adapter for ActiveRecord::Relation
+      # @private
       class ActiverecordRelation
         class << self
           #
@@ -111,6 +115,7 @@ class Serega
       end
 
       # Preloader adapter for Array of ActiveRecord objects
+      # @private
       class ActiverecordArray
         class << self
           #
@@ -146,6 +151,7 @@ class Serega
       end
 
       # Preloader adapter for Enumerator with ActiveRecord objects
+      # @private
       class ActiverecordEnumerator
         class << self
           #

data/lib/serega/plugins/camel_case/camel_case.rb

@@ -5,21 +5,14 @@ class Serega
     #
     # Plugin :camel_case
     #
-    # By default when we add attribute like `attribute :first_name` this means:
-    # - adding a `:first_name` key to resulted hash
-    # - adding a `#first_name` method call result as value
+    # CamelCases every attribute name automatically, replacing `_x` with `X`
+    # throughout the string. Runs once, when the attribute is defined, not on
+    # every serialization.
     #
-    # But its often desired to response with *camelCased* keys.
-    # Earlier this can be achieved by specifying attribute name and method directly
-    # for each attribute: `attribute :firstName, method: first_name`
+    # Provide a custom transformation with
+    # `plugin :camel_case, transform: ->(name) { name.camelize }`.
     #
-    # Now this plugin transforms all attribute names automatically.
-    # We use simple regular expression to replace `_x` to `X` for the whole string.
-    # You can provide your own callable transformation when defining plugin,
-    # for example `plugin :camel_case, transform: ->(name) { name.camelize }`
-    #
-    # For any attribute camelCase-behavior can be skipped when
-    # `camel_case: false` attribute option provided.
+    # Skip camelCase for a single attribute with `camel_case: false`.
     #
     # @example Define plugin
     #  class AppSerializer < Serega
@@ -44,6 +37,7 @@ class Serega
       }
 
       # @return [Symbol] Plugin name
+      # @private
       def self.plugin_name
         :camel_case
       end
@@ -55,6 +49,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.before_load_plugin(serializer_class, **opts)
         allowed_keys = %i[transform]
         opts.each_key do |key|
@@ -74,6 +69,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
         serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
@@ -88,6 +84,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.after_load_plugin(serializer_class, **opts)
         config = serializer_class.config
         config.opts[:camel_case] = {}
@@ -113,6 +110,7 @@ class Serega
       #
       # @see Serega::SeregaValidations::CheckAttributeParams
       #
+      # @private
       module CheckAttributeParamsInstanceMethods
         private
 
@@ -125,6 +123,7 @@ class Serega
       #
       # Validator for attribute :camel_case option
       #
+      # @private
       class CheckOptCamelCase
         class << self
           #
@@ -191,6 +190,7 @@ class Serega
       #
       # @see SeregaAttributeNormalizer::AttributeInstanceMethods
       #
+      # @private
       module AttributeNormalizerInstanceMethods
         private
 

data/lib/serega/plugins/context_metadata/context_metadata.rb

@@ -7,7 +7,8 @@ class Serega
     #
     # Depends on: `:root` plugin, that must be loaded first
     #
-    # Allows to specify metadata to be added to serialized response.
+    # Adds metadata supplied per serialization call (as opposed to `:metadata`,
+    # which is defined statically on the serializer).
     #
     # @example
     #   class UserSerializer < Serega
@@ -23,6 +24,7 @@ class Serega
       DEFAULT_CONTEXT_METADATA_KEY = :meta
 
       # @return [Symbol] Plugin name
+      # @private
       def self.plugin_name
         :context_metadata
       end
@@ -34,6 +36,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.before_load_plugin(serializer_class, **opts)
         allowed_keys = %i[context_metadata_key]
         opts.each_key do |key|
@@ -57,6 +60,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         serializer_class.include(InstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
@@ -71,6 +75,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.after_load_plugin(serializer_class, **opts)
         config = serializer_class.config
         meta_key = opts[:context_metadata_key] || DEFAULT_CONTEXT_METADATA_KEY
@@ -127,6 +132,7 @@ class Serega
       #
       # @see Serega::SeregaValidations::CheckSerializeParams
       #
+      # @private
       module CheckSerializeParamsInstanceMethods
         private
 
@@ -143,6 +149,7 @@ class Serega
       #
       # @see Serega
       #
+      # @private
       module InstanceMethods
         private
 

data/lib/serega/plugins/depth_limit/depth_limit.rb

@@ -5,25 +5,23 @@ class Serega
     #
     # Plugin :depth_limit
     #
-    # Helps to secure from malicious queries that require to serialize too much
-    # or from accidental serializing of objects with cyclic relations.
+    # Guards against malicious queries that serialize too much, or against
+    # accidentally serializing objects with cyclic relations.
     #
-    # Depth limit is checked when constructing a serialization plan, that is when
-    # `#new` method is called, ex: `SomeSerializer.new(with: params[:with])`.
-    # It can be useful to instantiate serializer before any other business logic
-    # to get possible errors earlier.
+    # Depth limit is checked when a serialization plan is built, i.e. when
+    # `#new` is called (`SomeSerializer.new(with: params[:with])`) — including
+    # internally by every class-level serialization method. Instantiating the
+    # serializer early surfaces depth errors sooner.
     #
-    # Any class-level serialization methods also check depth limit as they also instantiate serializer.
+    # When the limit is exceeded, `Serega::DepthLimitError` is raised;
+    # details are available via `Serega::DepthLimitError#details`.
     #
-    # When depth limit is exceeded `Serega::DepthLimitError` is raised.
-    # Depth limit error details can be found in additional `Serega::DepthLimitError#details` method
-    #
-    # Limit can be checked or changed with next config options:
+    # Limit can be checked or changed with config options:
     #
     #   - config.depth_limit.limit
     #   - config.depth_limit.limit=
     #
-    # There are no default limit, but it should be set when enabling plugin.
+    # There is no default limit — it must be set when enabling the plugin.
     #
     # @example
     #
@@ -37,6 +35,7 @@ class Serega
     #
     module DepthLimit
       # @return [Symbol] Plugin name
+      # @private
       def self.plugin_name
         :depth_limit
       end
@@ -48,6 +47,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.before_load_plugin(serializer_class, **opts)
         allowed_keys = %i[limit]
         opts.each_key do |key|
@@ -67,6 +67,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         serializer_class::SeregaPlan.include(PlanInstanceMethods)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
@@ -80,6 +81,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.after_load_plugin(serializer_class, **opts)
         config = serializer_class.config
         limit = opts.fetch(:limit) { raise SeregaError, "Please provide :limit option. Example: `plugin :depth_limit, limit: 10`" }
@@ -137,6 +139,7 @@ class Serega
       #
       # @see SeregaPlan
       #
+      # @private
       module PlanInstanceMethods
         #
         # Initializes serialization plan

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

@@ -5,29 +5,29 @@ class Serega
     #
     # Plugin :explicit_many_option
     #
-    # Plugin requires to add :many option when adding relationships
-    # (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
+    # Requires the `:many` option on every relationship attribute (an
+    # attribute with the `:serializer` option or a block defining a nested
+    # serializer), so it's always explicit whether it returns one object or many.
     #
     # @example
     #   class BaseSerializer < Serega
     #     plugin :explicit_many_option
-    #   end
-    #
-    #   class UserSerializer < BaseSerializer
-    #     attribute :name
+    #     config.base_serializer = self
     #   end
     #
     #   class PostSerializer < BaseSerializer
     #     attribute :text
-    #     attribute :user, serializer: UserSerializer, many: false
+    #
+    #     attribute :user, many: false do
+    #       attribute :name
+    #     end
+    #
     #     attribute :comments, serializer: PostSerializer, many: true
     #   end
     #
     module ExplicitManyOption
       # @return [Symbol] Plugin name
+      # @private
       def self.plugin_name
         :explicit_many_option
       end
@@ -40,6 +40,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         require_relative "validations/check_opt_many"
 
@@ -51,6 +52,7 @@ class Serega
       #
       # @see Serega::SeregaValidations::CheckAttributeParams
       #
+      # @private
       module CheckAttributeParamsInstanceMethods
         private
 

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

@@ -6,6 +6,7 @@ class Serega
       #
       # Validator for attribute :many option
       #
+      # @private
       class CheckOptMany
         class << self
           #

data/lib/serega/plugins/formatters/formatters.rb

@@ -5,20 +5,19 @@ class Serega
     #
     # Plugin :formatters
     #
-    # Allows to define value formatters one time and apply them on any attributes.
+    # Defines named value formatters once and applies them to any attribute.
     #
-    # Config option `config.formatters.add()` can be used to add formatters.
+    # Use `config.formatters.add()` to register formatters. The `:format`
+    # attribute option then accepts a formatter name or a callable directly.
     #
-    # Attribute option `:format` now can be used with name of formatter or with callable instance.
-    #
-    # Formatters can accept up to 2 parameters (formatted object, context)
+    # Formatters receive up to 2 parameters: the value and the context.
     #
     # @example
     #   class AppSerializer < Serega
     #     plugin :formatters, formatters: {
-    #       iso8601: ->(value) { time.iso8601.round(6) },
+    #       iso8601: ->(value) { value.iso8601 },
     #       on_off: ->(value) { value ? 'ON' : 'OFF' },
-    #       money: ->(value) { value.round(2) }
+    #       money: ->(value) { value.round(2) },
     #       date: DateTypeFormatter # callable
     #     }
     #   end
@@ -26,24 +25,25 @@ class Serega
     #   class UserSerializer < Serega
     #     # Additionally we can add formatters via config in subclasses
     #     config.formatters.add(
-    #       iso8601: ->(value) { time.iso8601.round(6) },
+    #       iso8601: ->(value) { value.iso8601 },
     #       on_off: ->(value) { value ? 'ON' : 'OFF' },
     #       money: ->(value) { value.round(2) }
     #     )
     #
     #     # Using predefined formatter
     #     attribute :commission, format: :money
-    #     attribute :is_logined, format: :on_off
+    #     attribute :is_logged_in, format: :on_off
     #     attribute :created_at, format: :iso8601
     #     attribute :updated_at, format: :iso8601
     #
     #     # Using `callable` formatter
-    #     attribute :score_percent, format: PercentFormmatter # callable class
+    #     attribute :score_percent, format: PercentFormatter # callable class
     #     attribute :score_percent, format: proc { |percent| "#{percent.round(2)}%" }
     #   end
     #
     module Formatters
       # @return [Symbol] Plugin name
+      # @private
       def self.plugin_name
         :formatters
       end
@@ -55,6 +55,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.before_load_plugin(serializer_class, **opts)
         allowed_keys = %i[formatters]
         opts.each_key do |key|
@@ -74,6 +75,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         serializer_class::SeregaConfig.include(ConfigInstanceMethods)
         serializer_class::SeregaAttributeNormalizer.include(AttributeNormalizerInstanceMethods)
@@ -89,6 +91,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.after_load_plugin(serializer_class, **opts)
         config = serializer_class.config
         config.opts[:formatters] = {}
@@ -141,6 +144,7 @@ class Serega
       #
       # @see Serega::SeregaValidations::CheckAttributeParams
       #
+      # @private
       module CheckAttributeParamsInstanceMethods
         private
 
@@ -156,6 +160,7 @@ class Serega
       #
       # @see SeregaAttributeNormalizer
       #
+      # @private
       module AttributeNormalizerInstanceMethods
         # Block or callable instance that will format attribute values
         # @return [Proc, #call, nil] Block or callable instance that will format attribute values
@@ -194,6 +199,7 @@ class Serega
       #
       # @see SeregaAttribute
       #
+      # @private
       module AttributeInstanceMethods
         #
         # Returns formatted attribute value
@@ -229,6 +235,7 @@ class Serega
       #
       # Validator for attribute :format option
       #
+      # @private
       class CheckOptFormat
         class << self
           #
@@ -265,6 +272,7 @@ class Serega
       #
       # Validator for formatters defined as config options or directly as attribute :format option
       #
+      # @private
       class CheckFormatter
         class << self
           #