serega 0.40.0 → 0.40.1

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.
@@ -261,6 +264,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

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `name` parameter validator
       #
+      # @private
       class CheckName
         # Regexp for valid attribute name
         FORMAT = /\A[\w~-]+\z/

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:base_serializer` option validator
       #
+      # @private
       class CheckOptBaseSerializer
         class << self
           #

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:batch` option validator
       #
+      # @private
       class CheckOptBatch
         class << self
           #

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:const` option validator
       #
+      # @private
       class CheckOptConst
         class << self
           #

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:delegate` option validator
       #
+      # @private
       class CheckOptDelegate
         class << self
           #

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:hash_access` option validator
       #
+      # @private
       class CheckOptHashAccess
         class << self
           #

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:hide` option validator
       #
+      # @private
       class CheckOptHide
         #
         # Checks attribute :hide option

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:many` option validator
       #
+      # @private
       class CheckOptMany
         class << self
           #

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:method` option validator
       #
+      # @private
       class CheckOptMethod
         class << self
           #

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Validator for attribute :preload option
       #
+      # @private
       class CheckOptPreload
         class << self
           #

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 class Serega
+  # @private
   module SeregaValidations
+    # @private
     module Attribute
       #
       # Attribute `:serializer` option validator
       #
+      # @private
       class CheckOptSerializer
         class << self
           #