serega 0.40.0 → 0.41.0

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
           #

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

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

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

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

data/lib/serega/plugins/metadata/meta_attribute.rb

@@ -6,10 +6,12 @@ class Serega
       #
       # Stores Attribute data
       #
+      # @private
       class MetaAttribute
         #
         # Stores Attribute instance methods
         #
+        # @private
         module InstanceMethods
           # @return [Symbol] Meta attribute name
           attr_reader :name

data/lib/serega/plugins/metadata/metadata.rb

@@ -3,23 +3,20 @@
 class Serega
   module SeregaPlugins
     #
-    # Plugin `:metadata`
+    # Plugin :metadata
     #
     # Depends on: `:root` plugin, that must be loaded first
     #
-    # Adds ability to describe metadata that must be added to serialized response
+    # Adds metadata to the serialized response via the class-level
+    # `meta_attribute` method, which accepts:
     #
-    # Added class-level method `:meta_attribute`, to define metadata, it accepts:
-    #
-    # - `*path` [Array of Symbols] - nested hash keys.
+    # - `*path` [Array<Symbol>] - nested hash keys
     # - `**options` [Hash]
-    #
-    #   - `:const` - describes metadata value (if it is constant)
-    #   - `:value` - describes metadata value as any `#callable` instance
-    #   - `:hide_nil` - does not show metadata key if value is nil, `false` by default
-    #   - `:hide_empty`, does not show metadata key if value is nil or empty, `false` by default
-    #
-    # - `&block` [Proc] - describes value for current meta attribute
+    #   - `:const` - a constant metadata value
+    #   - `:value` - a `#callable` producing the metadata value
+    #   - `:hide_nil` - hide the key if the value is nil (`false` by default)
+    #   - `:hide_empty` - hide the key if the value is nil or empty (`false` by default)
+    # - `&block` - computes the value for this meta attribute
     #
     # @example
     #  class AppSerializer < Serega
@@ -39,6 +36,7 @@ class Serega
     #
     module Metadata
       # @return [Symbol] Plugin name
+      # @private
       def self.plugin_name
         :metadata
       end
@@ -50,6 +48,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.before_load_plugin(serializer_class, **_opts)
         unless serializer_class.plugin_used?(:root)
           raise SeregaError, "Plugin #{plugin_name.inspect} must be loaded after the :root plugin. Please load the :root plugin first"
@@ -64,6 +63,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         serializer_class.extend(ClassMethods)
         serializer_class.include(InstanceMethods)
@@ -91,6 +91,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.after_load_plugin(serializer_class, **_opts)
         serializer_class.config.opts[:metadata] = {attribute_keys: %i[const hide_nil hide_empty value]}
       end
@@ -183,6 +184,7 @@ class Serega
       #
       # @see Serega
       #
+      # @private
       module InstanceMethods
         private
 

data/lib/serega/plugins/metadata/validations/check_block.rb

@@ -7,6 +7,7 @@ class Serega
         #
         # Validator for meta_attribute block parameter
         #
+        # @private
         class CheckBlock
           class << self
             #

data/lib/serega/plugins/metadata/validations/check_opt_const.rb

@@ -7,6 +7,7 @@ class Serega
         #
         # MetaAttribute `:const` option validator
         #
+        # @private
         class CheckOptConst
           class << self
             #

data/lib/serega/plugins/metadata/validations/check_opt_hide_empty.rb

@@ -7,6 +7,7 @@ class Serega
         #
         # Validator for meta_attribute :hide_empty option
         #
+        # @private
         class CheckOptHideEmpty
           class << self
             #

data/lib/serega/plugins/metadata/validations/check_opt_hide_nil.rb

@@ -7,6 +7,7 @@ class Serega
         #
         # Validator for meta_attribute :hide_nil option
         #
+        # @private
         class CheckOptHideNil
           class << self
             #

data/lib/serega/plugins/metadata/validations/check_opt_value.rb

@@ -7,6 +7,7 @@ class Serega
         #
         # Validator for meta_attribute :value option
         #
+        # @private
         class CheckOptValue
           class << self
             #

data/lib/serega/plugins/metadata/validations/check_opts.rb

@@ -7,6 +7,7 @@ class Serega
         #
         # Validator for meta_attribute options
         #
+        # @private
         class CheckOpts
           class << self
             #

