serega 0.40.0 → 0.40.1

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
           #

data/lib/serega/plugins/if/if.rb

@@ -3,46 +3,34 @@
 class Serega
   module SeregaPlugins
     #
-    # Plugin adds `:if`, `:unless`, `:if_value`, `:unless_value` options to
-    # attributes so we can remove attributes from response in various ways.
+    # Plugin :if
     #
-    # Use `:if` and `:unless` when you want to hide attributes before finding attribute value,
-    # and use `:if_value` and `:unless_value` to hide attributes after we find final value.
+    # Adds `:if`, `:unless`, `:if_value`, `:unless_value` attribute options to
+    # conditionally remove attributes from the response.
     #
-    # Options `:if` and `:unless` accept currently serialized object and context as parameters.
-    # Options `:if_value` and `:unless_value` accept already found serialized value and context as parameters.
+    # `:if`/`:unless` receive the serialized object and context, and are
+    # checked before the attribute value is found. `:if_value`/`:unless_value`
+    # receive the already-found value and context, checked after. The latter
+    # two cannot be used with the `:serializer` option, since a relationship
+    # has no "serialized value" of its own — use `:if`/`:unless` instead.
     #
-    # Options `:if_value` and `:unless_value` cannot be used with :serializer option, as
-    # serialized objects have no "serialized value". Use `:if` and `:unless` in this case.
+    # See also the plugin-free `:hide` option (README.md#selecting-fields),
+    # which hides an attribute unconditionally.
     #
-    # See also a `:hide` option that is available without any plugins to hide
-    # attribute without conditions. Look at README.md#selecting-fields for `:hide` usage examples.
+    # @example
+    #   class UserSerializer < Serega
+    #     attribute :email, if: :active? # if user.active?
+    #     attribute :email, if: proc { |user, ctx| user == ctx[:current_user] } # using context
+    #     attribute :email, if: CustomPolicy.method(:view_email?) # any callable
     #
-    # Examples:
-    #  class UserSerializer < Serega
-    #    attribute :email, if: :active? # if user.active?
-    #    attribute :email, if: proc {|user| user.active?} # same
-    #    attribute :email, if: proc {|user, ctx| user == ctx[:current_user]} # using context
-    #    attribute :email, if: CustomPolicy.method(:view_email?) # You can provide own callable object
-    #
-    #    attribute :email, unless: :hidden? # unless user.hidden?
-    #    attribute :email, unless: proc {|user| user.hidden?} # same
-    #    attribute :email, unless: proc {|user, context| context[:show_emails]} # using context
-    #    attribute :email, unless: CustomPolicy.method(:hide_email?) # You can provide own callable object
-    #
-    #    attribute :email, if_value: :present? # if email.present?
-    #    attribute :email, if_value: proc {|email| email.present?} # same
-    #    attribute :email, if_value: proc {|email, ctx| ctx[:show_emails]} # using context
-    #    attribute :email, if_value: CustomPolicy.method(:view_email?) # You can provide own callable object
-    #
-    #    attribute :email, unless_value: :blank? # unless email.blank?
-    #    attribute :email, unless_value: proc {|email| email.blank?} # same
-    #    attribute :email, unless_value: proc {|email, context| context[:show_emails]} # using context
-    #    attribute :email, unless_value: CustomPolicy.method(:hide_email?) # You can provide own callable object
-    #  end
+    #     attribute :email, unless: :hidden? # unless user.hidden?
+    #     attribute :email, if_value: :present? # if email.present?
+    #     attribute :email, unless_value: :blank? # unless email.blank?
+    #   end
     #
     module If
       # @return [Symbol] Plugin name
+      # @private
       def self.plugin_name
         :if
       end
@@ -55,6 +43,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         require_relative "validations/check_opt_if"
         require_relative "validations/check_opt_if_value"
@@ -77,6 +66,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.after_load_plugin(serializer_class, **opts)
         serializer_class.config.attribute_keys << :if << :if_value << :unless << :unless_value
       end
@@ -86,6 +76,7 @@ class Serega
       #
       # @see SeregaAttributeNormalizer::AttributeInstanceMethods
       #
+      # @private
       module AttributeNormalizerInstanceMethods
         #
         # Returns prepared attribute :if_options.
@@ -135,6 +126,7 @@ class Serega
       #
       # Resolves keyword-based conditions for if/unless options
       #
+      # @private
       class KeywordConditionResolver
         def initialize(keyword)
           @keyword = keyword
@@ -156,6 +148,7 @@ class Serega
       #
       # @see Serega::SeregaAttribute
       #
+      # @private
       module AttributeInstanceMethods
         # @return [Hash] provided :if options
         attr_reader :opt_if
@@ -177,6 +170,7 @@ class Serega
       #
       # @see Serega::SeregaPlanPoint::InstanceMethods
       #
+      # @private
       module PlanPointInstanceMethods
         #
         # @return [Boolean] Should we show attribute or not
@@ -225,6 +219,7 @@ class Serega
       #
       # @see Serega::SeregaValidations::CheckAttributeParams
       #
+      # @private
       module CheckAttributeParamsInstanceMethods
         private
 
@@ -247,6 +242,7 @@ class Serega
       #
       # @see Serega::SeregaDataBuilder
       #
+      # @private
       module DataBuilderClassMethods
         private
 
@@ -264,6 +260,7 @@ class Serega
       #
       # @see Serega::SeregaObjectSerializer
       #
+      # @private
       module ObjectSerializerInstanceMethods
         private
 

data/lib/serega/plugins/if/validations/check_opt_if.rb

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

data/lib/serega/plugins/if/validations/check_opt_if_value.rb

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