data/lib/serega/plugins/metadata/validations/check_path.rb

@@ -7,6 +7,7 @@ class Serega
         #
         # Validator for meta_attribute :path parameter
         #
+        # @private
         class CheckPath
           # Regexp for valid path
           FORMAT = /\A[\w~-]+\z/

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

@@ -15,12 +15,10 @@ class Serega
     # - The original object is accessible via __getobj__ (standard SimpleDelegator API).
     # - The serialization context is accessible via the private method __ctx__.
     #
-    # Objects are wrapped in the Presenter only when the serializer's Presenter
-    # class (or an inherited one) was actually extended with custom methods —
-    # a bare `plugin :presenter` adds no wrapping overhead. The check is
-    # denormalized: `SerializerClass.custom_presenter?` is asked once per
-    # object serializer and the result is reused for the whole level.
+    # The `presenter do ... end` block is evaluated inside the serializer's own
+    # Presenter class, so multiple blocks accumulate.
     #
+    # @example
     #   class UserSerializer < Serega
     #     plugin :presenter
     #
@@ -38,10 +36,9 @@ class Serega
     #     end
     #   end
     #
-    # The `presenter do ... end` block is evaluated inside the serializer's own
-    # Presenter class, so multiple blocks accumulate.
     module Presenter
       # @return [Symbol] Plugin name
+      # @private
       def self.plugin_name
         :presenter
       end
@@ -54,6 +51,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         serializer_class.extend(ClassMethods)
         serializer_class::SeregaObjectSerializer.include(SeregaObjectSerializerInstanceMethods)
@@ -67,6 +65,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.after_load_plugin(serializer_class, **_opts)
         presenter_class = Class.new(Presenter)
         presenter_class.serializer_class = serializer_class
@@ -79,8 +78,10 @@ class Serega
       end
 
       # Presenter class
+      # @private
       class Presenter < SimpleDelegator
         # Presenter instance methods
+        # @private
         module InstanceMethods
           #
           # @param object [Object] Serialized object to wrap
@@ -187,6 +188,7 @@ class Serega
         #
         # @return [Boolean] whether custom presenter methods were defined
         #
+        # @private
         def custom_presenter?
           self::Presenter.modified?
         end
@@ -207,6 +209,7 @@ class Serega
       #
       # @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.

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

@@ -5,7 +5,7 @@ class Serega
     #
     # Plugin :root
     #
-    # Allows to add root key to your serialized data
+    # Adds a root key to serialized data.
     #
     # Accepts options:
     #  - :root - specifies root for all responses
@@ -16,14 +16,12 @@ class Serega
     #   - config.root.one
     #   - config.root.many
     #   - config.root.one=
-    #   - config.root_many=
+    #   - config.root.many=
     #
     # Default root is `:data`.
     #
-    # Root also can be changed per serialization.
-    #
-    # Also root can be removed for all responses by providing `root: nil`. In this case no root will be added to response, but
-    # you still can to add it per serialization
+    # Root can also be changed per serialization, or removed entirely by
+    # providing `root: nil` (per serialization it can still be added back).
     #
     # @example Define plugin
     #   class UserSerializer < Serega
@@ -56,6 +54,7 @@ class Serega
       ROOT_DEFAULT = :data
 
       # @return [Symbol] Plugin name
+      # @private
       def self.plugin_name
         :root
       end
@@ -67,6 +66,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.before_load_plugin(serializer_class, **opts)
         allowed_keys = %i[root root_one root_many]
         opts.each_key do |key|
@@ -88,6 +88,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         serializer_class.extend(ClassMethods)
         serializer_class.include(InstanceMethods)
@@ -103,6 +104,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.after_load_plugin(serializer_class, **opts)
         config = serializer_class.config
         default = opts.fetch(:root, ROOT_DEFAULT)
@@ -214,6 +216,7 @@ class Serega
       #
       # @see Serega
       #
+      # @private
       module InstanceMethods
         #
         # Serializes provided object to a tree of Ruby Data objects.
@@ -226,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)
@@ -261,6 +266,7 @@ class Serega
       #
       # @see Serega::SeregaDataBuilder
       #
+      # @private
       module DataBuilderClassMethods
         #
         # @param serializer [Serega] Serializer instance carrying the plan

data/lib/serega/plugins/string_modifiers/parse_string_modifiers.rb

@@ -22,6 +22,7 @@ class Serega
       #
       # Modifiers parser
       #
+      # @private
       class ParseStringModifiers
         COMMA = ","
         COMMA_CODEPOINT = COMMA.ord

data/lib/serega/plugins/string_modifiers/string_modifiers.rb

@@ -2,8 +2,27 @@
 
 class Serega
   module SeregaPlugins
+    #
+    # Plugin :string_modifiers
+    #
+    # Allows `:only`, `:except` and `:with` to be given as a single comma-separated
+    # string, with nested attributes in parentheses. Useful for accepting a field
+    # list straight from a query parameter.
+    #
+    # @example
+    #   class UserSerializer < Serega
+    #     plugin :string_modifiers
+    #
+    #     attribute :username
+    #     attribute :first_name
+    #     attribute :addresses, serializer: AddressSerializer, hide: true
+    #   end
+    #
+    #   UserSerializer.to_h(user, only: "username,addresses(line1,line2)")
+    #
     module StringModifiers
       # @return [Symbol] Plugin name
+      # @private
       def self.plugin_name
         :string_modifiers
       end
@@ -16,6 +35,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def self.load_plugin(serializer_class, **_opts)
         serializer_class.include(InstanceMethods)
         require_relative "parse_string_modifiers"
@@ -26,6 +46,7 @@ class Serega
       #
       # @see Serega
       #
+      # @private
       module InstanceMethods
         private
 

data/lib/serega/plugins.rb

@@ -17,6 +17,7 @@ class Serega
       #
       # @return [void]
       #
+      # @private
       def register_plugin(name, mod)
         @plugins[name] = mod
       end
@@ -36,6 +37,7 @@ class Serega
       #
       # @return [Class<Module>] Plugin core module
       #
+      # @private
       def find_plugin(name)
         return name if name.is_a?(Module)
         return @plugins[name] if @plugins.key?(name)

data/lib/serega/utils/collection_detector.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaUtils
     #
     # Utility to check if an object should be serialized as a collection.
@@ -8,6 +9,7 @@ class Serega
     # Hashes and Structs are Enumerable, but enumerate their own member
     # values, so they are treated as single objects.
     #
+    # @private
     class CollectionDetector
       class << self
         #

data/lib/serega/utils/enum_deep_dup.rb

@@ -4,11 +4,13 @@ class Serega
   #
   # Utilities
   #
+  # @private
   module SeregaUtils
     #
     # Duplicates nested hashes and arrays
     # It does not duplicate any non-Array and non-Hash values
     #
+    # @private
     class EnumDeepDup
       class << self
         #

data/lib/serega/utils/enum_deep_freeze.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Utilities
   #
+  # @private
   module SeregaUtils
     #
     # Utility to freeze nested hashes and arrays
     #
+    # @private
     class EnumDeepFreeze
       class << self
         #

data/lib/serega/utils/method_signature.rb

@@ -4,10 +4,12 @@ class Serega
   #
   # Utilities
   #
+  # @private
   module SeregaUtils
     #
     # Utility to make method arguments signature
     #
+    # @private
     class MethodSignature
       SYMBOL_TO_PROC_SIGNATURE_RUBY2 = [[:rest]]
       SYMBOL_TO_PROC_SIGNATURE_RUBY3 = [[:req], [:rest]]

data/lib/serega/utils/serialized_attribute_error.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaUtils
     #
     # Reraises an error, adding which attribute and serializer were being
@@ -8,6 +9,7 @@ class Serega
     # and the batch attach phase so the message stays identical for every
     # attribute, whether its value is resolved inline or during batch loading.
     #
+    # @private
     module SerializedAttributeError
       module_function
 

data/lib/serega/utils/symbol_name.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaUtils
     #
     # Utility to get frozen string from symbol in any ruby version
     #
+    # @private
     class SymbolName
       class << self
         #

data/lib/serega/utils/to_hash.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaUtils
     #
     # Utility to transform almost anything to Hash
     #
+    # @private
     class ToHash
       class << self
         #

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

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
     #
     # Attribute parameters validators
     #
+    # @private
     module Attribute
       #
       # Attribute `block` parameter validator
       #
+      # @private
       class CheckBlock
         # Explains the changed attribute block behavior. Shown when the block
         # looks like an old-style value block — it accepts parameters or